---

Getting started with MSAL

Registering an application with Azure AD

Prerequisites

Prerequisites to register an application with the Microsoft identity platform.

Steps:

1. Go to portal.azure.com
2. Go to More services

3. Jump into Azure Active Directory

4. Go to App registrations. As you can see I am using my ex-company’s account.

5. As you can see I have already registered one application called ‘msal-test’. Now, go ahead and click on New registration.

6. Let’s call the application ‘msal-app’. You can have any name for the application. As you can see we have 4 options for “Who can use this application or access this API?”

To understand these options, read what ‘Tenant‘ is first.

There are four options: 

1. Accounts in this organizational directory only: This option allows only users in the same Azure AD tenant to access the application or API. Users from other organizations or tenants will not be able to use the application or access the API.
2. Accounts in any organizational directory: This option allows users from any Azure AD tenant to access the application or API. However, users must still be authenticated by their home tenant.
3. Accounts in any organizational directory and personal Microsoft accounts: This option allows users from any Azure AD tenant, as well as personal Microsoft accounts, to access the application or API. Personal Microsoft accounts include accounts like Outlook.com, Live.com, and Hotmail.com.
4. Single tenant: This option allows users from a specific tenant to access the application or API. The application will only be available to users from the specified tenant and not to any other tenant. This option is useful when the application is designed for a specific customer or partner organization.

Pick either the second or third option. I am gonna pick the second option for this tutorial.

7. In my case, since I am doing a native authentication, so I will select the first option. Depending on your requirement pick the option.

8. The next part is to set the redirect URI. Let’s keep the Redirect URI as simple as possible. Since I am running this natively, my URI is http://localhost. Then, click Register

9. Here’s your application registration. Since I have already registered ‘msal-test’ I will go ahead with that. You should find all the necessary information here.

10. Now you will need to enable an additional setting called Allow public client flows. Go ahead and set this setting to Yes. After that click Save, to save the changes.

Let’s understand few concepts and methodologies first before we proceed forward.

Authentication Flows in Azure Active Directory (Azure AD)

Authentication flows in Azure AD refer to the different methods that can be used to authenticate a user and obtain an access token for accessing protected resources.

1. Authorization Code Flow

The authorization code flow is used for web applications and involves the user being redirected to the Azure AD login page, where they enter their credentials. After successful authentication, Azure AD returns an authorization code to the application, which can then be exchanged for an access token.

2. Implicit Grant Flow

The implicit grant flow is also used for web applications but is intended for public clients, such as single-page applications. In this flow, the access token is returned directly to the application after the user successfully authenticates with Azure AD.

3. Device Code Flow

The device code flow is used for devices that cannot display a traditional login page, such as game consoles or smart TVs. Users are provided with a code to enter on a separate device, such as a mobile phone or computer, which allows them to authenticate and obtain an access token.

4. Resource Owner Password Credentials (ROPC) Flow

The resource owner password credentials (ROPC) flow is used for legacy applications that cannot be modified to use modern authentication protocols such as OAuth 2.0. In this flow, the user’s credentials are sent directly to Azure AD to obtain an access token, without the need for a separate authentication step.

5. Client Credentials Flow

The client credentials flow is used for non-interactive applications that need to access protected resources on behalf of themselves, rather than a user. In this flow, the application provides its own credentials to Azure AD to obtain an access token.

6. Combining Authentication Flows with Azure AD Features

These authentication flows can be used in combination with other Azure AD features, such as conditional access policies, multi-factor authentication, and password protection, to provide secure and flexible authentication solutions for various types of applications and scenarios.

Login URL

In Azure Active Directory (Azure AD), the login URL is the endpoint where users can sign in to access their applications and resources. This URL is also referred to as the Azure AD sign-in page or the Azure AD login page.

Here, ‘{tenant-id}‘ is the unique identifier for the Azure AD tenant. This URL is used by developers when configuring their applications to integrate with Azure AD for authentication and authorization.

When a user accesses the Azure AD login URL, they are prompted to enter their credentials and authenticate themselves. Once authenticated, they are granted access to their applications and resources based on their assigned permissions and roles.

When we login, we have a common URL. Let’s call it the Base URL. It will be used for login and token requests.

Base URL:

https://login.microsoftonline.com/tenant_id/oauth2/v2.0

The Azure AD login URL typically takes the following format:

https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize

Relative URL’s for specific actions:

• login: /authorize
• acquire token: /token

We can take specific action based on our relative URL. For instance, to login we go to /authorize relative URL or if we just want to get a token we go to the /token relative URL.

Tenants

In Azure Active Directory (Azure AD), a tenant represents an organization or a company that uses Azure AD to manage access to resources. It is a dedicated instance of Azure AD that is created when an organization first signs up for an Azure subscription.

Each tenant has its own separate and independent identity and access management system, which allows it to manage its own users, groups, applications, and resources. A tenant is identified by a unique domain name, such as yourcompanyname.onmicrosoft.com, which is assigned to the tenant during its creation.

Multiple tenants can be created within a single Azure account, each with its own set of users, groups, applications, and resources. This allows organizations to manage access to their resources across multiple departments, subsidiaries, or business units, while still maintaining central control over the overall Azure account.

It is a unique tenant ID for your organization. Say if someone is logging in with a particular tenant ID belonging to your organization, on the login portal it will show the name and branding of your Azure Active Directory tenant.

Endpoints:

• organization – Any organizational(school/work) account
• consumers – Any Microsoft account
• common – Any account

If we use organization endpoint then you will be taken to a special login page only for organizational accounts, basically your work or school accounts. Another endpoint is the consumers endpoint, this is a special endpoint that’s just for someone with a Microsoft account. Basically, if you’re building something to interact with any type of Microsoft account features you would go to the consumer’s tenant. The other endpoint is common and is just for any type of account whether it’s organizational or consumer account

Authorize

First and foremost, if you do not already have it, install Postman as we will use it to build our URL.

In Azure AD, authorization refers to the process of granting access to resources based on a user’s identity and the permissions associated with that identity. When a user attempts to access a resource, the Azure AD service determines whether the user has the necessary permissions to perform the requested action.

We will be performing these steps in our demo. For now, go through the steps to understand the important concepts and attributes that are involved in the process.

1. We navigate to the /authorize endpoint for login.microsoftonline.com
   1. Provide correct request string parameters
      1. client_id: Client ID(unique identifier that we saw during app registration) 
      2. responst_type: Set to code
      3. redirect_uri: Redirected URI’s specified during application registration
      4. scope: List of permissons
      5. response_mode: Either form-post or query
      6. state: Optional

Find the summary in the picture below. Basically we need to provide these above mentioned 5 parameters.

2. Then, we send a GET request from our Browser which either return a Micrsoft Sign-In page prompting you to login or a site not reached page.
3. After you send the GET request, take a look at the request string/URL on the top of the browser search bar.
   1. If response_mode = query, URL will consist of a unique code. We will use this code to acquire our token.
4. Here’s how our authorization request will look like. I will show you the steps to get this request later in this documentation.

GET Request to Microsoft:

In this scenario, we are using the organizational accounts to authenticate users, and we are doing so through the organizations and authorize endpoint. To access this endpoint, we need to provide a unique client_id, which we can find in Azure after registering our application. Additionally, we must specify a response_type as “code”, a redirect_uri, and response_mode of “query”. We only need to read the user’s profile, so our scope is set to user.read. We also include some state data. When the response is sent, it will redirect to our specified URI, in my case, http://localhost, and echo back our state data.

In summary, we are using a secure method of authentication for organizational accounts, utilizing unique identification, specific response types, and redirecting to specified URIs. The scope is set to only allow for reading of user profiles, and state data is included for added security. This process allows for a streamlined and secure way to access organizational accounts.

URI with code:

Here we have code and session_state. Now you may ask how did we receive this code? We will look into that later in the documentation.

The GET request query string you see above is what you paste in the browser search, i.e. you send a GET request. What you receive as a response is either a Microsoft Sign-In or Site not reached page, however it does not matter since we are concerned with the URL on the top after we send the request. The URL query string contains the values to two parameters: code and session_state. We only care about code since the value it holds will be used during the demo of running token acquisition and authentication manually later in this documentation.

Acquire a Bearer token

Acquiring a bearer token in Azure Active Directory (Azure AD) refers to the process of obtaining a token that can be used to authenticate and authorize access to protected resources. Bearer tokens are used in OAuth 2.0 authorization framework to grant access to resources.

In Azure AD, bearer tokens can be acquired through various authentication flows, such as the Authorization Code Flow, Implicit Grant Flow, Device Code Flow, Resource Owner Password Credentials (ROPC) Flow, and Client Credentials Flow.

When a user signs in using an authentication flow, Azure AD issues a bearer token that contains the user’s claims and permissions. This token can then be used to access resources that require authentication and authorization.

Bearer tokens acquired through Azure AD have an expiration time, after which they are no longer valid. To continue accessing protected resources, a new token must be acquired. This can be done automatically by the application or manually by requesting a new token from Azure AD.

Once a bearer token is acquired, it can be included in requests made to protected resources by adding it to the Authorization header. The resource server then validates the token by verifying its signature and checking its claims, such as the audience and issuer. If the token is valid, the resource server grants the requested access to the user.

Acquiring a bearer token in Azure AD is an essential step in enabling secure access to protected resources, and understanding the authentication flows and token handling is crucial for building secure applications.

We send a POST request to the ‘/token‘ endpoint for login.microsoftonline.com and this process will be covered later in the demo. Now here’s the interesting part. To get Bearer token you need to pass one more parameter to the POST request called ‘client_secret‘.

So, here’s how you get the client_secret.

1. Go to App registrations. Click on your app(msal-app). Make sure you are at the Overview page. There on the left side panel you will find Certificates & secrets. Click on it..

2. Go ahead and click on ‘New client secret’

3. Enter any description and keep the default option for Expires or based on your requirement. Then click Add.

4. A new client secret will be created. Now go ahead and copy the value and make sure you paste it somewhere safe(notepad, google doc/ms word or your preferred text editor)

5. Now we will use this client_secret as one of our parameters for the POST request.

Provide correct form parameters

• client_id: Client ID(unique identifier that we saw during app registration) 
• redirect_uri: Redirected URI’s specified during application registration
• scope: List of permissions
• code: code from authorization Request
• grant_type: We use ‘authorization_code’ as the value
• client_secret: The client_secret we copied above.

After sending the POST request, observe the response you receive. You will find that the access_token property/parameter has your Bearer token.

Demo: Manually Running Token Acquisition and Authentication

Here’s a demo of manually acquiring the token using Postman. At this point you should have Postman installed.

GET Request

1. Open Postman. Go to Workspaces > My Workspace. Click New > New Collection

2. Name your collection. I have named it as ‘msal-app’

3. Click on the + sign. This will open up the request tab.

4. In the request tab, copy and paste in the following link:

https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize

Make sure you select GET. You should be at the Params tab. If you remember I mentioned about navigating to the /authorize endpoint for login.microsoftonline.com. This is step is what I was referring to.

5. Fill in the keys and associated values. See the Authorize step above for reference. Here’s my list of key, value pairs. Since we are using Postman it will automatically form the request in the bar.

6. This is the expected result.

7. You can also copy and paste the URL into a browser and see the response a little better. Copy the URL and paste it in your browser to see the response. You will see a Microsoft Sign-In window. Once logged in, will redirect you to wherever we set the redirect URI, in this example, localhost. 

8. So go ahead and copy the URL and paste it in your browser and wait for the response.

9. You will most likely get the following response page(or you will get a Sign-In page first > you select the appropriate account > And get this page as a result). Dont worry. Go ahead and copy the URL on the top.

10. Go to Postman, and open a new GET request. Postman will automatically fetch code and session_state parameters from the URL.

11. Copy the code parameter. We will need it in the next step.

POST Request

12. Click New > HTTP Request. Type in the following where it says Enter URL > https://login.microsoftonline.com/common/oauth2/v2.0/token 

13. We will send query params as form data. Go to Body, check ‘form-data’

14. Start filling in the keys and values. First, paste the code we copied in the parameters. Please note that this time we have a new parameter in our list called client_secret as you can see in the image below. If you remember we have saved the client_secret. Copy and paste it next to client_secret parameter.

15. Click Send. If you did everything correctly. This is the response. You should get a Bearer token that looks something like this

Note: The token expires after a while. So if such a situation arises you have to perform steps 7 to 11 again to get a new code. So get a new code and paste it in the POST request code parameter(refer Step 24.)

16. Let’s go somewhere with this access_token to figure out what’s going and the overall lifecycle. Go to following link: aka.ms/ge

This is the URL to Microsoft’s Graph Explorer. If you are not logged in to the Graph Explorer, please do so.

17. You can click on GET my profile and then you will be able to see the URL shown. Otherwise it will already be there. So go ahead and copy the following URL

18. Now, copy the Bearer token aka the access_token. Head over to Postman. Open a new GET request and paste the link. Select Type > Bearer Token

19. Paste the Bearer token here. Click Send.

20. So it successfully went to the Microsoft Graph API and pulled my profile information using that Bearer token. Here’s the response.

Demo ends here.

Using Bearer Tokens for Accessing Resources

Bearer tokens acquired through the Microsoft Authentication Library (MSAL) can be used in an application to authenticate and authorize access to resources.

Token Acquisition and Inclusion in Requests

When a user signs in using MSAL, the library obtains an access token from Azure Active Directory (Azure AD) on behalf of the user. This token is then included in the Authorization header of requests made to protected APIs.

Token Validation and Authorization

The API validates the token by verifying its signature and checking its claims, such as the audience and issuer. If the token is valid, the API grants the requested access to the user.

Token Expiration

If the bearer token acquired through MSAL expires, the application will need to obtain a new token before attempting to access any protected resources.

Handling Expired Tokens

When an expired token is presented to a resource server, the server will reject the token and return a 401 Unauthorized HTTP status code. At this point, the client application should request a new token using MSAL and then attempt the request again with the new token.

Automatic Token Acquisition

It’s important to note that MSAL will automatically attempt to acquire a new token if an expired token is presented.

Manual Handling of Token Expiration

However, in some cases, the application may need to handle this scenario manually, for example if the expiration time of the token is shorter than the expected time required to complete a long-running operation. In such cases, the application should check the expiration time of the token and request a new one if necessary.

User Authentication with Token-based Authorization

Overview

The Vue.js component in the LBFE project is a simple login mechanism that uses the Microsoft Authentication Library (MSAL) to authenticate users with Azure Active Directory (AAD) and obtain a Bearer token to access secured web APIs. The component is structured as a single-file Vue.js component that consists of a script section, a template section, and a style section. The script section contains the component’s logic, which includes the configuration settings for MSAL, the functions for obtaining a Bearer token and retrieving user data from the Microsoft Graph API, and the evaluation of user permissions based on their profile information.

To obtain a Bearer token, the component uses the MSAL library to create a new UserAgentApplication instance with the provided MSAL configuration settings. Upon clicking the login button, the component will prompt the user to log in with their AAD credentials using the loginPopup function provided by MSAL. If the login is successful, the component will then call the getTokenSilent function to silently acquire a Bearer token.

After obtaining the Bearer token, the component will use it to retrieve the user’s profile information from the Microsoft Graph API by making an HTTP request to the endpoint “https://graph.microsoft.com/beta/me”. The user’s profile information is then passed to the evalUserPermission function to determine the user’s permission level based on their job title. Depending on their permission level, the component will then redirect the user to a specific page or display an invalid credentials page.

Component Structure

This component consists of a Vue.js template, a Vue.js script, and a CSS style sheet.

Template

The template includes a button labeled “Log In”, which triggers the authentication process when clicked. The template tag defines the component’s HTML markup. The button element is used to trigger the runMSALGetToken function when the user clicks it.

Script

The script is responsible for handling the authentication process. It includes the following 

1. The script tag imports the msalConfig and Msal modules. The msalConfig module contains the configuration settings for the MSAL library, such as the client ID and tenant ID. The Msal module provides the MSAL API, which is used to authenticate users and retrieve their data.
2. The data function defines the component’s data. The client variable is an instance of the MSAL UserAgentApplication class. The request variable is an object that specifies the scopes that the user is authorized to access.
3. Script defines an async function getTokenSilent that retrieves a token from the cache if it is available, or acquires a new token silently. The getTokenSilent function asynchronously acquires a token for the user without requiring the user to sign in. 
4. The getUserMSData function asynchronously retrieves the user’s data from the Microsoft Graph API using the token that was acquired by the getTokenSilent function. This function uses the access token to request user data from the Microsoft Graph API. It does this by calling the fetch() method with the following URL:

Code snippet

https://graph.microsoft.com/beta/me

5. The storeToken function stores the token in a local store. 
6. The evalUserPermission function evaluates the user’s permissions and redirects the user to the appropriate page. The function first checks the user’s job title. If the user is an admin, the function redirects the user to the http://localhost:8000/calendar page. If the user is a driver, the function redirects the user to the http://localhost:8000/driver page. If the user does not have any permissions, the function redirects the user to an error page.
7. The fetch method takes a request object as its argument. The request object specifies the URL of the resource to be fetched and the headers to be sent with the request. In this case, the request object specifies the following headers:

Authorization: Bearer <access_token>

8. The Authorization header specifies the Bearer token that was obtained from the MSAL client object.
9. The runMSALGetToken function is the main entry point for the component. This function calls the getTokenSilent function to acquire a token for the user and then calls the getUserMSData function to retrieve the user’s data.

Authentication Process

When the user clicks the “Log In” button, the runMSALGetToken function is called. This function initiates the authentication process by calling the loginPopup method on the ‘UserAgentApplication’ object, which opens a popup window for the user to enter their credentials. Once the user successfully signs in, the getUserMSData function is called to retrieve the user’s data from the MS Graph API. The token obtained from the authentication process is passed as an authorization header with the request to the MS Graph API.

Token Fetch

In the single-file Vue.js component, the Bearer token is being fetched in the getTokenSilent function. This function calls the acquireTokenSilent method of the client instance of the ‘UserAgentApplication’ class, which is provided by MSAL. This method acquires a token silently using the cached access token if it is not expired. If it is expired or not cached, it will initiate a silent token acquisition request with the authorization server to obtain a new access token. Once the token is acquired, it is passed as a Bearer token in the Authorization header of the HTTP request to the Microsoft Graph API to fetch the user data.

Token Storage

The token obtained from the authentication process is stored in the cache for later use. The getTokenSilent function retrieves the token from the cache if it is available, or acquires a new token silently if it has expired or has not been cached.

Redirect

Once the user’s data is retrieved, the evalUserPermission function is called to determine which page to redirect to based on the user’s job title. Currently, the function redirects the user to either the “driver” page or the “calendar” page, depending on the job title.