login

Use the login method to log an existing user in to the Convio-powered site based on a user_name and password or to send those credentials to the user by email.

Client Servlet Server Servlet HTTP Methods Supported Requires Authentication
CRConsAPI SRConsAPI POST Server.

Client API Syntax

https://secure2.convio.net/organization/site/CRConsAPI?method=login &api_key=value &v=value [ &center_id=value ] [ &error_redirect=value ] [ &redirect=value ] [ &response_format=xml | json ] [ &sign_redirects=value ] [ &source=value ] [ &sub_source=value ] [ &success_redirect=value ] [ &suppress_response_codes=value ] [ &email=value ] [ &logout=value ] [ &password=value ] [ &remember_me=value ] [ &send_user_name=value ] [ &user_name=value ]

Server API Syntax

https://secure2.convio.net/organization/site/SRConsAPI?method=login & api_key =value & login_name =value & login_password =value & v =value [ & center_id =value ] [ & response_format =xml |json ] [ & source =value ] [ & sub_source =value ] [ & suppress_response_codes =value ] [ & email =value ] [ & logout =value ] [ & password =value ] [ & remember_me =value ] [ & send_user_name =value ] [ & user_name =value ]

Usage Notes

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.

This API is generally invoked by sending a redirect from server code or in an onload JavaScript action.

Even though this API is actually invoked over a secure URL, you should invoke the API using the insecure domain for the client and allow Luminate Online to redirect the API call to the secure domain. This will ensure that if the user has only established a session on the insecure domain that it will be checked first. It also ensures that the API checks for a login cookie on both the insecure and secure domains before providing the response. Failure to follow this convention will result in the API erroneously flagging users as not being logged in.

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 and password for the user and send them to a previously-registered email address.

See also authenticateUser, loginTest, and logout.

Client API Parameters

Common Client Parameters

See topic Common Parameters.

email

Optional. Email address to which to send user name and password if 'send_user_name=true'

Type xsd:string.

logout

Optional. If 'true,' closes the current session and logs the user out. Equivalent to the logout method.

Type xsd:boolean.

Default is false.

password

Optional. Password of the constituent to log in.

Type xsd:string.

remember_me

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.

send_user_name

Optional. If 'true', sends the user's user name and password to the address specified in the 'email' parameter if the email address matches one that is registered for the user.

Type xsd:boolean.

Default is false.

user_name

Optional. User name of the constituent to log in.

Type xsd:string.

Server API Parameters

Common Server Parameters

See topic Common Parameters.

email

Optional. Email address to which to send user name and password if 'send_user_name=true'

Type xsd:string.

logout

Optional. If 'true,' closes the current session and logs the user out. Equivalent to the logout method.

Type xsd:boolean.

Default is false.

password

Optional. Password of the constituent to log in.

Type xsd:string.

remember_me

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.

send_user_name

Optional. If 'true', sends the user's user name and password to the address specified in the 'email' parameter if the email address matches one that is registered for the user.

Type xsd:boolean.

Default is false.

user_name

Optional. User name of the constituent to log in.

Type xsd:string.

Response

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>1374178604</timestamp>
  <signature>7bf20fd9d09f8a9a607facd5e71c4e47</signature>
  <token xsi:nil="true"/>
</loginResponse>

        
JSON response
{"loginResponse":{"timestamp":"1374178604","token":null,"cons_id":"1001002","signature":"7bf20fd9d09f8a9a607facd5e71c4e47"}}

        

Examples

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 will be posted to the API. In the event of a correct username/password combination, a session will be established on Luminate Online and the user's browser will be redirected back to the partner system. The redirect will contain 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 will be 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

Submitted by matt at 10:26 AM on February 22, 2012
If you are on Luminate the send_user_name parameter no longer sends the user's password. Instead they are given a link to reset their password.

Leave a Comment

Nickname
Comment
Enter this word: