Basic Integration of Asgardeo in a SPA for Newbies — Pt. 01
Before we get into how you can integrate Asgardeo, which sounds really cool, let’s first get you up to speed on what Asgardeo is. If you’re a fan of Marvel, you’re in for a real treat. The name Asgardeo was inspired by Thor’s home, Asgard, which is one of the Nordic mythologies’ nine realms. If you think that’s cool, you’re going to love Asgardeo.
Asgardeo is an IDaaS from the super cool folks at WSO2 that aims to empower developers to easily integrate seamless IAM in the hopes of reducing the complexities that have plagued the IAM domain for many years. Asgardeo is so cool that it can be integrated into almost any application that requires access management. Asgardeo enables developers to quickly and easily integrate secure authentication flows into applications. Woohooo!!
Now before jumping in, you might be wondering, “Hey Asgardeo sounds cool, but what is IDaaS and IAM?” Well, fear not.
IDaaS stands for identity as a service, and it is an application delivery model that allows users to connect and use cloud-based identity management services.
IAM stands for identity and access management, which is essentially a set of policies that ensure the right user has access to the right resources.
You now have a basic understanding of Asgardeo, IDaaS, and IAM. That’s all there is to it.
This article is the first of three parts that will walk you through the process of registering for Asgardeo, integrating it into your own application, and customizing the look and feel of seamless login experiences with Asgardeo. How cool is that?
In this article, we will familiarize you with Asgardeo and how you can integrate it into your application. So buckle up and put on your thinking caps, because this is going to be an exciting journey through Asgardeo.
Let’s start by getting you into the Asgardeo console, where all the magic happens. So head on over to Asgardeo Sign Up and follow the simple sign up process, either using your email or social media and get yourself registered. And boom, you’re in! It’s easy as that.
Once you’re in, you should be able to see the Asgardeo Console as shown below.
Let’s set up an organization for you in Asgardeo so that you can start being the cool kid on the block with Asgardeo. Go to the drop down next to the Asgardeo logo, add “New Organization,” and give it a suitable name.
You’re now ready to use Asgardeo and integrate it into your own product. As a result, you have the option of integrating it with any application. We will choose a SPA or a single page application.
When selected, you’ll be asked to give your application a name, so let’s do that. If you don’t have anything published yet, don’t worry. Asgardeo will let you add your redirect URLs later, so go ahead and let Asgardeo add, by default, https://localhost:3000 for you and press register.
Once in, you’ll see that you’re prompted to select a framework. We are going to use Vanilla JS here, but as you can see, Asgardeo also supports easy integration with frameworks like React, Angular, Vue, and many more.
When you click on the Vanilla JS icon, you’ll see a console with two different options with either trying out a sample or integrating it into your own application.
Select the option to integrate your application.
Before you begin tinkering with the code, let’s create a simple project with two HTML pages. Go to the GitHub repository below to clone the repo of the source files for the demo and host them using the GitHub Pages feature.
Asgardeo SPA SDK Integration Repo on GitHub
Finally, as the last prerequisite, let’s get NPM installed on your device. It’s recommended that you use NVM to install the Node.js runtime and NPM. You can install them from the NVM repo guide
Now that you’re all set up, let’s dive into how we can integrate Asgardeo into our own applications.
Installing/Importing the SDK
For you to get set up with the SDK in JS, there are 2 different ways. You can either install the JavaScript library from the NPM registry using the command below.
npm install --save @asgardeo/auth-spaOr you can import and load the SDK into the header of your HTML file as well
<script src="https://unpkg.com/@asgardeo/auth-spa@latest/dist/asgardeo-spa.production.min.js"></script>Instantiating/Initiating the client
When using the SPA client first, we have to make sure we initialize the SDK. For this, we use the getInstance() function in the SDK. When initiating the SDK, we are required to pass the correct parameters to the function auth.initialize() within your root component or home.html to correctly initialize the AsgardeoSPAClient
A correctly initiated client would look something like this,
// importing the SPA SDK
<script src="https://unpkg.com/@asgardeo/auth-spa@latest/dist/asgardeo-spa.production.min.js"></script><script>
// This client is a class and can be instantiated as follows.
var auth = AsgardeoAuth.AsgardeoSPAClient.getInstance();
// Once instantiated, the client can be initialized by passing the relevant parameters such as the server origin, redirect URL, client ID, etc.
auth.initialize({
signInRedirectURL: <the URL of the page after signing in>,
signOutRedirectURL: <the URL of the page after signing out>,
clientID: "<clientId>",
baseUrl: "https://api.asgardeo.io/t/<organization_name>",
scope: [ "openid","profile" ]
});
</script>
Now you might be wondering what these parameters are in the auth.initialize() function so let me break it down in a more simpler way for you,
signInRedirectURL is the URL that the app should redirect to once a user has logged in
signOutRedirectURL is the URL that the app should redirect to once a user has logged out
clientID is the client ID provided in your OIDC app on the Asgardeo Console.
baseUrl this is where Asgardeo’s hostname is there with your organization name that we created earlier.
scope is the the list of OIDC scopes that are used for requesting user information.
Don’t worry, we’ll be talking about how and where to find these parameters further down. 😉
Let’s see this in action. You can initiate the client and configure Asgardeo by adding the initialization to the root.
So now lets look at where you can get all these client IDs and Redirect URLs.
For the clientID you need to go to your Asgardeo Console and then select your organization. Then navigate to Develop > [Your Application] > Protocol and right on top you will find your clientID under OpenID Connect
Likewise, for the Redirect URLs same as above, navigate to the Protocol tab and scroll down to the Authorized redirect URLs and add your URLs of the 2 pages and make sure you allow CORS when prompted and check for the green tick.
🛑🛑🛑 DON’T FORGET TO PRESS UPDATE to any changes done in the Asgardeo console. 🛑🛑🛑
Then head over to the Quick Start tab and select the correct sign in and sign out URLs and copy the code that is auto generated for you.
And it’s as easy as that. Asgardeo is convenient and fast, and you don’t need to break a sweat. And you’re almost there.
Configuring Sign In/Sign Out
Setting up the sign in for Asgardeo is very easy. This can be done in two easy steps. First, go ahead and add this code snippet inside the script you added before and below the client initiate configs.
// To sign in, simply call the `signIn()` method.
auth.signIn();
// The `sign-in` hook is used to fire a callback function after signing in is successful.
auth.on("sign-in", (response) => {
alert("You have successfully signed in!");
});So your script for Asgardeo now should look like this
And for the second step you can add onClick="auth.signIn()" to your sign in button in the main of .html file to where ever you want a user to sign in.
<button onClick="auth.signIn()">Sign In</button>Now lets set up the SPA sign out. Its even more easier than the sign in. To make sure the sign out is working we have to pass {callOnlyOnRedirect:true} when the signInRedirectURL is loaded
So go ahead and in your script update the function auth.signIn() to auth.signIn({callOnlyOnRedirect:true}) so it should look something like this,
And voila you have seamlessly integrated a sign on experience with little to no effort with Asgardeo into your own application.
Now all you need to do is to test it out. So for now, let’s have a set of predefined credentials for a dummy user that you can assign to the Asgardeo console. So scroll down on the Quick Start tab and then add a user in the Try Out section.
And just provide some dummy credentials to test out the integration and and then go ahead and visit your hosted website and just try it for yourself.
Congratulations!!! You just created a seamless sign in/sign out experience through Asgardeo, and you’re super awesome cause you did it with literally little to no coding. Wooohooooooo!!!!! 😎
In the next part, we will go over how to configure the Asgardeo interface to allow self-registration and how to easily integrate social logins into your application for a seamless user experience and satisfaction with your product.
Check out the official documentation of Asgardeo at any time, and if you need technical help, you can always send an email to asgardeo-help@wso2.com
As always, keep shining and stay tuned for lots more exciting stuff coming your way. Keep grinding and stay curious and dare to do something new every day or learn something new. Look out for one another and keep rocking.
This is your friendly neighborhood UX/UI junkie signing out. See you in the next one. Peace ✌️
