📘

The content on this page deals with a legacy feature of the ​Akamai​ Identity Cloud (in this case, the JavaScript SDK). If you are currently an Identity Cloud customer and are using the JavaScript SDK, that SDK is still supported. However, if you’re new to the Identity Cloud the JavaScript SDK is no longer available. Instead, you should use Hosted Login for your login and registration needs.

​Akamai​'s Registration UI and Single Sign-On products are client-side web applications that generate access tokens when a user is authenticated to create a client-side “session”. A session is only dependent on the presence of a valid access token stored in the user’s browser and is not connected to a server-side session without integration on the customer’s side. The overview and more detailed sections below should help you determine whether server-side session management is required for your use cases. See JavaScript SDK access tokens and codes for more detail on each of the tokens referenced.

Client-side “sessions” may require less integration effort if you do not require server-side integration. However, ​Akamai​ does not provide a refresh token client-side, so the “session” will expire unless a new token is generated server-side. Outside of the code-for-token exchange, an API client with the access_issuer feature must be used to generate an access token.

Server-side session management requires more integration effort but is potentially more secure. The user’s access token does not have to be exposed client-side, but if users need to be able to access profile screens you will need to implement code placing an access token into localStorage when necessary. In the code-for-token exchange, you can use the same API client with the login_client feature client-side for authentication and server-side for refreshing access tokens.

Client-side sessions

By default, the Identity Cloud Registration UI is configured to return an access token after successful authentication. This is configured by setting the janrain.settings.capture.responseTypesetting to token. With this approach, the access token is returned client­-side and included in the response for the onCaptureSessionCreated and onCaptureLoginSuccess event handlers, and placed in the localStorage key janrainCaptureToken. See Registration JavaScript API events for details.

An access token being present in localStorage tells the Registration UI that there is an active “session” for the user, which allows access to screens configured to display user data, such as the editProfile screen.

The client­-side “session” will expire when the access token expires, one hour by default, and refresh tokens are not available for use client-side. In order to access screens that require an access token, the end user will need to reauthenticate through the Registration UI.

Alternately, the customer can implement server-side logic to extend the client-side “session” on the user’s behalf:

• After a user successfully logs in, collect the uuid, access token, and expiration time from the onCaptureLoginSuccess event response and store them server-side.

• When the access token expires, use the uuid to make a server-side call to the access/getAccessToken operation to generate a new access token.

• Pass the new access token to the client-side JavaScript function createCaptureSession, which will place it in the janrainCaptureToken key along with a new expiration time.

Server-side sessions

Although it requires a larger integration effort, a “code­-for­-token” solution is ideal for a higher level of security or tight integration with back­end session management. The Registration UI can be set to return a one-time authorization code rather than an access token by setting the janrain.settings.capture.responseType JavaScript setting to code. With this approach, the authorization code is returned in the response for the onCaptureSessionCreated and onCaptureLoginSuccess event handlers.

The authorization code must then be passed to a server and exchanged for an access token and refresh token, which must be stored in the server session and refreshed as needed using the oauth/token operation. With this approach, the access token is not placed in localStorage, which means there is no client­-side “session”.

A customer using the Registration UI can optionally create a client­-side session when performing the code-for-token exchange.

When a user interacting with the Registration UI attempts an action that requires an access token (e.g. save profile), the onCaptureExpiredToken, onCaptureInvalidToken, or onCaptureAccessDenied event handlers will fire depending on the scenario. These event handlers can be used to call a server-side script to generate a new valid access token, pass it back to the client-side JavaScript function createCaptureSession, and re-attempt the action.

To avoid expired access tokens, this server code should be used with each page load (or server request) to check the access token stored in the session and refresh it if it has expired. In this way, the sever session is “managing” the access token and will have a valid access token for as long as the session is valid.

The end­-user can use the Registration UI to log out, which will fire the onCaptureSessionEnded event handler. This can be used to send a request to the server to kill the session.