AuthExchange

Publisher Platform Authentication & Authorization Microservice

Service Type: Kubernetes Microservice
Technology: Node.js (JavaScript) with Express.js
Runtime: Node.js Container
Last Updated: 2025-07-01

📋 Overview

The AuthExchange microservice is the central authentication and authorization hub for the Publisher platform. It integrates with Microsoft Azure B2C for user authentication and Microsoft Graph API for user management. The service handles token exchange, user role management, group membership, and provides secure access control for all platform services.

Key Features

Azure B2C Integration: Seamless integration with Microsoft Azure B2C for authentication
Microsoft Graph API: User and group management through Microsoft Graph
JWT Token Management: Custom JWT token generation and verification
Role-Based Access Control: Comprehensive role and permission management
Multi-Tenant Support: Organization-based user isolation and management
Internal User Privileges: Automatic admin privileges for internal users
External Application Support: Special handling for external application authentication

🛠 Technology Stack

Component	Technology
Language	JavaScript (Node.js)
Runtime	Node.js Container
Framework	Express.js
Authentication	Azure B2C, JWT
User Management	Microsoft Graph API
Authorization	Custom RBAC
Build Tool	Webpack
Container	Docker
Orchestration	Kubernetes

🏗 Architecture

Service Architecture

Deployment Pattern: Kubernetes Deployment with HTTP Service
Port: 8081 (configurable)
Authentication Flow: Azure B2C → Token Exchange → Custom JWT
User Management: Microsoft Graph API integration
Configuration: ConfigMap and environment variables
Monitoring: Application logging and error tracking

System Flow

graph TD
    A[Client Application] --> B[Azure B2C Authentication]
    B --> C[AuthExchange Microservice]
    C --> D[Token Verification]
    D --> E[Microsoft Graph API]
    E --> F[User Groups & Roles]
    F --> G[Custom JWT Generation]
    G --> H[Signed Token Response]
    H --> A

    C --> I[User Management APIs]
    I --> E
    E --> J[User CRUD Operations]

🔄 Authentication Flow

Token Exchange Process

sequenceDiagram
    participant Client
    participant B2C as Azure B2C
    participant Auth as AuthExchange
    participant Graph as Microsoft Graph
    participant App as Application

    Client->>B2C: Login Request
    B2C-->>Client: B2C Token
    Client->>Auth: Token Exchange Request
    Auth->>Auth: Verify B2C Token
    Auth->>Graph: Get User Groups
    Graph-->>Auth: Group Memberships
    Auth->>Auth: Generate Custom JWT
    Auth-->>Client: Custom JWT Token
    Client->>App: API Request with JWT

Authorization Middleware Flow

graph LR
    A[HTTP Request] --> B[Extract Token]
    B --> C[Verify Token]
    C --> D{Token Valid?}
    D -->|No| E[401 Unauthorized]
    D -->|Yes| F[Extract Claims]
    F --> G[Check Roles/Permissions]
    G --> H[Allow Request]

📡 API Specification

Authentication Endpoints

Token Exchange

Endpoint: POST /ms/token
Authentication: Azure B2C Bearer Token
Description: Exchange B2C token for custom JWT with roles

{
  "headers": {
    "Authorization": "Bearer <b2c-token>"
  }
}

Response:

{
  "token_type": "Bearer",
  "access_token": "<custom-jwt-token>"
}

Inbound Admin Token

Endpoint: GET /ms/inboundAdmin-token
Authentication: Azure B2C Bearer Token
Description: Get access token for inbound admin operations

User Management Endpoints

Get All Users

Endpoint: GET /users
Authentication: Custom JWT Token
Description: Retrieve all users in the system

Search Users

Endpoint: GET /users/search/:name
Authentication: Custom JWT Token
Description: Search users by name

Delete User

Endpoint: DELETE /users/:userId
Authentication: Custom JWT Token
Description: Delete a user from the system

Update User Status

Endpoint: PUT /users/:userId/accountEnabled/:enabledStatus
Authentication: Custom JWT Token
Description: Enable/disable user account

Organization Management Endpoints

Organization Users

Endpoint: GET /organizations/:orgId/users
Authentication: Custom JWT Token
Description: Get users for specific organization

Group Management Endpoints

Group Operations

Endpoint: /groups/*
Authentication: Custom JWT Token
Description: Various group management operations

🔧 Business Logic

User Authentication Types

Internal Users

Identification: tfp claim = B2C_1_SIGNUPSIGNIN with wildcard organization/scope
Privileges: Automatically added to admin group
Account Status: Automatically enabled
Access Level: Full platform access

External Users

Identification: Standard B2C authentication
Privileges: Based on assigned groups and roles
Organization Scope: Limited to specific organization
Access Level: Organization-specific access

External Applications

Identification: isExternalApplication claim
Authentication: Special application-level authentication
Privileges: API-level access without user context

Role and Permission System

Required Claims Validation

// For non-external applications
extension_PublisherOrganization: "organization-id"
extension_PublisherScope: "scope-definition"

Group Mapping

Groups are mapped from Microsoft Graph to internal role names
Dynamic group membership resolution
Role-based access control enforcement

Token Management

Custom JWT Structure

{
  "oid": "user-object-id",
  "name": "user-display-name",
  "extension_PublisherOrganization": "org-id",
  "extension_PublisherScope": "scope",
  "extension_PublisherRoles": ["role1", "role2"],
  "exp": "expiration-timestamp"
}

⚙️ Configuration

Environment Variables

B2C Configuration: Tenant name, client secrets, JWT secrets
Microsoft Graph: API credentials and endpoints
Application Settings: Port, CORS settings, logging levels

Key Configuration Files

config/config.js: Main configuration
config/config.int.js: Integration environment
config/config.prod.js: Production environment

B2C Configuration Structure

{
  "B2C": {
    "tenantName": "tenant-name",
    "jwtSecret": "jwt-signing-secret",
    "groups": {
      "admin": "admin-group-id",
      "user": "user-group-id"
    }
  }
}

🚀 Deployment

Kubernetes Deployment

# Apply Kubernetes manifests
kubectl apply -f k8s/

# Check deployment status
kubectl get pods -l app=authexchange

# View logs
kubectl logs -l app=authexchange -f

Local Development

# Install dependencies
npm install

# Run locally (port 8081)
npm start

# Run with local wrapper
./run-local.sh

# Run without wrapper
./run-local-no-wrapper.sh

📊 Monitoring & Health Checks

Health Endpoints

Liveness: /live - Basic health check
Readiness: /ready - Service readiness check
Version: /version - Service version information

Key Metrics to Monitor

Authentication success/failure rates
Token exchange performance
Microsoft Graph API response times
User management operation success rates
Group membership resolution performance

Security Monitoring

Failed authentication attempts
Invalid token usage
Unauthorized access attempts
Privilege escalation attempts

🔧 Troubleshooting

Common Issues

Authentication Failures

B2C Token Invalid: Check B2C configuration and token format
Required Claims Missing: Verify user has proper organization/scope claims
Group Resolution Fails: Check Microsoft Graph API connectivity

User Management Issues

Graph API Errors: Verify Microsoft Graph permissions and credentials
User Not Found: Check user exists in Azure B2C directory
Group Assignment Fails: Verify group IDs and permissions

Token Exchange Problems

# Check JWT secret configuration
# Verify B2C tenant settings
# Validate group mappings

🧪 Testing

Unit Tests

npm test

Manual Testing

Authentication Flow: Test B2C login → token exchange
User Management: Test CRUD operations
Role Assignment: Verify group membership and role mapping
Authorization: Test access control enforcement

🤝 Dependencies

External Dependencies

Azure B2C: User authentication and directory
Microsoft Graph API: User and group management
JWT Libraries: Token generation and verification

Internal Dependencies

Configuration Service: For B2C and Graph settings
Logging Service: For audit trails and monitoring

NPM Dependencies

express: Web framework
jsonwebtoken: JWT handling
@microsoft/microsoft-graph-client: Graph API client
jwks-rsa: JWT key verification
axios: HTTP client

This documentation was created through manual code analysis of the AuthExchange microservice codebase.