Asgardio OIDC JS SDK: Bootstrap in three easy steps

Asgardio OIDC JavaScript SDK allows developers to implement OIDC authentication in their Single Page Applications in a fast and secure manner, especially when using the WSO2 Identity Server as the Identity Provider. 

The SDK offers three different storage options to store the session information, namely, session storage, local storage, and web worker. Besides, it supports PKCE verification, ID token validation, and allows you to use “form_post” and “query” response modes. You can find the complete set of information regarding the features and functionalities of the SDK here. 

Crafted with developer experience in mind, Asgardio OIDC JavaScript SDK lets you get started with implementing OIDC authentication in your application in three easy steps. Without wasting any more time, let’s dive right in. 

1. Install the Asgardio OIDC JavaScript SDK

First, we need to install the Asgardio OIDC JavaScript SDK. If your app uses NPM, then you can install the SDK directly from the NPM registry. 

npm install --save @asgardio/oidc-js

If you are working on an embedded script, then you can embed the Asgardio OIDC JavaScript SDK script from NPM’s CDN. The latest version as of the time of writing is 0.1.25. So, let’s embed the script belonging to this version. 

<script src="https://unpkg.com/@asgardio/oidc-js@0.1.25/dist/main.js"></script>  

2. Initialize the SDK

Once installed, we need to initialize the SDK. The SDK provides a singleton called IdentityClient. We can instantiate this singleton using its getInstance method.   

If your app is a modular one, then you need to import the client first. 

import { IdentityClient } from "@asgardio/oidc-js";  

After importing, we can instantiate it. 

const auth = IdentityClient.getInstance(); 

This is, however, valid only in modular applications. If you are going to use it in an embedded script, then you will have to obtain the IdentityClient from the AsgardioAuth global variable. 

var auth = AsgardioAuth.IdentityClient.getInstance(); 

Now, we have an instance of the IdentityClient. Let’s initialize it. 

To initialize, we need to pass an object containing the following attributes as an argument into the initialize method of the client. 

1. signInRedirectURL
2. signOutRedirectURL
3. clientHost
4. clientID
5. serverOrigin

The signInRedirectURL and signOutRedirectURL are the URLs to which a user should be redirected to once the user authenticates themselves with the Identity Server, and once the user logs out of the server respectively. Remember that the redirect URLs you configure here should be the same as the ones you specified in the relevant application in the Identity Server. Otherwise, the Identity Server would throw an error. 

The clientHost is simply the hostname of your Single Page Application, and the clientID is the ID of the application in the Identity Server that the SPA will be authenticating through. The serverOrigin is the hostname of the Identity Server, which is usually https://localhost:9443 for WSO2 Identity Server. 

With that said, let’s call the initialize method. 

auth.initialize({ 
    signInRedirectURL: "", 
    signOutRedirectURL: "", 
    clientHost: origin, 
    clientID: "", 
    serverOrigin: "http://localhost:9443" 
});  

3. Invoke the signIn() method

We have done the dirty work. Now, it’s time for the moment of truth. Let’s invoke the signIn method and see if it works.  

auth.signIn();  

Yes, it is that simple! If everything goes well, you will be redirected to the Single-Sign-On page of the WSO2 Identity Server. Once you enter your credentials, you will be redirected back to the URL you specified.  

Here is where things may get a bit tricky. You need to make sure the signIn method is invoked when the user is redirected back to the app. So, you should either make sure that the user is redirected to the same page that first invokes the signIn method or signIn method is invoked by the page the user is redirected to. 

To add a cherry on top, let’s have a callback function fire when the user successfully signs in. We can do this by leveraging the on method provided by the client. This method lets us hook callback functions to various events so that they can be fired when these events take place.  

The on method accepts two mandatory arguments. The first is the name of the hook. We will be using the “sign-in” hook to attach a callback function to the sign-in event. The second is, as you may have guessed, the callback function.  

auth.on("sign-in", (response) => { 
    alert("You have successfully signed in!"); 
}); 

You can call this method anywhere but I recommend to call it soon after initializing the client.  

There you are, that’s how you do it. You have added authentication to your SPA in just three easy steps-hop, skip and jump!