Wondering what’s next for npm?Check out our public roadmap! »

    @curity/oauth-assistant
    TypeScript icon, indicating that this package has built-in type declarations

    1.7.0 • 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
            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

    Install

    npm i @curity/oauth-assistant

    DownloadsWeekly Downloads

    400

    Version

    1.7.0

    License

    Apache-2.0

    Unpacked Size

    147 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar