Asgardeo Auth NodeJS SDK

Table of Content

• Introduction

• Install

• Getting Started

• APIs

  • constructor
  • signIn
  • signOut
  • getIDToken
  • isAuthenticated
  • getBasicUserInfo
  • getOIDCServiceEndpoints
  • getAccessToken
  • revokeAccessToken
  • requestCustomGrant
  • updateConfig
  • isSignOutSuccessful
  • isSignOutSuccessful

• Data Storage

  • Data Layer

• Models

  • AuthClientConfig<T>
  • Store
  • NodeTokenResponse
  • URLResponse

• Logging

  • Configuring the logger

• Develop

• Contribute

• License

Introduction

Asgardeo Auth NodeJS SDK provides the core methods that are needed to implement OIDC authentication in JavaScript/TypeScript based server side apps. This SDK can be used to build RESTful APIs with Javascript/Typescript based frameworks such as ExpressJS.

Prerequisites

Create an organization in Asgardeo if you don't already have one. The organization name you choose will be referred to as <org_name> throughout this documentation. If you are using Asgardeo as the identity server (IdP), create a Standard-Based Application in the console.

Install

Install the library from the npm registry.

npm install @asgardeo/auth-node

Getting Started

This getting started guide is an example of Express JS implementation. Other Node.js frameworks may differ from this implementation

// Import the packages needed to create an Express app
const express = require("express");
const cookieParser = require("cookie-parser");
const { v4: uuidv4 } = require("uuid");

// Import the Asgardeo Node SDK
// The SDK provides a client that can be used to carry out the authentication.
const { AsgardeoNodeClient } = require("@asgardeo/auth-node");

// Create a config object containing the necessary configurations.
const config = {
    clientID: "<your_client_id>",
    clientSecret: "<your_client_secret>",
    baseUrl: "https://api.asgardeo.io/t/<org_name>",
    signInRedirectURL: "http://localhost:3000/auth/sign-in",
    signOutRedirectURL: "http://localhost:3000",
    scope: ["openid", "profile"]
};

//If you are using Asgardeo as the IdP, make sure to add 'http://localhost:3000/auth/sign-in' as an authorized redirect URL and 'http://localhost:3000' as an allowed origin.

// Create an express app  and setup
const PORT = 3000;
const app = express();
app.use(cookieParser());

// Instantiate the AsgardeoNodeClient and pass the config object as an argument into the constructor.
const authClient = new AsgardeoNodeClient(config);

// Implement a login route.
// For this example, we will define the login route as '/auth/sign-in'.
// You can change this to match your use case.
app.get("/auth/sign-in", (req, res) => {

    // Check if the incoming request has a session ID which contains the user ID.
    let userID = req.cookies.ASGARDEO_SESSION_ID;

    // If the user ID is not present, create a new user ID.
    if (!userID) {
        userID = uuidv4();
    }

    // Define the callback function of the 'signIn' method
    const redirectCallback = (url) => {
        if (url) {
            // Make sure you use the httpOnly and sameSite to prevent from cross-site request forgery (CSRF) attacks.
            // You can change the cookie parameters as per your use case.
            res.cookie("ASGARDEO_SESSION_ID", userID, { maxAge: 900000, httpOnly: true, sameSite: "lax" });
            res.redirect(url);

            return;
        }
    };
    // Use the 'signIn' method from the SDK to initiate the authorization flow.
    authClient
        .signIn(
            redirectCallback,
            userID,
            req.query.code,
            req.query.session_state,
            req.query.state
        )
        .then((response) => {
            if (response.accessToken || response.idToken) {
                // If the accessToken or the idToken is present, redirect to the homepage.
                // In this case, the home route is defined as `/home`.
                res.redirect("/home");
            }
        }).catch((err) => {
            console.log(err);
            // If there is an error, you can redirect to an error page
            // In this case, the home route is defined as `/errorPage`.
            res.redirect("/errorPage");
        });

    // Now you have successfully implemented the /sign-in endpoint with Asgardeo Node SDK.
    // Please refer to the sample app to see the how to implement the other functionalities.
    
});

//Start the app and listen on PORT 3000
app.listen(PORT, () => {
    console.log(`Server Started at PORT ${ PORT }`);
});

APIs

The SDK provides a client class called AsgardeoAuth that provides you with the necessary methods to implement authentication. You can instantiate the class and use the object to access the provided methods.

constructor

new AsgardeoAuth(config:AuthClientConfig<T>, store?: Store);

Arguments

1. config: AuthClientConfig<T>

   This contains the configuration information needed to implement authentication such as the client ID, base URL etc. Additional configuration information that is needed to be stored can be passed by extending the type of this argument using the generic type parameter. For example, if you want the config to have an attribute called foo, you can create an interface called Bar in TypeScript and then pass that interface as the generic type to AuthClientConfig interface. To learn more about what attributes can be passed into this object, refer to the AuthClientConfig<T> section.

   interface Bar {
       foo: string
   }
   
   const auth = new AsgardeoAuthClient(config: AuthClientConfig<Bar>);
   }

   Example

   const config = {
       signInRedirectURL: "http://localhost:3000/sign-in",
       signOutRedirectURL: "http://localhost:3000/login",
       clientID: "client ID",
       baseUrl: "https://api.asgardeo.io/t/<org_name>"
   };

2. store: Store

   This is the object of interface Store that is used by the SDK to store all the necessary data used ranging from the configuration data to the access token. By default, the SDK is packed with a built-in Memory Cache Store. If needed, you can implement the Store to create a class with your own implementation logic and pass an instance of the class as the second argument. This way, you will be able to get the data stored in your preferred place. To know more about implementing the Store interface, refer to the Data Storage section.

   Description

   This creates an instance of the AsgardeoAuthClient class and returns it.

   Example

   class NodeStore implements Store {
       public async setData(key: string, value: string): void {
           yourCustomStorage.setItem(key, value);
       }
   
       public async getData(key: string): string {
           return yourCustomStorage.getItem(key);
       }
   
       public async removeData(key: string): void {
           yourCustomStorage.removeItem(key);
       }
   }
   
   const store = new NodeStore();
   
   const auth = new AsgardeoAuthClient(config: AuthClientConfig<Bar>, store: store);

signIn

signIn(authURLCallback: AuthURLCallback, authorizationCode?: string, sessionState?: string, userId?: string): Promise<URLResponse | NodeTokenResponse>

Arguments

1. authURLCallback: AuthURLCallback

   This is the callback function which is used to redirect the user to the authorization URL.

2. authorizationCode: string (optional)

   This is the authorization code obtained from Asgardeo after a user signs in.

3. sessionState: string (optional)

   This is the session state obtained from Asgardeo after a user signs in.

4. userId: string (optional)

   If you want to use the SDK to manage multiple user sessions, you can pass a unique ID here to generate an authorization URL specific to that user. This can be useful when this SDK is used in backend applications.

Returns

A Promise that resolves with a Promise that resolves with the NodeTokenResponse object.

Description

This method first checks if the authorizationCode or sessionState is available in the arguments. If they exists, It will request the access token for the respective authorization code and returns a promise that will be resolved with the NodeTokenResponse object. If not, it will obtain the authorization URL and callback the authURLCallback function with the authorization URL. The user can be redirected to this URL to authenticate themselves and authorize the client.

Note: Make sure you call the same signIn() method in the signInRedirectURL path to request the access token successfully.

Example (Express JS)

authClient.signIn(req.query.code, req.query.session_state, req.query.user_id).then(response => {
        //URL property will available if the user has not been authenticated already
        if (response.hasOwnProperty('url')) {
            res.redirect(response.url)
        } else {
            //Set the cookie
            res.cookie('ASGARDEO_SESSION_ID', response.session, { maxAge: 900000, httpOnly: true, SameSite: true });
            res.status(200).send(response)
        }
    });

signOut

signOut(userId: string): Promise<string>

Returns

signOutURL: Promise<string>

The user should be redirected to this URL in order to sign out of the server.

Description

This clears the authentication data from the store, generates the sign-out URL and returns it. This should be used only if you want to sign out the user from the Asgardeo as well.

Example

Note: Make sure to invalidate the cookie ID when sending the response to the client

// This should be within an async function.
const signOutURL = await authClient.signOut("a2a2972c-51cd-5e9d-a9ae-058fae9f7927");
//If you are using Express JS you may try this to invalidate the cookie
 res.cookie('ASGARDEO_SESSION_ID',null, { maxAge: 0 });
 res.redirect(signOutURL);

getIDToken

getIDToken(userId: string): Promise<string>

Returns

idToken: Promise<string> A Promise that resolves with the ID Token.

Description

This method returns the id token.

Example

const idToken = await authClient.getIDToken("a2a2972c-51cd-5e9d-a9ae-058fae9f7927");

isAuthenticated

isAuthenticated(userId: string): Promise<boolean>

Returns

isAuth: boolean A boolean value that indicates of the user is authenticated or not.

Description

This method returns a boolean value indicating if the user is authenticated or not.

Example

// This should be within an async function.
const isAuth = await authClient.isAuthenticated("a2a2972c-51cd-5e9d-a9ae-058fae9f7927");

getBasicUserInfo

getBasicUserInfo(userId: string): Promise<BasicUserInfo>

Arguments

1. userId: string (optional)

   If you want to use the SDK to manage multiple user sessions, you can pass a unique ID here to generate an authorization URL specific to that user. This can be useful when this SDK is used in backend applications.

Returns

basicUserInfo: Promise<BasicUserInfo> An object containing basic user information obtained from the id token.

Description

This method returns the basic user information obtained from the payload. To learn more about what information is returned, checkout the DecodedIDTokenPayload model.

Example

// This should be within an async function.
const basicUserInfo = await authClient.getBasicUserInfo("a2a2972c-51cd-5e9d-a9ae-058fae9f7927");

getOIDCServiceEndpoints

getOIDCServiceEndpoints(): Promise<OIDCEndpoints>

Returns

oidcEndpoints: Promise<OIDCEndpoints> An object containing the OIDC service endpoints returned by the .well-known endpoint.

Description

This method returns the OIDC service endpoints obtained from the .well-known endpoint. To learn more about what endpoints are returned, checkout the OIDCEndpoints section.

Example

// This should be within an async function.
const oidcEndpoints = await authClient.getOIDCServiceEndpoints();

getDecodedIDToken

getDecodedIDToken(userId?: string): Promise<DecodedIDTokenPayload>

Arguments

1. userId: string (optional)

   If you want to use the SDK to manage multiple user sessions, you can pass a unique ID here to generate an authorization URL specific to that user. This can be useful when this SDK is used in backend applications.

Returns

decodedIDTokenPayload: Promise<DecodedIDTokenPayload> The decoded ID token payload.

Description

This method decodes the payload of the id token and returns the decoded values.

Example

// This should be within an async function.
const decodedIDTokenPayload = await authClient.getDecodedIDToken("a2a2972c-51cd-5e9d-a9ae-058fae9f7927");

getAccessToken

getAccessToken(userId?: string): Promise<string>

Arguments

1. userId: string (optional)

   If you want to use the SDK to manage multiple user sessions, you can pass a unique ID here to generate an authorization URL specific to that user. This can be useful when this SDK is used in backend applications.

Returns

idToken: Promise<string> The id token.

Description

This method returns the id token.

Example

// This should be within an async function.
const idToken = await authClient.getIDToken("a2a2972c-51cd-5e9d-a9ae-058fae9f7927");

revokeAccessToken

revokeAccessToken(userId?: string): Promise<FetchResponse>

Arguments

1. userId: string (optional)

   If you want to use the SDK to manage multiple user sessions, you can pass a unique ID here to generate an authorization URL specific to that user. This can be useful when this SDK is used in backend applications.

Returns

A Promise that resolves with the response returned by the server.

Description

This method clears the authentication data and sends a request to revoke the access token. You can use this method if you want to sign the user out of your application but not from the server.

Example

// This should be within an async function.
const revokeToken = await auth.revokeAccessToken("a2a2972c-51cd-5e9d-a9ae-058fae9f7927");

requestCustomGrant

requestCustomGrant(config: CustomGrantConfig, userId?: string): Promise<TokenResponse | FetchResponse>

Arguments

1. config: CustomGrantConfig

   The config object contains attributes that would be used to configure the custom grant request. To learn more about the different configurations available, checkout the CustomGrantConfig model.

2. userId: string (optional)

   If you want to use the SDK to manage multiple user sessions, you can pass a unique ID here to generate an authorization URL specific to that user. This can be useful when this SDK is used in backend applications.

Returns

A Promise that resolves with the token information or the response returned by the server depending on the configuration passed.

Description

This method can be used to send custom-grant requests to Asgardeo.

Example

const config = {
    attachToken: false,
    data: {
        client_id: "{{clientID}}",
        grant_type: "account_switch",
        scope: "{{scope}}",
        token: "{{token}}",
    },
    id: "account-switch",
    returnResponse: true,
    returnsSession: true,
    signInRequired: true
}

auth.requestCustomGrant(config).then((response) => {
    console.log(response);
}).catch((error) => {
    console.error(error);
});

updateConfig

updateConfig(config: Partial<AuthClientConfig<T>>): Promise<void>

Arguments

1. config: AuthClientConfig<T>

   The config object containing the attributes that can be used to configure the SDK. To learn more about the available attributes, refer to the[ AuthClientConfig](# AuthClientConfig) model.

Description

This method can be used to update the configurations passed into the constructor of the AsgardeoAuthClient. Please note that every attribute in the config object passed as the argument here is optional. Use this method if you want to update certain attributes after instantiating the class.

Example

const pkce = auth.updateConfig({
    signOutRedirectURL: "http://localhost:3000/sign-out"
});

isSignOutSuccessful

static isSignOutSuccessful(signOutRedirectURL: string): boolean

This is a static method.

Arguments

1. signOutRedirectURL: string

   The URL to which the user is redirected to after signing out from the server.

Returns

isSignedOut: boolean A boolean value indicating if the user has been signed out or not.

Description

This method returns if the user has been successfully signed out or not. When a user signs out from the server, the user is redirected to the URL specified by the signOutRedirectURL in the config object passed into the constructor of the AsgardeoAuthClient. The server appends path parameters indicating if the sign-out is successful. This method reads the URL and returns if the sign-out is successful or not. So, make sure you pass as the argument the URL to which the user has been redirected to after signing out from the server.

Example

const isSignedOut = auth.isSignOutSuccessful(<signout_redirect_url>);

didSignOutFail

static didSignOutFail(signOutRedirectURL: string): boolean

This is a static method.

Arguments

1. signOutRedirectURL: string

   The URL to which the user is redirected to after signing out from the server.

Returns

didSignOutFail: boolean A boolean value indicating if sign-out failed or not.

Description

This method returns if sign-out failed or not. When a user signs out from the server, the user is redirected to the URL specified by the signOutRedirectURL in the config object passed into the constructor of the AsgardeoAuthClient. The server appends path parameters indicating if the sign-out is successful. This method reads the URL and returns if the sign-out failed or not. So, make sure you pass as the argument the URL to which the user has been redirected to after signing out from the server.

Example

const isSignedOutFailed = auth.isSignOutSuccessful(<signout_redirect_url>);

Data Storage

Since the SDK was developed with the view of being able to support various frameworks such as ExpressJS, Fastify and Next JS, the SDK allows developers to use their preferred mode of storage. To that end, the SDK allows you to pass a store object when instantiating the AsgardeoAuthClient. This store object contains methods that can be used to store, retrieve and delete data. The SDK provides a Store interface that you can implement to create your own Store class. You can refer to the Store section to learn mire about the Store interface.

There are three methods that are to be implemented by the developer. They are

1. setData
2. getData
3. removeData

The setData method is used to store data. The getData method is used to retrieve data. The removeData method is used to delete data. The SDK converts the data to be stored into a JSON string internally and then calls the setData method to store the data. The data is represented as a key-value pairs in the SDK. The SDK uses four keys internally and you can learn about them by referring to the Data Layer section. So, every JSON stringified data value is supposed to be stored against the passed key in the data store. A sample implementation of the Store class using the browser session storage is given here.

class NodeStore implements Store {
    public setData(key: string, value: string): void {
        sessionStorage.setItem(key, value);
    }

    public getData(key: string): string {
        return sessionStorage.getItem(key);
    }

    public removeData(key: string): void {
        sessionStorage.removeItem(key);
    }
}

Models

AuthClientConfig<T>

This model has the following attributes. |Attribute| Required/Optional| Type | Default Value| Description| |--|--|--|--|--| |signInRedirectURL |Required|string|""|The URL to redirect to after the user authorizes the client app. eg: https//localhost:3000/sign-in| |signOutRedirectURL |Optional|string| The signInRedirectURL URL will be used if this value is not provided. |The URL to redirect to after the user |signs out. eg: http://localhost:3000/dashboard| |clientHost|Optional| string|The origin of the client app obtained using window.origin|The hostname of the client app. eg: https://localhost:3000| |clientID|Required| string|""|The client ID of the OIDC application hosted in the Asgardeo.| |clientSecret|Optional| string|""|The client secret of the OIDC application| |enablePKCE|Optional| boolean|true| Specifies if a PKCE should be sent with the request for the authorization code.| |prompt|Optional| string|""|Specifies the prompt type of an OIDC request| |responseMode|Optional| ResponseMode|"query"|Specifies the response mode. The value can either be query or form_post| |scope|Optional| string[]|["openid"]|Specifies the requested scopes.| |baseUrl|Required| string|""|The origin of the Identity Provider. eg: https://api.asgardeo.io/t/<org_name>| |endpoints|Optional| OIDCEndpoints|OIDC Endpoints Default Values|The OIDC endpoint URLs. The SDK will try to obtain the endpoint URLS |using the .well-known endpoint. If this fails, the SDK will use these endpoint URLs. If this attribute is not set, then the default endpoint URLs will be |used. However, if the overrideWellEndpointConfig is set to true, then this will override the endpoints obtained from the .well-known endpoint. | |overrideWellEndpointConfig|Optional| boolean | false | If this option is set to true, then the endpoints object will override endpoints obtained |from the .well-known endpoint. If this is set to false, then this will be used as a fallback if the request to the .well-known endpoint fails.| |wellKnownEndpoint|Optional| string|"/oauth2/token/.well-known/openid-configuration"| The URL of the .well-known endpoint.| |validateIDToken|Optional| boolean|true|Allows you to enable/disable JWT ID token validation after obtaining the ID token.| |clockTolerance|Optional| number|60|Allows you to configure the leeway when validating the id_token.| |sendCookiesInRequests|Optional| boolean|true|Specifies if cookies should be sent in the requests.|

The AuthClientConfig<T> can be extended by passing an interface as the generic type. For example, if you want to add an attribute called foo to the config object, you can create an interface called Bar and pass that as the generic type into the AuthClientConfig<T> interface.

interface Bar {
    foo: string
}

const config: AuthClientConfig<Bar> ={
    ...
}

Store

| Method | Required/Optional | Arguments | Returns | Description | | ------------ | ----------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | setData | Required | key: string, value: string | Promise<void> | This method saves the passed value to the store. The data to be saved is JSON stringified so will be passed by the SDK as a string. | | getData | Required | key: string|string | This method retrieves the data from the store and returns a Promise that resolves with it. Since the SDK stores the data as a JSON string, the returned value will be a string. | | removeData | Required | key: string | Promise<void> | Removes the data with the specified key from the store. |

NodeTokenResponse

| Method | Type | Description | | -------------- | -------- | --------------------------- | | accessToken | string | The access token. | | idToken | string | The id token. | | expiresIn | string | The expiry time in seconds. | | scope | string | The scope of the token. | | refreshToken | string | The refresh token. | | tokenType | string | The token type. | | session | string | The session ID. |

AuthURLCallback

(url: string): void;

Description

This method is used to handle the callback from the signIn method. You may use this function to get the authorization URL and redirect the user to authorize the application.

Example

//You may use this in Express JS
const urlCallbackHandler = (url: string): void => {
    res.redirect(url);
}

Logging

The SDK supports the following log levels. DEBUG is the lowest log level while OFF is the highest.

| Level | Description | |---------|-------------------------------------------------------------| | DEBUG | Log messages intended for debugging purposes. | | INFO | Log messages intended for typical logging purposes. | | WARN | Log messages that designates potentially harmful scenarios. | | ERROR | Log messages that designates error scenarios. | | OFF | Turns the logging off. |

Setting the application's log level to a certain log level will filter out messages from all the log levels below it. For example, if the application log level wasINFO, only INFO,WARN and ERROR messages are logged.

Configuring the Logger

In order to configure the logger, the developers need to provide LOG_LEVEL as an environment variable. The log level is set to OFF by default.

Please note that the LOG_LEVEL config only accepts the above log level values, and any other value will be ignored.

Develop

Prerequisites

• Node.js (version 10 or above).
• yarn package manager.

Installing Dependencies

The repository is a mono repository. The SDK repository is found in the lib directory. You can install the dependencies by running the following command at the root.

yarn run build

Contribute

Please read Contributing to the Code Base for details on our code of conduct, and the process for submitting pull requests to us.

Reporting issues

We encourage you to report issues, improvements, and feature requests creating Github Issues.

Important: And please be advised that security issues must be reported to security@wso2com, not as GitHub issues, in order to reach the proper audience. We strongly advise following the WSO2 Security Vulnerability Reporting Guidelines when reporting the security issues.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.