Authentication

Janrain Engage supports two different end user authentication models: Server-Side and Client-Side. Server-Side Authentication requires a page refresh. If your login page is media rich, the refresh will be resource expensive and time consuming, so you might want to use Client-Side authentication instead.

Short Cut ¶

If you are not interested in the details of how user authentication works, you can skip ahead to either the Server-Side Authentication or Client-Side Authentication pages.

Authentication Details ¶

In either case, the Engage Widget resides on your login page, which may or may not be your home page. That’s up to you. Place the link where you want users to sign in to your website.

Refer to Figure 1 below for the following steps. When an end user clicks on the Engage Widget (1), chooses a login provider, and enters their password, the Widget makes a call (2) to the Janrain Engage Servers, which make a call to the identity provider (3), for this example, Acme Social. Acme then performs its authentication routine and makes a callback (4) to the Janrain Engage Servers. So the actual authentication takes place on the Acme servers.

The Engage Widget on your site listens for this callback. When it arrives (5), the Widget makes a call to the Engage Servers (6), using JSONP over an SSL connection, so it remains secure. Our Janrain Servers then return the One-Time Token to the Widget (7), also as JSONP. All of this communication occurs very rapidly.

Whether you use the Token URL page or some other page, this page must hold your apiKey and the One-Time Token that the Janrain servers return to the widget in step 7 of the diagram.

Here is where the difference between Server-Side Authentication and Client-Side Authentication comes into play.

At this point, the Widget makes a call to either the Token URL page (8S) or Your Server page (8C) to supply the page with the One-Time Token. For the Token URL page, this call is an HTTP POST. For the call to Your Server page, the call is an AJAX call (or other technology).

Your Token URL page (9s) or Your Server page (9c) makes an auth_info call to the Janrain servers, with the apiKey and One-Time Token to retrieve the information. The Janrain servers then return the information (10S) (10C) to whichever page sent it.

At a minimum, auth_info returns a single object containing the user’s profile. Depending on which optional parameters you use and the services offered by the identity provider, this call can also return various other objects. For more details, refer to the auth_info documentation.

Figure 1: Authentication Flow

If you use Server-Side Authentication, the Token URL page makes an HTTP POST (11S) to the login page, which causes a full refresh of the login page. If your login page is media rich, the refresh will take a lot of time and resources.

If you use Client-Side Authentication, Your Server page makes an AJAX (or similar) call (11C) to your login page, which does not require a page refresh. You will have to implement this code, and you can use whatever you want. So long as you do not require a full page refresh, you will improve performance, while maintaining security.

Security Issue: Make sure that your apiKey is never available on any public page. If a malicious user gains access to your apiKey, they could steal data from your website, or even make changes to your website.

Next Step ¶

Go to either the Server-Side Authentication or Client-Side Authentication for implementation details.