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.
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.
Fig. 41 Listing all applications.
Fig. 42 Adding a Token Handler application.
After a Token Handler application is created, it needs to be configured in the edit application modal.
Fig. 43 Configure a Token Handler application.
The configuration is divided into two parts:
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).
Single Page Application Base URL
The optional Backend for Frontend Parent Domain is only needed when the OAuth Agent and the OAuth Proxy will be running on different subdomains.
Backend for Frontend Parent Domain
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:
Use External OAuth Server
off
General
+ New Internal Client
Client Redirect URI
https://www.example.com/path
Fig. 44 Create a new internal client for token handler application.
on
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).
scope
ui_locales
login_hint
Authorization Parameters Whitelist
login/start
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).
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.
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
POST login/end
GET session
POST refresh
POST logout
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:
<BASE_URL>/<APP_ANONYMOUS_ENDPOINT>/<TOKEN_HANDLER_APP_ID>
https://example.com
/apps-anonymous
token-handler1
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
To help SPA developers to interact with OAuth Agents (token handler application plugins), Curity developed a lightweight JavaScript library.