Experimental

Token Handler Application

Note

This is an experimental feature.

Token Handler application plugin helps with implementing the Token Handler pattern for Single Page Applications (SPAs). Learn more about the Token Handler pattern from our resource library articles.

Creating a Token Handler Application

Token Handler applications act as OAuth Agents as defined in the Token Handler pattern. Token Handler applications are configured in an application service profile, more specifically on the applications list. The following two figures illustrate listing and adding a Token Handler application.

../../_images/application-list.png

Fig. 41 Listing all applications.

../../_images/application-create.png

Fig. 42 Adding a Token Handler application.

Configuring a Token Handler Application

After a Token Handler application is created, it needs to be configured in the edit application modal.

../../_images/configure-token-handler.png

Fig. 43 Configure a Token Handler application.

The configuration is divided into two parts. On the left, there’s an SPA related configuration. Typically, a single Token Handler application will handle one SPA, so it needs to be configured as such. The Single Page Application Base URL and Backend for Frontend Base URL are the domains that an SPA and an OAuth Proxy is running on. They have to share the same eTLD+1 domain so that the Token Handler cookies will be passed by the browser to both the OAuth Agent and the OAuth Proxy.

Next, there’s a picker for the OAuth Server, whose value can be set to internal-client only at this moment. The value internal-client means that this Token Handler application will leverage the Curity Identity Server’s client (defined in the linked OAuth profile) to run the OAuth flows. The client will run the code flow with PKCE to authenticate the user. It will run the refresh flow to refresh access tokens. And it will run the RP-initiated logout flow to logout the user.

Note

In the future, it will be possible to configure a Token Handler application with an external OAuth server as well.

The client to be used is picked in the Client dropdown. The client has to be defined in advance in the linked OAuth profile and it has to be configured in a specific way, namely:

  • the code flow capability has to be allowed
  • the client has to have a single redirect_uri
  • the redirect_uri has to be the same as the Single Page Application Base URL (or it can be a sub-path under this URL)
  • the client authentication has to be set to symmetric-key

On the right, there’s a configuration related to an OAuth Proxy. An asymmetric key has to be configured. This key will be used by the Token Handler application to encrypt proxy cookies that will be sent over to the OAuth Proxy. OAuth Proxy will have to be configured with the private key part of this asymmetric key.

Token Handler Application API

A token handler application will expose an API that SPAs can call to actually use the Token Handler pattern. The API will be exposed on the application anonymous endpoint that was created in the same application profile as the Token Handler application. Each Token Handler application exposes five endpoints under these paths:

  • POST login/start - starts the login and returns the authorization URL. SPAs are supposed to redirect the user to the returned URL.
  • POST login/end - supposed to be called after the user has authenticated. Finishes the login. The request body should contain url encoded authorization response parameters returned by the authorization server in the redirect URI.
  • GET session - returns claims that are in the ID token of the currently logged in user.
  • POST refresh - runs the refresh token flow and renews the access token.
  • POST logout - logouts the user (removing the Token Handler cookies) and responds with a single logout URL (if configured).

These endpoints will be exposed under the path <BASE_URL>/<APP_ANONYMOUS_ENDPOINT>/<TOKEN_HANDLER_APP_ID>. Assume the Curity Identity Server’s base URL is set to https://example.com, the application profile’s anonymous endpoint is exposed with /apps-anonymous path and a Token Handler application with id token-handler1 is created. Then the API will be exposed under these paths:

  • https://example.com/app-anonymous/token-handler1/login/start
  • https://example.com/app-anonymous/token-handler1/login/end
  • https://example.com/app-anonymous/token-handler1/session
  • https://example.com/app-anonymous/token-handler1/refresh
  • https://example.com/app-anonymous/token-handler1/logout

Limitations

The Token Handler application currently works only when opaque access tokens are used.