Docs: oidc - rollthecloudinc/quell GitHub Wiki

Documentation for Angular OIDC Library

Table of Contents

  1. Introduction
  2. Installation
  3. Overview
  4. Key Concepts
    • OpenID Connect Integration
    • State Management
    • Cookie-Based Session Handling
    • HTTP Interceptors
  5. Core Components
    • OidcModule
    • Effects (OidcAuthEffects)
  6. Key Services
    • AuthWebStorageService
    • User Manager Factory
  7. Usage
    • Configuration
    • Handling Authentication Lifecycle
  8. API Reference
  9. Examples
  10. Testing

1. Introduction

The Angular OIDC (OpenID Connect) Library simplifies the integration of OpenID Connect authentication into Angular applications. By leveraging the oidc-client library, it provides features for managing user sessions, handling authentication callbacks, and utilizing cookies for session storage. Additionally, it integrates seamlessly with NgRx for state management and offers effects for handling authentication workflows dynamically.

2. Installation

To install the library and its dependencies, use npm:

npm install oidc-client ngrx @rollthecloudinc/auth

3. Overview

The Angular OIDC Library enables applications to authenticate users using OpenID Connect and provides tools for managing authentication state, tokens, and cookies across platforms (browser and server-side).

Features:

  • OpenID Connect Authentication: Supports login, logout, and authentication callbacks.
  • NgRx Integration: Manages authentication state and workflows using NgRx effects.
  • Cookie-Based Session Storage: Persists user session data securely.
  • HTTP Interceptors: Handles authorization headers for authenticated API calls.
  • Effects-Driven Logic: Streamlines workflows such as authentication and user data retrieval.

4. Key Concepts

4.1 OpenID Connect Integration

The library uses the oidc-client library for integrating OpenID Connect workflows:

  • Login: Redirects users to the authentication provider.
  • Logout: Offers a logout mechanism via OIDC workflows.
  • Callback Handling: Processes authentication redirects using OIDC client-side routing.

4.2 State Management

State management for authentication workflows is handled using NgRx. It includes:

  • Actions such as Login, Logout, and CompleteAuthentication.
  • Effects, such as login redirection (login$) and handling authentication callbacks (completeAuthentication$).

4.3 Cookie-Based Session Handling

The library uses cookies for storing authentication data, enhancing security and enabling server-side storage for OpenID sessions. It provides methods for reading, setting, and managing cookies. The AuthWebStorageService is responsible for managing session storage across platforms.

4.4 HTTP Interceptors

The TokenInterceptor automatically attaches authentication tokens to outgoing HTTP requests, ensuring that requests are authenticated wherever necessary.

5. Core Components

5.1 OidcModule

The OidcModule serves as the entry point for the library. It registers metadata, provides the user manager, and includes effects for handling authentication workflows.

Configuration Example:

import { OidcModule } from './oidc.module';

@NgModule({
  imports: [
    OidcModule.forRoot(),
  ],
})
export class AppModule {}

5.2 Effects (OidcAuthEffects)

The OidcAuthEffects manage authentication workflows dynamically based on dispatched actions.

Key Effects:

  • login$: Redirects the user to the authentication provider.
  • logout$: Handles logout workflows.
  • completeAuthentication$: Processes authentication callbacks and sets the user in state.

6. Key Services

6.1 AuthWebStorageService

Manages authentication data across platforms (browser/server) and provides methods for storage and cookie handling.

Key Features:

  • Securely stores authentication tokens and user information in session storage or cookies.
  • Transfers authentication state across the browser and server using Angular Universal’s TransferState.

6.2 User Manager Factory

The userManagerFactory initializes a UserManager instance from the oidc-client library with custom settings, utilizing web storage and state management.

Example Usage:

const userManager = userManagerFactory(clientSettings, authWebStorage);

7. Usage

7.1 Configuration

Configure and bootstrap the library in the root module of your application.

App Module Configuration:

import { OidcModule } from './oidc.module';

@NgModule({
  imports: [
    OidcModule.forRoot(),
  ],
})
export class AppModule {}

7.2 Handling Authentication Lifecycle

Login Workflow: Use effects to initiate login redirection through OpenID Connect.

this.authFacade.login(); // Triggers login effect

Authentication Callback Workflow: Handle authentication callbacks using OpenID Connect.

this.authFacade.completeAuthentication(); // Processes tokens and updates authentication state

8. API Reference

Classes

  1. OidcModule: Core module for OpenID Connect workflows.
  2. AuthWebStorageService: Handles session storage and cookies.
  3. OidcAuthEffects: Manages authentication workflows using NgRx effects.

Models

  1. ClientSettings: Represents OIDC client configuration, including authority, client ID, redirect URIs, and metadata.

Factory Methods

  1. userManagerFactory: Creates and initializes a UserManager instance.
  2. authWebStorageFactory: Creates a AuthWebStorageService instance for managing storage and cookies.
  3. initAuthFactory: Bootstraps authentication lifecycle (e.g., retrieving the current user).

9. Examples

Example 1: Basic Authentication Integration

Login Workflow:

import { AuthFacade } from '@rollthecloudinc/auth';

constructor(private authFacade: AuthFacade) {}

ngOnInit() {
  this.authFacade.login();
}

Callback Handling:

import { AuthFacade } from '@rollthecloudinc/auth';

constructor(private authFacade: AuthFacade) {}

ngOnInit() {
  this.authFacade.completeAuthentication();
}

Example 2: HTTP Interceptor for Token Injection

Integrate the TokenInterceptor into your application using the HTTP_INTERCEPTORS provider.

Configuration in App Module:

import { HTTP_INTERCEPTORS } from '@angular/common/http';
import { TokenInterceptor } from './lib/http-interceptors/token-interceptor';

@NgModule({
  providers: [
    { provide: HTTP_INTERCEPTORS, useClass: TokenInterceptor, multi: true },
  ],
})
export class AppModule {}

The TokenInterceptor will attach the idToken to outgoing requests for authenticated endpoints automatically.

10. Testing

Service Testing (AuthWebStorageService):

Test the functionality of session storage and cookie handling:

import { TestBed } from '@angular/core/testing';
import { AuthWebStorageService } from './auth-web-storage.service';

describe('AuthWebStorageService', () => {
  let service: AuthWebStorageService;

  beforeEach(() => {
    TestBed.configureTestingModule({});
    service = TestBed.inject(AuthWebStorageService);
  });

  it('should create service instance', () => {
    expect(service).toBeTruthy();
  });

  it('should set and retrieve items', () => {
    const key = 'test-key';
    const value = 'test-value';
    service.setItem(key, value);
    expect(service.getItem(key)).toEqual(value);
  });

  it('should handle cookies correctly', () => {
    service.setCookie('test-cookie', 'cookie-value');
    expect(service.getCookie('test-cookie')).toEqual('cookie-value');
  });
});

Conclusion

The Angular OIDC Library efficiently integrates OpenID Connect workflows into Angular applications, offering authentication effects, NgRx state management, cookie-based session storage, and HTTP interceptors. It is highly configurable and can be extended to fit complex authentication scenarios in modern applications.

For contributions, feature requests, or issues, feel free to reach out!