@azure/msal-angular 4.0.11 → 4.0.13

package/docs/events.md

@@ -0,0 +1,262 @@
+# Events in MSAL Angular
+
+Before you start here, make sure you understand how to [initialize the application object](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-angular/docs/initialization.md).
+
+`@azure/msal-angular` uses the event system exposed by `@azure/msal-browser`, which emits events related to auth and MSAL, and can be used for updating UI, showing error messages, and so on.
+
+## Consuming events in your app
+
+Events in `@azure/msal-angular` are managed by the `MsalBroadcastService`, and are available by subscribing to the `msalSubject$` observable on the `MsalBroadcastService`. 
+
+Here is an example of how you can consume the emitted events in your application:
+```javascript
+import { MsalBroadcastService } from '@azure/msal-angular';
+import { EventMessage, EventType } from '@azure/msal-browser';
+
+export class AppComponent implements OnInit, OnDestroy {
+  private readonly _destroying$ = new Subject<void>();
+
+  constructor(
+    //...
+    private msalBroadcastService: MsalBroadcastService
+  ) {}
+
+  ngOnInit(): void {
+    this.msalBroadcastService.msalSubject$
+      .pipe(
+        // Optional filtering of events.
+        filter((msg: EventMessage) => msg.eventType === EventType.LOGIN_SUCCESS), 
+        takeUntil(this._destroying$)
+      )
+      .subscribe((result: EventMessage) => {
+        // Do something with the result
+      });
+  }
+
+  ngOnDestroy(): void {
+    this._destroying$.next(null);
+    this._destroying$.complete();
+  }
+}
+```
+
+Note that you may need to cast the `result.payload` as a specific type to prevent compilation errors. The payload type will depend on the event, and can be found in our documentation [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/events.md).
+
+```javascript
+ngOnInit(): void {
+  this.msalBroadcastService.msalSubject$
+    .pipe(
+      filter((msg: EventMessage) => msg.eventType === EventType.LOGIN_SUCCESS),
+    )
+    .subscribe((result: EventMessage) => {
+      // Casting payload as AuthenticationResult to access account
+      const payload = result.payload as AuthenticationResult;
+      this.authService.instance.setActiveAccount(payload.account);
+    });
+}
+```
+
+For the full example of using events, please see our sample [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-angular-samples/angular-modules-sample/src/app/home/home.component.ts).
+
+## Table of events
+
+For more information about the `EventMessage` object, including the full table of events currently emitted by `@azure/msal-browser` (including descriptions and related payloads), please see the documentation [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/events.md).
+
+## Handling errors with events
+
+As the `EventError` in `EventMessage` is defined as `AuthError | Error | null`, an error should be validated as the correct type before accessing specific properties on it. 
+
+See the example below of how an error can be cast to `AuthError` to avoid TypeScript errors:
+
+```javascript
+import { MsalBroadcastService } from '@azure/msal-angular';
+import { EventMessage, EventType } from '@azure/msal-browser';
+
+export class AppComponent implements OnInit, OnDestroy {
+  private readonly _destroying$ = new Subject<void>();
+
+  constructor(
+    //...
+    private msalBroadcastService: MsalBroadcastService
+  ) {}
+
+  ngOnInit(): void {
+    this.msalBroadcastService.msalSubject$
+      .pipe(
+        // Optional filtering of events
+        filter((msg: EventMessage) => msg.eventType === EventType.LOGIN_FAILURE), 
+        takeUntil(this._destroying$)
+      )
+      .subscribe((result: EventMessage) => {
+        if (result.error instanceof AuthError) {
+          // Do something with the error
+        }
+      });
+  }
+
+  ngOnDestroy(): void {
+    this._destroying$.next(null);
+    this._destroying$.complete();
+  }
+}
+```
+
+An example of error handling can also be found on our [MSAL Angular B2C Sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-angular-samples/angular-b2c-sample/src/app/app.component.ts#L129).
+
+## Syncing logged in state across tabs and windows
+
+If you would like to update your UI when a user logs in or out of your app in a different tab or window you can subscribe to the `ACCOUNT_ADDED` and `ACCOUNT_REMOVED` events. The payload will be the `AccountInfo` object that was added or removed.
+
+```javascript
+import { MsalService, MsalBroadcastService } from '@azure/msal-angular';
+import { EventMessage, EventType } from '@azure/msal-browser';
+
+export class AppComponent implements OnInit, OnDestroy {
+  private readonly _destroying$ = new Subject<void>();
+
+  constructor(
+    //...
+    private authService: MsalService,
+    private msalBroadcastService: MsalBroadcastService
+  ) {}
+
+  ngOnInit(): void {
+    this.authService.instance.enableAccountStorageEvents(); // Register the storage listener that will be emitting the events
+    this.msalBroadcastService.msalSubject$
+      .pipe(
+        // Optional filtering of events
+        filter((msg: EventMessage) => msg.eventType === EventType.ACCOUNT_ADDED || msg.eventType === EventType.ACCOUNT_REMOVED), 
+        takeUntil(this._destroying$)
+      )
+      .subscribe((result: EventMessage) => {
+        if (this.authService.msalInstance.getAllAccounts().length === 0) {
+          // Account logged out in a different tab, redirect to homepage
+          window.location.pathname = "/";
+        } else {
+          // Update UI to show user is signed in. result.payload contains the account that was logged in
+        }
+      });
+  }
+
+  ngOnDestroy(): void {
+    this._destroying$.next(null);
+    this._destroying$.complete();
+  }
+}
+```
+
+A full example can also be found in our [samples](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-angular-samples/angular-modules-sample/src/app/app.component.ts).
+
+## The inProgress$ Observable
+
+The `inProgress$` observable is also handled by the `MsalBroadcastService`, and should be subscribed to when application needs to know the status of interactions, particularly to check that interactions are completed. We recommend checking that the status of interactions is `InteractionStatus.None` before functions involving user accounts. 
+
+Note that the last / most recent `InteractionStatus` will also be available when subscribing to the `inProgress$` observable.
+
+See the example below for its use. A full example can also be found in our [samples](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-angular-samples/angular-modules-sample/src/app/home/home.component.ts#L29). A full list of interaction statuses can be found [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/src/utils/BrowserConstants.ts#L87).
+
+```js
+import { Component, OnInit, Inject, OnDestroy } from '@angular/core';
+import { MsalBroadcastService} from '@azure/msal-angular';
+import { InteractionStatus } from '@azure/msal-browser';
+import { Subject } from 'rxjs';
+import { filter, takeUntil } from 'rxjs/operators';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+  styleUrls: ['./app.component.css']
+})
+export class AppComponent implements OnInit, OnDestroy {
+  private readonly _destroying$ = new Subject<void>();
+
+  constructor(
+    private msalBroadcastService: MsalBroadcastService
+  ) {}
+
+  ngOnInit(): void {
+    this.msalBroadcastService.inProgress$
+      .pipe(
+        // Filtering for all interactions to be completed
+        filter((status: InteractionStatus) => status === InteractionStatus.None),
+        takeUntil(this._destroying$)
+      )
+      .subscribe(() => {
+        // Do something related to user accounts or UI here
+      })
+  }
+
+  ngOnDestroy(): void {
+    this._destroying$.next(null);
+    this._destroying$.complete();
+  }
+}
+
+```
+
+## Optional `MsalBroadcastService` Configurations
+
+The `MsalBroadcastService` can be optionally configured to replay past events when subscribed to. By default, events that are emitted after the `MsalBroadcastService` is subscribed to are available. There may be instances where events prior to subscription are needed. By providing a configuration for the `MsalBroadcastService` and setting the `eventsToReplay` parameter to a number, that number of past events will be available upon subscription. 
+
+For more information about replaying events, see the RxJS docs on ReplaySubjects [here](https://rxjs.dev/api/index/class/ReplaySubject).
+
+The `MsalBroadcastService` can be configured in the app.module.ts file as follows:
+
+```typescript
+// app.module.ts
+import { NgModule } from '@angular/core';
+import { HTTP_INTERCEPTORS } from '@angular/common/http';
+import { AppComponent } from './app.component';
+import { MsalModule, MsalService, MsalGuard, MsalInterceptor, MsalBroadcastService, MsalRedirectComponent, MSAL_BROADCAST_CONFIG } from "@azure/msal-angular"; // Import MsalBroadcastService and MSAL_BROADCAST_CONFIG here
+import { PublicClientApplication, InteractionType, BrowserCacheLocation } from "@azure/msal-browser";
+
+@NgModule({
+    imports: [
+        MsalModule.forRoot( new PublicClientApplication({ // MSAL Configuration
+            auth: {
+                clientId: "clientid",
+                authority: "https://login.microsoftonline.com/common/",
+                redirectUri: "http://localhost:4200/",
+                postLogoutRedirectUri: "http://localhost:4200/",
+                navigateToLoginRequestUrl: true
+            },
+            cache: {
+                cacheLocation : BrowserCacheLocation.LocalStorage,
+                storeAuthStateInCookie: true, // set to true for IE 11
+            },
+            system: {
+                loggerOptions: {
+                    loggerCallback: () => {},
+                    piiLoggingEnabled: false
+                }
+            }
+        }), {
+            interactionType: InteractionType.Popup, // MSAL Guard Configuration
+            authRequest: {
+              scopes: ['user.read']
+            },
+            loginFailedRoute: "/login-failed" 
+        }, {
+            interactionType: InteractionType.Redirect, // MSAL Interceptor Configuration
+            protectedResourceMap
+        })
+    ],
+    providers: [
+        {
+            provide: HTTP_INTERCEPTORS,
+            useClass: MsalInterceptor,
+            multi: true
+        },
+        {
+          provide: MSAL_BROADCAST_CONFIG, // Add configuration to providers here
+          useValue: {
+            eventsToReplay: 2 // Set how many events you want to replay when subscribing
+          }
+        },
+        MsalGuard,
+        MsalBroadcastService // Ensure the MsalBroadcastService is provided
+    ],
+    bootstrap: [AppComponent, MsalRedirectComponent]
+})
+export class AppModule {}
+```

package/docs/initialization.md

@@ -0,0 +1,206 @@
+# Initialization of MSAL Angular
+
+Before using `@azure/msal-angular`, [register an application in Azure AD](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app) to get your `clientId`.
+
+In this document:
+- [Initialization of MSAL](#initialization-of-msal-angular)
+    - [Include and initialize the MSAL module in your app module](#include-and-initialize-the-msal-module-in-your-app-module)
+    - [Secure the routes in your application](#secure-the-routes-in-your-application)
+    - [Get tokens for Web API calls](#get-tokens-for-web-api-calls)
+    - [Subscribe to events](#subscribe-to-events)
+- [Next Steps](#next-steps)
+
+## 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.
+
+```js
+import { NgModule } from '@angular/core';
+import { HTTP_INTERCEPTORS, HttpClientModule } from '@angular/common/http';
+import { AppComponent } from './app.component';
+import { MsalModule, MsalService, MsalGuard, MsalInterceptor, MsalBroadcastService, MsalRedirectComponent } from "@azure/msal-angular";
+import { PublicClientApplication, InteractionType, BrowserCacheLocation } from "@azure/msal-browser";
+
+@NgModule({
+    imports: [
+        MsalModule.forRoot( new PublicClientApplication({ // MSAL Configuration
+            auth: {
+                clientId: "Your client ID",
+                authority: "Your authority",
+                redirectUri: "Your redirect Uri",
+            },
+            cache: {
+                cacheLocation : BrowserCacheLocation.LocalStorage,
+                storeAuthStateInCookie: true, // Deprecated, will be removed in future version
+            },
+            system: {
+                loggerOptions: {
+                    loggerCallback: () => {},
+                    piiLoggingEnabled: false
+                }
+            }
+        }), {
+            interactionType: InteractionType.Redirect, // MSAL Guard Configuration
+        }, {
+            interactionType: InteractionType.Redirect, // MSAL Interceptor Configuration
+        })
+    ],
+    providers: [
+        {
+            provide: HTTP_INTERCEPTORS,
+            useClass: MsalInterceptor,
+            multi: true
+        },
+        MsalService,
+        MsalGuard,
+        MsalBroadcastService
+    ],
+    bootstrap: [AppComponent, MsalRedirectComponent]
+})
+export class AppModule {}
+```
+
+## 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. When a user visits these routes, the library will prompt the user to authenticate.
+
+See our [`MsalGuard` doc](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-angular/docs/msal-guard.md) for more details on configuration and considerations, including using additional interfaces.
+
+See this example of a route defined with the `MsalGuard`:
+
+```js
+import { NgModule } from '@angular/core';
+import { Routes, RouterModule } from '@angular/router';
+import { HomeComponent } from './home/home.component';
+import { ProfileComponent } from './profile/profile.component';
+import { MsalGuard } from '@azure/msal-angular';
+
+const routes: Routes = [
+    {
+        path: 'profile',
+        component: ProfileComponent,
+        canActivate: [MsalGuard]
+    },
+    {
+        path: '',
+        component: HomeComponent
+    },
+];
+
+@NgModule({
+    imports: [RouterModule.forRoot(routes)],
+    exports: [RouterModule]
+})
+export class AppRoutingModule { }
+```
+
+## Get tokens for Web API calls
+
+`@azure/msal-angular` allows you to add an Http interceptor (`MsalInterceptor`) in your `app.module.ts` as follows. The `MsalInterceptor` will obtain tokens and add them to all your Http requests in API calls based on the `protectedResourceMap`. See our [MsalInterceptor doc](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-angular/docs/msal-interceptor.md) for more details on configuration and use.
+
+```js
+import { NgModule } from '@angular/core';
+import { HTTP_INTERCEPTORS } from '@angular/common/http';
+import { AppComponent } from './app.component';
+import { MsalModule, MsalService, MsalGuard, MsalInterceptor, MsalBroadcastService, MsalRedirectComponent } from "@azure/msal-angular";
+import { PublicClientApplication, InteractionType, BrowserCacheLocation } from "@azure/msal-browser";
+
+@NgModule({
+    imports: [
+        MsalModule.forRoot( new PublicClientApplication({ // MSAL Configuration
+            auth: {
+                clientId: "Your client ID",
+                authority: "Your authority",
+                redirectUri: "Your redirect Uri",
+            },
+            cache: {
+                cacheLocation : BrowserCacheLocation.LocalStorage,
+                storeAuthStateInCookie: true, // Deprecated, will be removed in future version
+            },
+            system: {
+                loggerOptions: {
+                    loggerCallback: () => {},
+                    piiLoggingEnabled: false
+                }
+            }
+        }), {
+            interactionType: InteractionType.Redirect, // MSAL Guard Configuration
+        }, {
+            interactionType: InteractionType.Redirect, // MSAL Interceptor Configuration
+            protectedResourceMap: new Map([
+                ['https://graph.microsoft.com/v1.0/me', ['user.read']],
+                ['https://api.myapplication.com/users/*', ['customscope.read']],
+                ['http://localhost:4200/about/', null] 
+            ])
+        })
+    ],
+    providers: [
+        {
+            provide: HTTP_INTERCEPTORS,
+            useClass: MsalInterceptor,
+            multi: true
+        },
+        MsalService,
+        MsalGuard,
+        MsalBroadcastService
+    ],
+    bootstrap: [AppComponent, MsalRedirectComponent]
+})
+export class AppModule {}
+```
+
+Using the `MsalInterceptor` is optional. You may wish to explicitly acquire tokens using the acquireToken APIs instead.
+
+Please note that the `MsalInterceptor` is provided for your convenience and may not fit all use cases. We encourage you to write your own interceptor if you have specific needs that are not addressed by the `MsalInterceptor`. 
+
+## Subscribe to events
+
+MSAL provides an event system, which emits events related to auth and MSAL, and can be subscribed to as below. To use events, the `MsalBroadcastService` should be added to your constructor in your component/service. 
+
+### 1. How to subscribe to events
+
+```js
+import { EventMessage, EventType } from '@azure/msal-browser';
+import { filter } from 'rxjs/operators';
+
+this.msalBroadcastService.msalSubject$
+    .pipe(
+        filter((msg: EventMessage) => msg.eventType === EventType.LOGIN_SUCCESS)
+    )
+    .subscribe((result) => {
+        // do something here
+    });
+```
+
+### 2. Available events
+
+The list of events available to MSAL can be found in the [`@azure/msal-browser` event documentation.](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/events.md)
+
+### 3. Unsubscribing
+
+It is extremely important to unsubscribe. Implement `ngOnDestroy()` in your component and unsubscribe.
+
+```js
+import { EventMessage, EventType } from '@azure/msal-browser';
+import { filter, Subject, takeUntil } from 'rxjs';
+
+private readonly _destroying$ = new Subject<void>();
+
+this.msalBroadcastService.msalSubject$
+    .pipe(
+        filter((msg: EventMessage) => msg.eventType === EventType.LOGIN_SUCCESS),
+        takeUntil(this._destroying$)
+    )
+    .subscribe((result) => {
+        this.checkAccount();
+    });
+
+ngOnDestroy(): void {
+    this._destroying$.next(null);
+    this._destroying$.complete();
+}
+```
+
+# Next Steps
+
+You are ready to use `@azure/msal-angular` [public APIs](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-angular/docs/public-apis.md)!

package/docs/known-issues.md

@@ -0,0 +1,19 @@
+# Known issues for MSAL Angular
+
+## 2.0.0
+* MSAL Guard's `CanLoad` does not interactively prompt for login. This will be addressed in a future release.
+
+## 2.0.0-beta.6
+* Due to a security fix, the `MsalCustomNavigationClient` will not navigate client-side when `navigateToLoginRequestUrl` is set to true and handling redirects. This will be addressed in a future release.
+
+## 2.0.0-beta.4
+* When the MSAL Guard is used on the page used for the redirect URI, the `code=` hash may remain in the url. This is addressed in `2.0.0-beta.5`, except when the MSAL Guard is used for `canLoad`. To mitigate this issue, applications should not put the MSAL Guard on the page used for the redirect URI.
+
+## 2.0.0-alpha.3
+* MSAL Guard's `Canload` interface has a return type of `Observable<boolean|UrlTree>`, which is incompatible with the Angular 9 `CanLoad` base type. This is addressed in version `2.0.0-alpha.4`.
+
+## 2.0.0-alpha.0
+* Warnings related to `minimatch` and `path`: These warnings should not cause any problems and will be addressed in a future release.
+* IE11 is not supported: This is not currently supported in this version, but will be addressed in a future release.
+
+Please see the `@azure/msal-browser` [FAQ](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/FAQ.md#why-is-there-no-access-token-returned-from-acquiretokensilent) for additional known issues.

package/docs/logging.md

@@ -0,0 +1,47 @@
+# Logging in MSAL Angular
+
+The logger definition has the following properties:
+
+1. correlationId
+1. logLevel
+    * logLevels include: `Error`, `Warning`, `Info`, `Trace`, and `Verbose`
+1. piiLoggingEnabled
+
+You can enable logging in your app as shown below:
+
+```js
+import { LogLevel, PublicClientApplication } from '@azure/msal-browser';
+
+export function loggerCallback(logLevel: LogLevel, message: string) {
+    console.log(message);
+}
+
+@NgModule({
+    imports: [ 
+        MsalModule.forRoot(new PublicClientApplication({
+            auth: {
+                clientId: 'Your client ID',
+            },
+            system: {
+                loggerOptions: {
+                    loggerCallback,
+                    piiLoggingEnabled: true,
+                    logLevel: LogLevel.Info
+                }
+            }
+        }))
+    ]
+})
+```
+
+The `logger` can also be set dynamically by using `MsalService.setLogger()`.
+
+```js
+this.authService.setLogger(new Logger({
+    loggerCallback: (logLevel, message, piiEnabled) => {
+        console.log('MSAL Logging: ', message);
+    },
+    piiLoggingEnabled: false,
+    logLevel: LogLevel.Info
+}));
+```