Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

@curity/oauth-assistant

1.1.2 • Public • Published

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
        backdrop: {
            visible      : true, // default is true
            style        : null, // take default value
            backdropClass: ""
        }
    },
    allowed_origins: ["http://localhost:8443", "http://localhost:8080"], // default is [window.origin]
    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
    },
    debug: false,  // Optional: Enabling debug to true will display console logs of assistant, default is false
};

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. getToken()
6. getIDToken()
7. revoke()
8. logout(postLogoutRedirectUri)
9. getScope()
10. getExpiresIn()
11. 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) => {});    
    

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) => {});

Logout
Logout the user from server and revoke tokens.
Default value of postLogoutRedirectUri is window.location.href.

assistant.logout(postLogoutRedirectUri)
    .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: ""
        }
    },
    allowed_origins: ["http://localhost:8443", "http://localhost:8080"], // default is [window.origin]
    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
    },
   debug: false,  // Enabling debug to true will display console logs of assistant
};

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.

  • allowed_origins* Allowed origins: default is [window.origin]

  • 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.           
    
  • debug Debug mode set to true will enable the assistant to display console logs in order to help for debugging.

Install

npm i @curity/oauth-assistant

DownloadsWeekly Downloads

121

Version

1.1.2

License

Apache-2.0

Unpacked Size

129 kB

Total Files

13

Last publish

Collaborators

  • avatar
  • avatar