IO-Routing-Auth-Library

Introduction

The IO-Routing-Auth-Library is designed to facilitate authentication in Angular applications via the IntraOffice Authentication Gateway.

Demo

For hands-on experience, download and try out the Demo App from our GitHub repository.

Installation

Run the following command to install the library:

npm install io-routing-auth-library

Peer Dependencies

Make sure to install all peer dependencies:

npm install crypto-js jwt-decode rxjs

Configuration

First, you'll need to provide the required configuration using Angular's Dependency Injection.

import { AUTHGATEWAYCONFIG, IAuthGatewayConfig } from 'io-routing-auth-library';

const myAuthGatewayConfig: IAuthGatewayConfig = {
  testJwt: null,
  gateWayUrl: 'https://authentication-dev.intraofficesigning.com/acme-dev',    
  returnUrl: '', // Keep this value empty for production
  aud: 'io-acme-dev', 
  tenant: 'acme', 
  roles: ['supervisor'],  
  includeUrls: ['https://myProtectedApi.azurewebsites.net'] // List of external url's that are protected 
};


  providers: [
    { provide: AUTHGATEWAYCONFIG, useValue: myAuthGatewayConfig }
  ]

Using Interceptor

Additionally, you need to add the interceptor into your application.

import { HTTP_INTERCEPTORS } from '@angular/common/http';
import { AuthGatewayInterceptor } from 'io-routing-auth-library';

  providers: [
    {
      provide: HTTP_INTERCEPTORS,
      useClass: AuthGatewayInterceptor,
      multi: true,
    }
  ]

Adding Authentication Services

To include your authentication services, you can provide them using Angular's DI system. You can even provide multiple different implementations of authentication services. For example, if you are using GatewayAuthService as one of your authentication services, you would add this to your providers array in the AppModule:

{
  provide: AUTH_SERVICES, 
  useClass: AuthService,
  multi: true
}

HttpClientModule

Import HttpClientModule in your Angular module:

import { HttpClientModule } from '@angular/common/http';


  imports: [
    HttpClientModule,
    // ...other modules
  ]

This is a necessary step as the library uses HttpClient internally.

Required Route Configuration

To make the library function correctly, you must add the following routes to your Angular application's routing configuration:

{ path: 'auth', component: AuthRedirectHandlerComponent },
{ path: 'noaccess', component: NoAccessPageComponent },
{ path: 'signedout', component: SignedOutPageComponent }

Hash-based Routing

It's important to note that hash-based routing (useHash: true) is not compatible with the Authentication Gateway's redirect mechanism. Make sure to set useHash: false in your route configuration. For example:

@NgModule({
  imports: [RouterModule.forRoot(routes, { useHash: false })],
  exports: [RouterModule]
})

Failure to configure these routes and settings will lead to authentication and redirection issues.

Usage

HTTPS and URL Registration

1. HTTPS Requirement: The Authentication Gateway requires that your application runs over HTTPS. Make sure to configure your development and production environments accordingly.

2. URL Registration: The URL of your application needs to be registered in the Authentication Gateway settings. Contact the gateway administrator or consult the gateway documentation to perform this registration.

Failure to meet these requirements will result in authentication errors.

Secure a Route

To secure a route, use AuthGatewayGuardService in your routing configuration.

import { AuthGatewayGuardService } from 'io-routing-auth-library';

const routes: Routes = [
  {
    path: 'protected',
    component: YourProtectedComponent,
    canActivate: [AuthGatewayGuardService]
  },
];

This will secure the /protected route according to the roles and other configurations set.