24.15.1Session Management

The concepts of logout and user sessions are a little bit different when using an external SMART identity server such as the Smile CDR Outbound Security module. This is because a user can log out of a client application (whether by actively signing out of it, or simply by leaving it inactive for a period of time) but can effectively remain signed in to the authorization server.

This might be for one of several reasons:

• The user might still have an active user session with the Authorization Server, even though their user session in the client application is inactive. This would mean that the user could effectively log back in without being prompted for credentials again.
• The client application might have a refresh token and therefore be able to make background queries on behalf of the user even though they are not actively using the application.

24.15.2Token Revocation Endpoint

The SMART Outbound Security module implements the Token Revocation Endpoint, as specified in RFC 7009. This endpoint allows a client to request that a specific token be revoked, such that it may no longer be used by the client.

A simple example is shown below:

POST /session/token/revoke
Content-Type: application/x-www-form-urlencoded

token=ew9t4p98yy4tyetwhfmd9e8jr.ffiofhiofeshldflsdflhfdlhfdsldfihfd

The request should have the following parameters, which are transmitted in the request body using a Content-Type of application/x-www-form-urlencoded:

• token – The token to revoke (may be an access token or a refresh token).
• token_type – (optional) A hint to the server indicating which type the token actually is. This parameter is only an optimization, so it is not required, but it is nonetheless recommended that it be supplied in order to minimize the load on the server. Valid values are: access_token and refresh_token.

If the token was granted to a confidential client (a client configured as Client Required to Authenticate), the request must also contain an Authorization header authenticating the client. For example:

Authorization: Basic [base64 of "client-id:client-secret"]

24.15.3User Logout Endpoint

The SMART Outbound Security module also contains an endpoint that can be used to request that the user's session be cleared. This prevents any further tokens from being issued for this user until the user is prompted to log in once again.

24.15.3.1Configuration Requirements

Enabling the User Logout Endpoint requires a few configuration settings in the SMART Outbound Security module:

• The CORS Enabled property must be set to true.
• The CORS Origins property must include a list of domains where a Logout request can originate. For example, if the SMART Outbound Security module is being used to authenticate users logging into an appSphere App Management Console or Developer Portal, then the base server URLs being used to access the Management Console and Developer Portal would need to be included in the CORS Origins list. The CORS Origins value must not be set to *, per the CORS specification.
• The Respect Forward Headers property may need to be set to true if the User Logout Endpoint is being routed through a proxy server such as NGINX.

24.15.3.2Submitting a User Logout Request

The User Logout Endpoint is located at /logout on the SMART Outbound Security module server.

The following example shows a call to the User Logout Endpoint. Typically this call is invoked via an AJAX request.

POST /logout?cb=none&revoke=token&revoke=token_refresh
Authorization: Bearer [access token]
Cookie: Master_smart_auth_SESSIONID=node01f2e96vxo

As shown in the example above, the request must include a session cookie, which will be a cookie with a name resembling [node_id]_[module_id]_SESSIONID. This is typically added to the request automatically by the browser. Note that cookies need to be enabled in the browser for this functionality to work.

Also when invoking the logout endpoint via an AJAX request, you must set the withCredentials flag on the request. See the relevant MDN header documentation for more information.

Finally, the request must include an Authorization header containing a valid access token.

The server will respond with an HTTP 204 No Content indicating that the user's session has been closed.

The request has the following parameters:

• cb – This indicates what should be returned by the API after the logout is complete. At this time the only valid value is none. Other options may be added in the future.
• revoke – (optional) If specified, this parameter may be used to signal to the API that the access/refresh tokens associated with this user should also be revoked.
  • "token" - Revoke the access token.
  • "token_refresh" - Revoke the refresh token associated with the access token. This will also revoke any access tokens associated with the given refresh token.