@curity/token-handler-js-assistant

token-handler-js-assistant

A helper library to help SPAs interact with the OAuth Agent in the Token Handler pattern.

Add to project

Add to your project using npm

npm install @curity/token-handler-js-assistant

How to use in your project

Import the Assistant into your project and initialize it using Configuration object.

import {OAuthAgentClient} from "@curity/token-handler-js-assistant";
const client = new OAuthAgentClient({oauthAgentBaseUrl: 'https://api.example.com/oauthagent/example'})

The Configuration object contains the following options:

• oauthAgentBaseUrl - a URL with path to the token handler application created in the Curity Identity Server (this URL ends with a token handler application ID as defined in the Curity Identity Server configuration).

Using the initialized client

1. Starting the user login

   const response = await this.oauthAgentClient.startLogin({
     extraAuthorizationParameters: {
       scope: "openid profile", 
       login_hint: "username",
       ui_locales: "en"
     }
   })
   location.href = response.authorizationUrl
   

2. Finishing the user login

   const url = new URL(location.href)
   const response = await client.endLogin({ searchParams: url.searchParams })
   if (response.isLoggedIn) {
    // use id token claims to get username, e.g. response.idTokenClaims?.sub
   }
   

Note: The endLogin function should only be called with authorization response parameters (when the authorization server redirected user to the SPA after a successful user login). It's recommended to call onPageLoad() instead on every load of the SPA. This function makes a decision based the query string and either calls endLogin() or session().

1. Handling page load

   const sessionResponse = await client.onPageLoad(location.href)
   if (sessionResponse.isLoggedIn) {
     // user is logged in
   } else {
     const response = await client.startLogin()
     // redirect the user to the authorization server
     location.href = response.authorizationUrl
   }
   

2. Refreshing tokens

   await client.refresh()
   

3. Retrieving ID token claims

   const sessionResponse = await client.session()
   // use session data
   if (session.isLoggedIn === true) {
    session.idTokenClaims?.sub
   }
   

4. Logging out

   const logoutResponse = await client.logout()
   if (logoutResponse.logoutUrl) {
     // redirect user to the single logout url
     location.href = logoutResponse.logoutUrl;
   }