Pluggable Authentication Mechanism

This document describes a 3-step authentication verification flow using OpenAPI specifications.

Overview

The pluggable authentication mechanism implements an asynchronous polling pattern that allows for flexible authentication methods (magic links, SMS, email verification, etc.) while maintaining a consistent API interface and reusing existing verification infrastructure.

Authentication Flow

Step 1: Authentication Initiation

The UI starts the authentication process by calling:

POST /verification-srv/authentiaction/:method/initiation

Request Payload:

• requestid: Unique request identifier
• identifier: User identifier (email, phone, etc.)
• verification_challenge: Contains challenge data like challengeid

Response:

• exchange_id: Session management object with expiration
• sub: Masked subject identifier for the user
• status_id: Used to track verification status
• server_challenge: Contains redirect URI for next steps

Step 2 & 3: External Service Integration

The verification service makes a backend call to an external SPI (Service Provider Interface):

POST /external-srv/verify/

Key Process:

1. Uses client_id from the settings to create and cache a token
2. Calls the configured SPI endpoint with verification data

Request Includes:

• status_id: Links back to the original request
• identifier: User identifier
• requestId: Original request ID
• sub: Subject identifier
• verification_challenge: Challenge data (flexible structure)

Response (202 Accepted):

• redirect_uri: Where to redirect the user
• message: Status message

Step 4 & 5: Status Update

Updates the verification status once authentication is complete:

PUT /verification-srv/verificationstatus/:status_id

Request:

• status: Set to "AUTHENTICATED" upon success
• deviceInformation: Optional device metadata

Architecture Pattern

This implements an asynchronous polling pattern where:

1. UI initiates the process
2. Backend orchestrates with external services
3. UI polls for status updates using the status_id
4. External service updates status when verification completes

Configuration Setup

In the context of pluggable verification, the config endpoint serves as the setup mechanism that defines how external authentication methods integrate with the cidaas verification system.

What the Config Does:

The /verification-actions-srv/config endpoint allows you to:

1. Register External Authentication Methods: Define custom verification types (like YOUR_EXTERNAL_AUTHENTICATION_METHOD) that aren't built into cidaas by default

2. Configure Service Provider Interface (SPI): Specify the external service URL that cidaas will call during Step 2 & 3 of the authentication flow

3. Set Authentication Details: Define how cidaas authenticates with your external service (OAuth2 client credentials, API keys, etc.)

4. Enable Pluggable Architecture: This configuration makes the verification system "pluggable" by allowing you to add new authentication methods without modifying cidaas core code

In the Authentication Flow:

When a user initiates verification with your custom method:

1. Step 1: User calls /verification-srv/authentication/YOUR_EXTERNAL_AUTHENTICATION_METHOD/initiation
2. Step 2: cidaas looks up the config you created to find your external service URL
3. Step 3: cidaas calls your configured endpoint using the auth details you specified (client_id is a client configured in cidaas)
4. Steps 4-5: Status updates flow back through the system

Example Use Cases:

• Custom MFA providers (hardware tokens, biometric services)
• Third-party authentication (corporate SSO, specialized identity providers)
• Business-specific verification (document verification, KYC services)

The config essentially acts as the "bridge" that tells cidaas how to communicate with your external authentication service, making the verification system extensible and customizable.

Required Scope: cidaas:verification_write

To configure a new verification type for the pluggable authentication mechanism:

curl -X POST 'https://cidaasdomain.com/verification-actions-srv/config' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'Cookie: cidaas_dr=28196fb4-895b-4f07-b415-bff77182eeb4' \
--data '{
    "verificationType": "YOUR_EXTERNAL_AUTHENTICATION_METHOD",
    "url": "https://example.com",
    "auth_type": "OAUTH2",
    "cidaasAuthDetails": {
        "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
}'
``
**Note**: The bearer token must include the `cidaas:verification_write` scope to access this configuration endpoint.