Token Handler

Token Handler applications act as OAuth Agents as defined in the Token Handler pattern. Learn more about the Token Handler pattern on the Token Handler Overview guide.

Configuring a Token Handler Application#

The configuration is divided in two parts:

• Configuration of OAuth Agent on the left
• Configuration of OAuth Proxy on the right

OAuth Agent 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 is the URL that the SPA will be running on. This setting is used to allow cross-origin resource sharing (CORS) requests from the SPA (all requests from the SPA to this token handler application will be cross-origin).

The optional Backend for Frontend Parent Domain is only needed when the OAuth Agent and the OAuth Proxy will be running on different subdomains.

Each token handler application needs to use an Authorization Server to authenticate and authorize users. The Use External OAuth Server switch button enables administrators to choose between two modes:

• button is in the off state - this means that the token handler application will use this instance of the Curity Identity Server to authenticate users and get/refresh tokens. This option requires that the current Application profile is linked to a Token profile (this can be done on the General page). When this option is selected, a new client needs to be created just for the purposes of this token handler application. The client can be created via a dedicated modal window by clicking the + New Internal Client button. This ensures that the client has the correct configuration to be used with the token handler application (e.g. it has to have a symmetric key authentication configured). One thing to note: Client Redirect URI must be hosted under the configured SPA Base URL. It can be configured to the SPA’s base URL, or to any SPA’s sub-path (e.g. https://www.example.com/path). The SPA developers need to be aware that they have to handle the authorization response redirect on this sub-path. The configured client will be used to 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 log out the users.

• button is in the on state - this means that the token handler application will use an external Authorization Server to authenticate users and get/refresh tokens. This server can be any Authorization Server that supports authorization code flow.

SPAs may want to send extra parameters in authorization requests. The only parameter that is always allowed to be sent by SPAs is scope. Any other parameters (e.g. ui_locales or login_hint) have to be enabled using the Authorization Parameters Whitelist component. Any parameters listed in this component can be sent by SPAs in the login/start requests (described below).

Likewise, SPAs may want to send extra parameters in token refresh requests. Such parameters have to be allowed in the Refresh Parameters Whitelist section (except for scope, which is always allowed). The parameters can then be sent by SPAs in refresh requests (described below) and will be included in the request to the Authorization Server’s token endpoint.

Token handler applications will call the token endpoint on the configured authorization server. If a specific TLS trust is needed to connect to the server (e.g. the server is using self-signed certificates in pre-production environments) then an HTTP Client with a correctly configured client trust store has to be created and used (the trust store with the certificates the server is using).

To limit the exposure of cookies created by a token handler application, the path attribute is set on the relevant cookie with a value that matches the URL path to the token handler application that created the cookie (e.g. /<APP_ANONYMOUS_ENDPOINT>/<TOKEN_HANDLER_APP_ID>). This makes browsers send the cookie only to the token handler application (and not to a token handler proxy). In case there’s an HTTP reverse proxy in front of the Curity Identity Server and this proxy rewrites the path to the token handler application, the Curity Identity Server admin can override the value that is set in the path attribute of the cookie using the Session Cookie Path configuration setting.

It’s recommended to enable the Require Custom Header setting. It will make all the endpoints require a custom HTTP header: token-handler-version=1. When enabled, this header has to be sent in all token handler application requests. If not sent, the requests will be rejected. Requiring this header strengthens the security of token handler applications in cross-origin deployments by enforcing the browsers to send CORS pre-flight requests, thus enabling the token handler application to authorize a request prior to executing it. It prevents a sort of cross-site request forgery (CSRF) attacks based on CORS-safe listed requests. Starting from version 2.0 of each token handler proxy (e.g. Kong, Apigee, etc.), all proxies require this header as well. Refer to each token handler proxy documentation for details.

OAuth Proxy Configuration#

For an Oauth Proxy, an elliptic-curve public key has to be configured. This key is taken from an asymmetric keypair where the public key is used here, by the Token Handler application to encrypt the cookie that will be sent to the OAuth Proxy, whereas the private key of the keypair is used on the Proxy side to decrypt the cookie.

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

SPA Integration#

To help SPA developers interact with OAuth Agents (token handler application plugins), Curity developed a lightweight JavaScript library. Refer to the library documentation for details on how to use it. The library will help SPA developers with calling the endpoints of token handler applications.

Starting from version 1.1.0, the library also includes the token-handler-version header in all requests to token handler applications (this header is enforced in a token handler application by enabling the Require Custom Header setting). SPAs are required to also send this header in all requests to a token handler proxy (starting from version 2.0 of all token handler proxies).