Curity OAuth Assistant

Add to project

Add to your project using npm

npm install @curity/oauth-assistant

or yarn

yarn add @curity/oauth-assistant

How to use in your project

Initialize Assistant

You need to pass in the settings object in order to initialize Assistant.

Here is an example settings object.

const settings = {
    flow_type      : "code", // Possible values : (code, implicit, assisted_token)
    base_url       : "http://localhost:8443",
    client_id      : "test_client_id",
    issuer         : "https://localhost:8443/oauth/v2/oauth-anonymous",
    redirect_uri   : "http://localhost:8080/assisted.html", // Basic version of assisted.html is available in example/assisted.html but it can be customized as needed.
    for_origin     : "http://localhost:8080",
    iframe         : { // Optional: Passing in null would take default values
        targetElement: null, // targetElement querySelector , default: 'body'
        width   : null, // take default value : 400
        height  : null, // take default value : 700
        style   : null, // take default value
        backdrop: {
            visible      : true, // default is true
            style        : null, // take default value
            backdropClass: ""
        },
        closeButton: {
            visible: true, // default is true
            style  : null, // style for wrapper div of close button
            class  : "",
            button : null
        },
    },
    "popup": {
        "width" :  null,  // take default value : 400
        "height": null   // take default value : 600
    },
    allowed_origins: ["http://localhost:8443", "http://localhost:8080"], // default is [window.origin]
    disable_session_management: false, // Optional: if set to true, session management will be disabled
    check_session_iframe: null, // Optional url, if not provided then it will be resolved from metadata
    session_polling_interval: 5, // Optional: polling interval in seconds, default is 5
    check_session_iframe_events: { // Optional
            onStateChanging: () => {},
            onStateChanged: () => {},
            onLogout: () => {},
            onConsent: () => {},
            onError: () => {},
            onUnchanged: () => {},
    },
    allowed_jwt_algorithms: ['RS256'], // Optional: algorithms to trust for JWT validation
    jwt_sig_public_key: { // allowed formats are jwk | jwks_uri | pem | issuer | metadata_url | raw
        format: 'issuer', // in case of issuer, the issuer value will be taken from jwt payload
        value: null
    },
    ignore_not_before: false, // Optional: controls whether to skip the validation of the nbf claim when validating the ID Token, default is false
    ignore_expiration: false, // Optional: controls whether to skip the validation of the exp claim when validating the ID Token, default is false
    clock_tolerance: 0, // Optional: controls the clock tolerance when validating the ID Token to accomodate drifting clocks, default is 0
    debug: false,  // Optional: Enabling debug to true will display console logs of assistant, default is false
    openid_configuration_url: "https://example.com/path/.well-known/openid-configuration", // Optional: set if the OpenID Configuration URL uses different host or base path than the issuer 
};

More details on settings object is available in the settings section.

Import Assistant into your project and initialize it using settings object.

import Assistant from "@curity/oauth-assistant";
// OR using require 
// const Assistant = require("@curity/oauth-assistant");


const assistant = new Assistant(settings);

assistant.init()
    .then(() => {
        console.log("assistant loaded");
        // Start the authorize flow
    });

Available methods

1. authorize(parameters)
2. authorizeFrame(parameters)
3. authorizeHiddenFrame(parameters)
4. authorizeHiddenFallbackToVisible(parameters)
5. authorizePopup(parameters)
6. authorizeHiddenFallbackToPopup(parameters)
7. getToken()
8. getIDToken()
9. revoke()
10. logout(postLogoutRedirectUri, global)
11. getScope()
12. getExpiresIn()
13. getAdditionalFieds()

After initializing the Assistant, you can start authorize flow using any of the 4 methods available.

To each authorize flow, you can pass in any number of optional parameters like below.

const parameters = {
    scope: "openid",
    state: "state-value",
    response_type: "token id_token",
   ...
};

1. Login with redirect

   assistant.authorize(parameters); 

2. Login with visible iframe

   assistant.authorizeFrame(parameters)
    .then((token) => {})
    .catch((err) => {});

3. Login with hidden iframe

   assistant.authorizeHiddenFrame(parameters)
    .then((token) => {})
    .catch((err) => {});    

4. Login with hidden iframe (fallback to visible iframe if login is required)

   assistant.authorizeHiddenFallbackToVisible(parameters)
    .then((token) => {})
    .catch((err) => {});    

5. Login with visible popup

   assistant.authorizePopup(parameters)
    .then((token) => {})
    .catch((err) => {});

6. Login with hidden flow (fallback to visible popup if login is required)

   assistant.authorizeHiddenFallbackToPopup(parameters)
    .then((token) => {})
    .catch((err) => {});    

Once the authorize flow is complete, you can get the token, id_token or revoke tokens using the Assistant.

Get Token

assistant.getToken();

Get ID Token

assistant.getIDToken();

Revoke Tokens

assistant.revoke()
    .then(() => {})
    .catch((err) => {});

Refresh Tokens If the AS issued a refresh token, use it to obtain new tokens.

assistant.refresh()
    .then(() => {})
    .catch((err) => {});

Logout
Logout the user from server and revoke tokens.
Default value of postLogoutRedirectUri is window.location.href. Default value of global is false, if set to true then it will be sent during logout as an extra query parameter, causing logout to happen globally across all logged in clients.

assistant.logout(postLogoutRedirectUri, global)
    .then(() => {})
    .catch((err) => {});

Get scopes

Get the space-delimited list of scope tokens associated with the last authorization response.

assistant.getScope();

Get expires in

Get the expires_in value associated with the last authorization response.

assisstant.getExpiresIn();

Get additional fields

Get a map of any additional fields associated with the last authorization response. Fields other than access_token, scope, expires_in or id_token.

assistant.getAdditionalFields();

Settings

While initializing Assistant, you need to pass in a settings object which contain some mandatory and optional values.

{
    flow_type      : "code", // Possible values : (code, implicit, assisted_token)
    base_url       : "http://localhost:8443",
    client_id      : "test_client_id",
    issuer         : "https://localhost:8443/oauth/v2/oauth-anonymous",
    redirect_uri   : "http://localhost:8080/assisted.html", // Basic version of assisted.html is available in example/assisted.html but it can be customized as needed.
    for_origin     : "http://localhost:8080",
    iframe         : { // Optional: Passing in null would take default values
        targetElement: null, // targetElement querySelector , default: 'body'
        width   : null, // take default value : 400
        height  : null, // take default value : 700
        style   : null, // take default value
        backdrop: {
            visible      : true, // default is true
            style        : null, // take default value
            backdropClass: ""
        }
    },
    "popup": {
        "width":  null,  // take default value : 400
        "height": null   // take default value : 600
    },
    allowed_origins: ["http://localhost:8443", "http://localhost:8080"], // default is [window.origin]
    disable_session_management: false,
    check_session_iframe: null, // Optional url, if not provided then it will be resolved from metadata
    session_polling_interval: 5, // Optional: polling interval in seconds, default is 5
    check_session_iframe_events: { // Optional
            onStateChanging: () => {},
            onStateChanged: () => {},
            onLogout: () => {},
            onConsent: () => {},
            onError: () => {},
            onUnchanged: () => {},
    },
    allowed_jwt_algorithms: ['RS256'], // Optional: algorithms to trust for JWT validation
    jwt_sig_public_key: { // allowed formats are jwk | jwks_uri | pem | issuer | metadata_url | raw
        format: 'issuer', // in case of issuer, the issuer value will be taken from jwt payload
        value: null
    },
   ignore_not_before: true,
   ignore_expiration: false,
   clock_tolerance: 10,
   debug: false,  // Enabling debug to true will display console logs of assistant
   openid_configuration_url: "https://example.com/path/.well-known/openid-configuration", // Set if the OpenID Configuration URL uses different host or base path than the issuer
};

All fields marked with * are mandatory.

• flow_type* Flow type determines the authorize flow to be used. It can be any of the three flows (code, implicit, assisted_token).

• base_url* Base url of Curity Identity server.

• client_id* App client id

• issuer* Issuer endpoint

• redirect_uri* In case of framed flow, it will be something like assisted.html which is provided in example, you can provide any redirect uri and handle the response accordingly like it is done in assisted.html, you need to either host assisted.html on your server or implement the same thing in yourself and provide the redirect uri accordingly. In case of login with redirect, redirect uri will be probably your host application or wherever you will handle the response.

• iframe You can optionally customize the iframe height, width, style and backdrop as shown in example object above.

• popup You can optionally customize the popup height and width as shown in example object above.

• allowed_origins* Allowed origins: default is [window.origin]. For assisted token flow, this should include the origin of the token server or the origin of where the script is hosted. If the server is behind a reverse proxy, then the proxy's origin should be used.

• disable_session_management Set to true to disable session management

• check_session_iframe Url for the check session iframe, default will be resolved from metadata

• session_polling_interval Polling interval to post message to check session iframe to check for session, default is 5 seconds

• check_session_iframe_events

  Callback events which will be called in response to check session iframe polling.

  1. onStateChanging is called right before the prompt=none is sent when session has changed.
  2. onStateChanged is called right after the prompt=none re-authorization is received back to the client.
  3. onLogout is called when the the prompt returns an error of login_required.
  4. onConsent is called when the the prompt returns an error of consent_required.
  5. onError is called when an error is thrown by IP iframe
  6. onUnchanged is called whenever the login state does not change.

• allowed_jwt_algorithms Optional: Algorithms to trust for JWT validation

• jwt_sig_public_key More details

  An optional parameter which specify the format and value of public key to be used to verify the jwt signature.
  Default format is issuer.
  Allowed formats are jwk | jwks_uri | pem | issuer | metadata_url | raw

   1. **jwk**   
      A jwk can directly be passed as an object (and not a string), when format specified is `jwk`.    
        
   2. **jwks_uri**     
      A list of jwks can be retrieved from a specified `jwks_uri`.
     
   3. **pem**    
      A pem key string can be provided using public key format `pem`. 
     
   4. **issuer**   
      If the format specified is `issuer`, then jwt issuer is used to retrieve metadata which in turn, is resolved to retrieve jwk from corresponding jwks_uri. 
       
   5. **metadata_url**   
      If the format specified is `metadata_url`, then jwk is retrieved from corresponding jwks_uri of resolved metadata.
      
   6. **raw**       
      You can provide HMAC secret keys using `raw` format.           
  
  
   

• ignore_not_before Set to true to ignore not before (nbf) on ID Token validity check, default is false

• ignore_expiration Set to true to expiration (exp) on ID Token validity check, default is false

• clock_tolerance Controls the clock skew of the nbf and exp claim on ID Token validity check

• debug Debug mode set to true will enable the assistant to display console logs in order to help for debugging.

• openid_configuration_url URL of the OpenID Configuration well-known endpoint. By default this URL equals to the issuer value plus the path /.well-known/openid-configuration

Follow https://curity.io/resources/learn/test-using-oauth-assistant/ to try out the OAuth Assistant using the example app