Use the login method to log an existing user in to the Luminate Online-powered site based on a user_name and password or to send the Send User Name autoresponder to the user.
| Client Servlet | Server Servlet | HTTP Methods Supported | Requires Authentication |
|---|---|---|---|
| CRConsAPI | SRConsAPI | POST | Server. |
The login method permits users to log in to Luminate Online and establish a session. If the user successfully logs in, this method returns the user's Constituent ID and an authorization token that can be used access other APIs that require authentication during the logged-in user's current session.
When the login method is successfully called from a client using the Client API, it will log in the session that processes the request for that user. It will also attempt to push a session cookie to the user's browser. When called with the redirect or success_redirect parameters, it may process an intermediate redirect in order to ensure that session cookies are pushed for both the secure and insecure domains.
When the login method is successfully called from a server using the Server API, it will not change the state of the session that processes the request nor will it attempt to push session cookies.
The send_user_name and email parameters may be used to retrieve a forgotten user name for the user and send them to a previously-registered email address. This triggers sending the "Send User Name" autoresponder to the email address specified, if that email address is associated with an existing active constituent record, or the "Unknown Email Address" autoresponder if the email address is not associated with an existing active constituent record. The contents of these autoresponders can be configured by administrators in the Autoresponder Center of the site.
See also authenticateUser, loginTest, and logout.
See topic Common Parameters.
Optional. If the 'send_user_name' parameter is 'true,' a Send User Name autoresponder email is sent to the email address specified in this parameter. The autoresponder contains the user name as well as a password reset link. If this email address does not match an email address associated with an active constituent record for this user, then 'Unknown Email Address' autoresponder is sent.
Type xsd:string.
Optional. If 'true,' closes the current session and logs the user out. Equivalent to the logout method.
Type xsd:boolean.
Default is false.
Optional. Password of the constituent to log in.
Type xsd:string.
Optional. If set, a log-in cookie is pushed to the browser to recognize the current user on his next visit.
Type xsd:boolean.
Default is false.
Optional. When 'true', the "Send User Name" autoresponder email containing the user name of the user and password reset link is sent to the email address listed in the email parameter, as long as the email address matches an email address recorded for the user in an existing active constituent record. If the email address does not match an email address with an existing active constituent record, an "Unknown Email Address" autoresponder email is sent.
Type xsd:boolean.
Default is false.
Optional. User name of the constituent to log in.
Type xsd:string.
See topic Common Parameters.
Optional. If the 'send_user_name' parameter is 'true,' a Send User Name autoresponder email is sent to the email address specified in this parameter. The autoresponder contains the user name as well as a password reset link. If this email address does not match an email address associated with an active constituent record for this user, then 'Unknown Email Address' autoresponder is sent.
Type xsd:string.
Optional. If 'true,' closes the current session and logs the user out. Equivalent to the logout method.
Type xsd:boolean.
Default is false.
Optional. Password of the constituent to log in.
Type xsd:string.
Optional. If set, a log-in cookie is pushed to the browser to recognize the current user on his next visit.
Type xsd:boolean.
Default is false.
Optional. When 'true', the "Send User Name" autoresponder email containing the user name of the user and password reset link is sent to the email address listed in the email parameter, as long as the email address matches an email address recorded for the user in an existing active constituent record. If the email address does not match an email address with an existing active constituent record, an "Unknown Email Address" autoresponder email is sent.
Type xsd:boolean.
Default is false.
Optional. User name of the constituent to log in.
Type xsd:string.
See topic HTTP Status Codes.
XML response
<?xml version="1.0" encoding="UTF-8"?>
<loginResponse xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd" xmlns="http://convio.com/crm/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<cons_id>1001002</cons_id>
<timestamp>1454341434</timestamp>
<signature>52a4fa3790b63458a2b0abdb1b70d52d</signature>
<token xsi:nil="true"/>
<nonce xsi:nil="true"/>
<JSESSIONID xsi:nil="true"/>
<routing_id xsi:nil="true"/>
</loginResponse>
JSON response
{"loginResponse":{"routing_id":null,"timestamp":"1454341434","JSESSIONID":null,"nonce":null,"token":null,"cons_id":"1001002","signature":"52a4fa3790b63458a2b0abdb1b70d52d"}}
Logging In
When a user enters a user name and password on a partner site's login page, the partner wants to authenticate with Luminate Online and redirect that user to a content page if successful, or back to the login page if the authentication was unsuccessful.
The solution in this scenario is to design a secure form that uses POST to the login method at this URL:
https://securex.convio.net/[org]/site/CRConsAPI
The form should look something like this:
<form method="post" action="https://securex.convio.net/yoursite/site/CRConsAPI">
<input type="hidden" name="api_key" id="api_key" value="open" />
<input type="hidden" name="v" id="v" value="1.0" />
<input type="hidden" name="method" id="method" value="login" />
<input type="hidden" name="success_redirect" value="http://yourothersite.org/login_page.html?cons_id=" >
<input type="hidden" name="error_redirect" value="http://yourothersite.org/login_page.html?code=&message=" >
<input type="hidden" name="sign_redirects" id="sign_redirects" value="true" />
<table>
<tr>
<td>User Name:</td>
<td><input name=user_name type=text size=15 maxlength="100"></td>
</tr>
<tr>
<td>Password:</td>
<td><input name=password type=password size=15 maxlength="100"></td>
</tr>
<tr>
<td>Remember Me:</td>
<td><input name=remember_me type=checkbox></td>
</tr>
</table>
<input type="submit" value="Submit" name="Submit" />
</form>
When the form is submitted, the data posts to the API. In the event of a correct username/password combination, a session is established on Luminate Online and the user's browser is redirected back to the partner system. The redirect contains the cons_id of the user and the signature. The partner system should then log that user in and display the content provided that the user is authorized. In the event of a login failure, the user's browser is redirected back to the login page with an error message in the URL. The login page should then take that error message from the URL and display it on the page to the user.
Retrieving a Forgotten User Name or Password
When a user has lost or forgotten their user name and password, they expect to be provided some means to retrieve that information from the system, typically through email.
The solution in this scenario is to design a secure form that uses POST to the login method with the option send_user_name=true at this URL:
https://securex.convio.net/[org]/site/CRConsAPI
The form should look something like this:
<form method="post" action="https://securex.convio.net/yoursite/site/CRConsAPI">
<input type="hidden" name="api_key" id="api_key" value="open" />
<input type="hidden" name="v" id="v" value="1.0" />
<input type="hidden" name="method" id="method" value="login" />
<input type="hidden" name="send_user_name" id="send_user_name" value="true" />
<input type="hidden" name="success_redirect" value="http://yourothersite.org/login_page.html?user_name_sent=true" >
<input type="hidden" name="error_redirect" value="http://yourothersite.org/login_page.html?code=&message=" >
<input type="hidden" name="sign_redirects" id="sign_redirects" value="true" />
<table>
<tr>
<td>Email you registered with:</td>
<td><input name=email type=text size=30 maxlength="200"></td>
</tr>
</table>
<input type="submit" value="Submit" name="Submit" />
</form>
If an unregistered email address is provided, the API does not respond with an error. Instead, it emails that address saying that the user is not registered. This response is intended to prevent attempts to mine constituents.
Maintaining Logged-in Status on Luminate Online
One issue with any single sign-on system is maintaining the logged-in state on the two systems. Systems typically expire a session after some period of inactivity. On Luminate Online systems, this time limit is 15 minutes. To keep the session alive, the partner web site only needs to include an image tag that references a servlet on the Luminate Online site:
<img src=http://www.foo.org/site/PixelServer />
This will render a 1x1 clear GIF image. It is desirable to only include this once the user has been logged in to the Luminate Online hosted site.
Because the session cookie has been pushed to the user's browser, any links to the insecure domain (for example, www.foo.org) will automatically connect to the correct session and, as long as the partner site maintains the logged in status, will operate seamlessly for the user. Links directly to the secure URL (for example, https://secure2.convio.net/foo) should not be used from the partner site as it is possible that a session cookie has not been pushed yet. If the partner site links to a page that should be secure, such as a donation form over the insecure domain, the system will automatically redirect and push the secure session cookie at that time.
Comments