Skip to content

IDP Client-Side Implementation Overview (Version 1)

Introduction

The client-side IDP implementation provides device registration, token management, and authentication for Angular applications. It consists of several key components that work together to handle the complete authentication flow from device registration through token refresh and usage.

Architecture Overview

┌─────────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
│   IDP Registration  │    │   Token Storage  │    │   Authentication    │
│   Flow              │───►│   & Management   │───►│   Usage             │
└─────────────────────┘    └──────────────────┘    └─────────────────────┘
        │                           │                         │
        ├─ Device Code Entry        ├─ Secure Storage         ├─ HTTP Interceptor
        ├─ OTP Activation           ├─ Token Refresh          ├─ WebSocket Headers
        └─ Startup Task             └─ Expiration Check       └─ Session Management

Core Components

1. IDP Service (idp.service.ts)

The central service managing all IDP operations:

Key Responsibilities:

  • Device Registration: Handles OTP-based device activation with external IDP endpoints
  • Token Management: Orchestrates OAuth2 client credentials flow for token acquisition
  • Secure Storage Integration: Manages encrypted storage of credentials using Capacitor's SecureStoragePlugin
  • Token Lifecycle: Handles parsing, validation, expiration checking, and automatic refresh
  • Error Recovery: Implements fallback mechanisms and retry logic for network failures

Storage Management:

The service manages multiple secure storage keys for different credential types: - Token endpoint URLs - Client credentials (ID and secret) - Access tokens and parsed JWT claims - Refresh tokens and expiration timestamps

2. Device Registration Flow

IdpDeviceCodeEntryComponent (idp-device-code-entry.component.ts)

A modal dialog component that provides the user interface for device registration:

Functionality: - Presents a form for OTP/device code entry with validation - Provides user options to either proceed with registration or skip the process - Handles error states and provides visual feedback to users - Returns structured data indicating user's choice and entered code

IdpPersonalizationStartupTask (idp-personalization.startup-task.ts)

A startup task that orchestrates the complete device registration and personalization flow:

Registration Orchestration: 1. Dialog Management: Opens the device code entry dialog and waits for user input 2. Device Registration: Calls the IDP service to register the device with the provided OTP 3. Token Acquisition: Uses returned client credentials to obtain access tokens 4. Token Processing: Parses JWT tokens to extract device and server information 5. Personalization Setup: Configures the application with extracted data (server URL, app ID, device ID)

3. Authentication Integration

AuthInterceptor (auth-interceptor.service.ts)

An HTTP interceptor that provides transparent authentication for all outgoing requests:

Token Management: - Automatic Token Attachment: Adds Bearer tokens to HTTP request headers transparently - Expiration Detection: Checks token validity before each request to prevent authentication failures - Proactive Refresh: Attempts to refresh expired tokens automatically in the background - Fallback Strategy: Uses cached tokens when refresh operations fail due to network issues - Transparent Operation: Requires no changes to existing HTTP client usage patterns

Request Processing Flow: 1. Intercepts all outgoing HTTP requests before they leave the application 2. Retrieves and validates stored authentication tokens from secure storage 3. Attempts token refresh if expiration is detected or imminent 4. Clones requests with appropriate Authorization headers attached 5. Handles authentication failures gracefully with appropriate error responses

SessionService WebSocket Integration (session.service.ts)

Manages WebSocket connections with integrated IDP authentication:

WebSocket Authentication: - Header Injection: Includes IDP tokens in WebSocket connection headers for server authentication - Session Continuity: Maintains authentication state across connection events and reconnections - Dynamic Headers: Updates authentication information for new connections and reconnection attempts - Multi-Context Support: Integrates various client contexts and personalization data into connection headers

Connection Management: - Negotiates WebSocket URLs through discovery service integration - Handles connection state changes, disconnections, and automatic recovery - Implements heartbeat and keepalive mechanisms for connection stability - Manages subscription lifecycle with proper cleanup and resource management

Data Flow & State Management

1. Registration Flow

User Enters OTP ──► Device Registration ──► Token Acquisition ──► Personalization Setup
      │                    │                      │                      │
      ├─ Modal Dialog      ├─ API Call           ├─ OAuth2 Flow         ├─ Extract Claims
      ├─ Form Validation   ├─ Clear Old Data     ├─ Store Credentials   ├─ Set Server URL
      └─ Error Handling    └─ Timeout Handling   └─ Parse JWT Token     └─ Set Device ID

2. Token Lifecycle

Token Creation ──► Secure Storage ──► Usage ──► Expiration Check ──► Refresh
      │                 │              │            │                  │
      ├─ JWT Parsing    ├─ Capacitor   ├─ HTTP      ├─ Interceptor     ├─ OAuth2 Flow
      ├─ Claims Extract ├─ Platform    ├─ WebSocket ├─ Automatic       ├─ New Token
      └─ Expiry Calc    └─ Secure      └─ Headers   └─ Detection       └─ Update Storage