@cleavelandprice/authentication NPM

@cleavelandprice/authentication

Authentication is an Angular 12+ library providing foundational functionality to Cleaveland/Price applications.

Installation

To install this library, run:

$ npm install @cleavelandprice/authentication

Prerequisites

This library requires the following:

@auth0/angular-jwt (third-party, required for Authentication token management)
@angular/material (If using the login components provided in this package)
@cleavelandprice/dialog (If using the login components provided in this package)
@cleavelandprice/sharepoint (If using the login components provided in this package)

Note: Even if you are using the login components provided in this package, the sharepoint package is optional. If it is present, the login component will attempt to retreive the photo for the logged-in user. If the sharepoint package is not present, the photo will simply not be displayed.

To install the prerequisites, run:

npm install @auth0/angular-jwt
ng add @angular/material
npm install @cleavelandprice/dialog
npm install @cleavelandprice/sharepoint

Consuming Authentication

After installing the Authentication package, the authentication module must be imported in your AppModule file:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { AuthenticationModule } from '@cleavelandprice/authentication';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,

    AuthenticationModule.forRoot({apiUrl: 'http://utilityapi/authenticate/token'})
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

The Authentication module provides a component and a service that allows you to perform Active/Directory authentication. You can tap into this functionality "manually" - meaning that you construct the interface to acquire user credentials and pass it into the service call, and you have complete control over the user interface before, during, and after authentication.

Or, you may choose to simply use the authentication-login component, which performs all of the heavy lifting for you. By simply including the authentication-login tag in your HTML markup, the Authentication module provides its own login interface, built with Angular Material components, and displays the user's photo after authentication. This method requires no manual coding or user interface construction. It's well suited as a drop-in component for a toolbar.

Regardless of which of the two approaches you decide to take, the Authentication module will handle management of the authentication token, saving it in the browser's Local Storage and automatically retrieving it the next time the user visits the page - preventing them from having to re-authenticate each time.

The Authentication module also allows the developer to (optionally) specify an Active Directory group that a user must belong to in order to be considered an administrator of the application. When the web service returns the authentication token, an Admin flag will be set to true or false depending on whether or not the user belongs to the group specified. It is then up to the developer to customize the user's experience within the app based on this value. In some cases, it may even be desireable for the app to restrict login to only members of the specified group. In such a case, you would perform the authentication and implement some additional logic after authentication completes via the observable subscribe() method. If the user isn't an Admin (because they don't belong to the group), you would call the logout() method of the AuthenticationService and display a message informing them that they can't login without the required group membership.

Since the LoginComponent also displays a login form that utiliizes Angular Material components, you will need to install @angular/material and reference an Angular Material theme stylesheet. For more thorough up-to-date documentation on Angular Material, please visit the Angular Material site.

Using the Authentication service (manual login/logout)

import { AuthenticationService } from '@cleavelandprice/authentication';

@Component({
  selector: 'app-authentication',
  template: `
    <input type="text" [(ngModel)]="username">
    <input type="text" [(ngModel)]="password">
    <img *ngIf="authenticationService.authenticated && authenticationService.authenticatedUser.photoUrl"
      [src]="authenticationService.authenticatedUser.photoUrl" />
    <button (click)="login()">Login</button>
    <button (click)="logout()">Logout</button>
    `
})
export class AuthenticationComponent implements OnInit {
  username: string;
  password: string;
  adminGroup = 'App Admins'; // Optional AD group specifying who is an admin of this app
  requiredGroup: boolean; // Optional login restriction

  // Inject the AuthenticationService into this component
  constructor(public authenticationService: AuthenticationService) {}

  ngOnInit(): void {
    // If we're requiring the user to be in a certain group to login, then check it after login
    // If not a valid member, then log them out
    this.authenticationService.authenticatedChanged
      .subscribe(() => {
        if (this.authenticationService.authenticated) {
          if (this.adminGroup && this.requiredGroup) {
            if (!this.authenticationService.authenticatedUser.admin) {
              this.logout();
              alert(`You are not a member of '${this.adminGroup}'`);
              return;
            }
          }
          alert('Logged in');
        } else {
          alert('Logged out');
        }
      });
  }

  login() {
    if (this.username && this.password) {
      this.authenticationService.login(this.username, this.password, this.adminGroup);
    }
  }

  logout() {
    this.authenticationService.logout();
  }
}