@azure/msal-angular

What is @azure/msal-angular?

@azure/msal-angular is a library that allows Angular applications to authenticate users with Microsoft Identity Platform and obtain tokens to call Microsoft APIs such as Microsoft Graph or any API registered with the Microsoft identity platform.

What are @azure/msal-angular's main functionalities?

User Authentication

This code demonstrates how to set up the MSAL instance in an Angular application to enable user authentication with Microsoft Identity Platform.

import { MsalModule, MsalService, MSAL_INSTANCE } from '@azure/msal-angular';
import { PublicClientApplication } from '@azure/msal-browser';

export function MSALInstanceFactory() {
  return new PublicClientApplication({
    auth: {
      clientId: 'your-client-id',
      authority: 'https://login.microsoftonline.com/your-tenant-id',
      redirectUri: 'http://localhost:4200'
    }
  });
}

@NgModule({
  imports: [
    MsalModule
  ],
  providers: [{
    provide: MSAL_INSTANCE,
    useFactory: MSALInstanceFactory
  }, MsalService]
})
export class AppModule { }

Token Acquisition

This code demonstrates how to log in a user and acquire an access token silently for calling Microsoft Graph API or other APIs.

import { MsalService } from '@azure/msal-angular';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent {
  constructor(private authService: MsalService) {}

  login() {
    this.authService.loginPopup().subscribe(response => {
      console.log('Login successful', response);
    }, error => {
      console.error('Login failed', error);
    });
  }

  getToken() {
    this.authService.acquireTokenSilent({
      scopes: ['user.read']
    }).subscribe(response => {
      console.log('Token acquired', response.accessToken);
    }, error => {
      console.error('Token acquisition failed', error);
    });
  }
}

Guarding Routes

This code demonstrates how to protect routes in an Angular application using MsalGuard to ensure that only authenticated users can access certain routes.

import { MsalGuard } from '@azure/msal-angular';

const routes: Routes = [
  { path: 'profile', component: ProfileComponent, canActivate: [MsalGuard] }
];

@NgModule({
  imports: [RouterModule.forRoot(routes)],
  exports: [RouterModule]
})
export class AppRoutingModule { }

Other packages similar to @azure/msal-angular

angular-oauth2-oidc

angular-oauth2-oidc is a library for OAuth2 and OpenID Connect (OIDC) authentication in Angular applications. It provides similar functionalities to @azure/msal-angular, such as user authentication, token management, and route protection. However, it is more generic and can be used with various identity providers, not just Microsoft Identity Platform.

oidc-client

oidc-client is a JavaScript library for OpenID Connect (OIDC) and OAuth2 authentication. It can be used in various JavaScript frameworks, including Angular, to handle user authentication and token management. Unlike @azure/msal-angular, it is not specific to Angular and requires more manual setup for integration with Angular applications.

auth0-angular

auth0-angular is a library for integrating Auth0 authentication and authorization into Angular applications. It provides similar functionalities to @azure/msal-angular, such as user authentication, token management, and route protection. Auth0 is a third-party identity provider that supports various authentication methods and social logins.

README

Microsoft Authentication Library for Angular

Getting Started	AAD Docs	Library Reference	Support	Samples

MSAL for Angular enables client-side Angular web applications, running in a web browser, to authenticate users using Azure AD work and school accounts (AAD), Microsoft personal accounts (MSA) and social identity providers like Facebook, Google, LinkedIn, Microsoft accounts, etc. through Azure AD B2C service. It also enables your app to get tokens to access Microsoft Cloud services such as Microsoft Graph.

Installation

The MSAL Angular package is available on NPM:

npm install msal @azure/msal-angular --save

Guides

• Quickstart
• Upgrade Guide (0.x-1.x)
• Configuration

Version Support

At a minimum, MSAL Angular will follow the support schedule of the main Angular project. We may continue to support certain versions of Angular that are no under Active or LTS support from the main Angular project on a version-by-version basis, as defined below.

MSAL Angular version	MSAL support status	Supported Angular versions
1.x.x	Active development	6, 7, 8, 9
0.x.x	In maintenance	4, 5

Samples

• Angular Quickstart
• B2C Angular SPA
• Angular v6
• Angular v7
• Angular v8
• Angular v9

Usage

Prerequisites

Before using MSAL.js, register an application in Azure AD to get your clientId.

1. Include and initialize the MSAL module in your app module.

Import MsalModule into app.module.ts. To initialize MSAL module you are required to pass the clientId of your application which you can get from the application registration.

@NgModule({
    imports: [
        MsalModule.forRoot({
            auth: {
                clientId: "Your client ID"
            }
        })
    ]
})
export class AppModule {}

2. Secure the routes in your application

You can add authentication to secure specific routes in your application by just adding canActivate : [MsalGuard] to your route definition. It can be added at the parent or child routes.

{
    path: 'product',
    component: ProductComponent,
    canActivate: [MsalGuard],
    children: [
        {
            path: 'detail/:id',
            component: ProductDetailComponent
        }
    ]
}, {
    path: 'myProfile',
    component: MsGraphComponent,
    canActivate: [MsalGuard]
},

When a user visits these routes, the library will prompt the user to authenticate.

3. Get tokens for Web API calls

MSAL Angular allows you to add an Http interceptor (MsalInterceptor) in your app.module.ts as follows. MsalInterceptor will obtain tokens and add them to all your Http requests in API calls based on the protectedResourceMap.

@NgModule({
    imports: [
        MsalModule.forRoot({
            auth: {
                clientId: "Your client ID"
            }
        }, {
            protectedResourceMap: [
                ['https://graph.microsoft.com/v1.0/me', ['user.read']],
                ['https://api.myapplication.com/users/*', ['customscope.read']]
            ]
        })
    ],
    providers: [
        ProductService, 
        {
            provide: HTTP_INTERCEPTORS,
            useClass: MsalInterceptor,
            multi: true
        }
    ]
})
export class AppModule {}

Using MsalInterceptor is optional and you can write your own interceptor if you choose to. Alternatively, you can also explicitly acquire tokens using the acquireToken APIs.

As of @azure/msal-angular@1.1.0, protectedResourceMap supports wildcard patterns that are supported by minimatch, and unprotectedResources is deprecated and ignored.

Note: When using wildcards, if multiple matching entries are found in the protectedResourceMap, the first match found will be used (based on the order of the protectedResourceMap).

4. Subscribe to event callbacks

MSAL wrapper provides below callbacks for various operations. For all callbacks, you need to inject BroadcastService as a dependency in your component/service and also implement a handleRedirectCallback:

this.authService.handleRedirectCallback((authError, response) => {
    // do something here
});

1. Login-related events (loginPopup/loginRedirect)

this.broadcastService.subscribe("msal:loginFailure", payload => {
    // do something here
});

this.broadcastService.subscribe("msal:loginSuccess", payload => {
    // do something here
});

1. Token-related events (acquireTokenSilent()/acquireTokenPopup()/acquireTokenRedirect())

this.broadcastService.subscribe("msal:acquireTokenSuccess", payload => {
    // do something here
});

this.broadcastService.subscribe("msal:acquireTokenFailure", payload => {
    // do something here
});

1. SSO-related events (ssoSilent())

this.broadcastService.subscribe("msal:ssoSuccess", payload => {
    // do something here
});

this.broadcastService.subscribe("msal:ssoFailure", payload => {
    // do something here
});

1. It is extremely important to unsubscribe. Implement ngOnDestroy() in your component and unsubscribe.

 private subscription: Subscription;

 this.subscription = this.broadcastService.subscribe("msal:acquireTokenFailure", (payload) => {});

 ngOnDestroy() {
    this.broadcastService.getMSALSubject().next(1);
    if (this.subscription) {
      this.subscription.unsubscribe();
    }
  }

MSAL Angular Public API

Login and AcquireToken APIs

The wrapper exposes APIs for login, logout, acquiring access token and more.

1. loginRedirect()
2. loginPopup()
3. logOut()
4. acquireTokenSilent()
5. acquireTokenPopup()
6. acquireTokenRedirect()
7. getAccount()
8. ssoSilent()

Advanced Topics

Logging

The logger definition has the following properties. Please see the config section for more details on their use:

1. correlationId
2. level
3. piiLoggingEnabled

You can enable logging in your app as shown below:

export function loggerCallback(logLevel, message, piiEnabled) {
    console.log(message);
}

@NgModule({
    imports: [ MsalModule.forRoot({
        auth: {
            clientId: 'Your client ID',
        },
        system: {
            logger: new Logger(loggerCallback, {
                correlationId: '1234',
                level: LogLevel.Verbose,
                piiLoggingEnabled: true,
            }),
        }
    })]
})

Multi-Tenant

By default, you have multi-tenant support since MSAL sets the tenant in the authority to 'common' if it is not specified in the config. This allows any Microsoft account to authenticate to your application. If you are not interested in multi-tenant behavior, you will need to set the authority config property as shown above.

If you allow multi-tenant authentication, and you do not wish to allow all Microsoft account users to use your application, you must provide your own method of filtering the token issuers to only those tenants who are allowed to login.

Security

Tokens are accessible from Javascript since MSAL is using HTML5 storage. Default storage option is sessionStorage, which keeps the tokens per session. You should ask user to login again for important operations on your app. You should protect your site for XSS. Please check the article here: https://www.owasp.org/index.php/XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet

CORS API usage

MSAL will get access tokens using a hidden Iframe for given CORS API endpoints in the config. To make CORS API call, you need to specify your CORS API endpoints as a map in the Angular config.

export const protectedResourceMap:[string, string[]][]= [
    ['https://buildtodoservice.azurewebsites.net/api/todolist', [ 'api://a88bb933-319c-41b5-9f04-eff36d985612/access_as_user' ]],
    ['https://graph.microsoft.com/v1.0/me', ['user.read']]
];

@NgModule({
    imports: [
        MsalModule.forRoot({
            auth: {
                clientId: 'Your client ID',
            }
        }, {
            protectedResourceMap : protectedResourceMap
        })
    ]
})

In your API project, you need to enable CORS API requests to receive flight requests.

Internet Explorer support

This library supports Internet Explorer 11 with the following configuration:

• For CORS API calls, the Iframe needs to access the cookies for the same domain that you did the initial sign in on. IE does not allow to access cookies in Iframe for localhost. Your URL needs to be fully qualified domain i.e http://yoursite.azurewebsites.com. Chrome does not have this restriction.
• If you put your site in the trusted site list, cookies are not accessible for Iframe requests. You need to remove protected mode for Internet zone or add the authority URL for the login to the trusted sites as well.
• IE may clear local storage when navigating between websites in different zones (e.g. your app and the login authority), which results in a broken experience when returning from the login page. To fix, set storeAuthStateInCookie to true.
• There are known issues with popups in IE. We recommend using redirect flows by setting popUp to false.

It is recommended that these properties are set dynamically based on the user's browser.

const isIE =
    window.navigator.userAgent.indexOf("MSIE ") > -1 ||
    window.navigator.userAgent.indexOf("Trident/") > -1;

MsalModule.forRoot({
    // ...
    cache: {
        storeAuthStateInCookie: ieIE
    }
}, {
    popUp: !isIE
});

Community Help and Support

• FAQs for access to our frequently asked questions
• Stack Overflow using tag "msal". We highly recommend you ask your questions on Stack Overflow first and browse existing issues to see if someone has asked your question before.
• GitHub Issues for reporting a bug or feature requests
• User Voice page to provide recommendations and/or feedback

Contribute

We enthusiastically welcome contributions and feedback. Please read the contributing guide before you begin.

Build and running tests

If you want to build the library and run all the unit tests, you can do the following.

First navigate to the root directory of the library(msal-angular) and install the dependencies:

npm install

Then use the following command to build the library and run all the unit tests:

npm run build

npm run test

Versioning

This library controls how users sign-in and access services. We recommend you always take the latest version of our library in your app when possible. We use semantic versioning so you can control the risk associated with updating your app. As an example, always downloading the latest minor version number (e.g. x.y.x) ensures you get the latest security and feature enhanements but our API surface remains the same. You can always see the latest version and release notes under the Releases tab of GitHub.

Security Reporting

If you find a security issue with our libraries or services please report it to [e-mail] with as much detail as possible. Your submission may be eligible for a bounty through the Microsoft Bounty program. Please do not post security issues to GitHub Issues or any other public site. We will contact you shortly upon receiving the information. We encourage you to get notifications of when security incidents occur by visiting this page and subscribing to Security Advisory Alerts.

License

Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License (the "License");

We Value and Adhere to the Microsoft Open Source Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.