Skip to content

Device Identity Server

A hierarchical multi-organizational OAuth2 server for device identity management and authentication with JWT token issuance.

Overview

The Device Identity Server is a Spring Boot application that provides a comprehensive solution for managing device identities in a hierarchical multi-organizational environment. It enables secure device registration, authentication, and authorization through OAuth2 workflows specifically designed for IoT devices, with complete isolation at organization and environment levels.

Key Features

  • Hierarchical Multi-Organization Architecture: Complete isolation by Organization → Environment → Client Pool → Devices
  • Client Pool-Based OAuth2: Dedicated OAuth2 infrastructure per environment with unique signing keys
  • JWT Token Issuance: Issue and validate signed JWT tokens with comprehensive organizational and device context
  • Device Lifecycle Management: Complete device registration, activation, and management with rich metadata and tags
  • OTP-Based Secure Activation: One-time password flows for secure device credential provisioning
  • Flexible Key Management: Support for both self-signed keys and AWS KMS integration
  • Token Revocation: Built-in mechanism for revoking tokens with centralized tracking
  • Enterprise Integration: Built with JumpMind POS framework for microservice capabilities

System Architecture

graph TD
    A[Device] -->|1- OTP Activation | B[OTP Flow Controller]
    B -->|2- Provision Credentials| C[Client Pool OAuth2]
    A -->|3- Token Request| D["Token Endpoint
{clientPoolId}/oauth2/token"]
    D -->|4- Validate Device| E[(Device Repository)]
    D -->|5- Generate JWT| F[Client Pool Key Manager]
    F -->|5a- Self-Signed| G[(Local Keys)]
    F -->|5b- AWS KMS| H[🔐 AWS KMS]
    D -->|6- Return JWT| A
    A -->|7- API Request with JWT| I[Resource Server]
    I -->|8- Validate JWT| J["JWKS Endpoint
{clientPoolId}/.well-known/jwks.json"]
    I -->|9- Process Request| K[(Protected Resources)]

Hierarchical Structure

graph TD
    A[Organization
retail-corp] --> B[Environment
production]
    A --> C[Environment
staging]
    A --> D[Environment
development]

    B --> E[Client Pool
pool-prod-east]
    C --> F[Client Pool
pool-stage-east]
    D --> G[Client Pool
pool-dev-east]

    E --> H[Device
pos-terminal-001]
    E --> I[Device
kiosk-checkout-003]
    F --> J[Device
test-device-001]

    H --> K[OAuth2 Client
client_abc123]
    I --> L[OAuth2 Client
client_def456]
    J --> M[OAuth2 Client
client_test789]

API Structure

Internal Management APIs

/api/internal/org                                                        # Organization management
/api/internal/org/{orgId}/env                                            # Environment management
/api/internal/org/{orgId}/env/{envId}/device                             # Device management
/api/internal/org/{orgId}/env/{envId}/device/{deviceId}/app              # Application binding
/api/internal/org/{orgId}/env/{envId}/device/{deviceId}/app/{appId}/otp  # OTP generation

OAuth2 APIs (per client pool)

/{clientPoolId}/oauth2/token           # Token endpoint
/{clientPoolId}/oauth2/revoke          # Token revocation
/{clientPoolId}/.well-known/jwks.json  # JWKS endpoint

Authentication Flow APIs

/api/otp/activate                      # OTP-based device activation

Core Components

Models

  • OrganizationModel: Root organizational entity with unique identifiers
  • OrganizationEnvironmentModel: Environment within an organization (dev, staging, prod)
  • ClientPoolModel: OAuth2 client pool configuration per environment
  • OrganizationBusinessUnitDeviceModel: Device entity with organizational context
  • ClientModel: Individual OAuth2 client credentials and configuration
  • OrganizationBusinessUnitDeviceMetadata: Key-value metadata storage for devices
  • RevokedTokenInfo: Token revocation tracking and management

Controllers

Internal Management APIs

  • ApiKeyManagementController: API key generation and management for internal use
  • OrganizationController: Organization lifecycle management
  • OrganizationEnvironmentController: Environment creation and management
  • OrganizationEnvironmentClientController: OAuth2 client management within environments (but not assciated with devices)
  • OrganizationEnvironmentDevicesController: Device registration and lifecycle management

OAuth2 APIs

  • ClientPoolOAuth2Controller: OAuth2 token endpoint implementation
  • ClientPoolOAuth2WellKnownController: OAuth2 discovery and JWKS endpoints

Authentication Flow

  • OtpFlowController: One-time password device activation flow

Security Components

  • KeyManager: Cryptographic key management for client pools
  • SigningKey: JWT signing key abstraction and operations
  • AuthTokenRevocationStore: Token revocation tracking and validation

Technology Stack

  • Spring Boot: Application framework with JumpMind POS integration
  • Spring Security OAuth2: Standards-compliant OAuth2 implementation
  • Spring Data JPA: Data access layer with repository pattern
  • H2/PostgreSQL: Configurable database backends
  • AWS SDK: Integration with AWS KMS for production key management
  • Nimbus JOSE+JWT: JWT and JWK operations

Component Architecture

Controller Layer

  • OrganizationController → manages organizations
  • OrganizationEnvironmentController → manages environments within organizations
  • OrganizationEnvironmentDevicesController → handles device registration and management
  • ClientPoolOAuth2Controller → processes OAuth2 token requests and operations
  • OtpFlowController → handles one-time password device activation

Data Model Hierarchy

Organization (retail-corp)
└── Environment (production, staging, dev)
    └── Client Pool (pool-prod-east)
        └── Device (pos-terminal-001)
            └── OAuth2 Client (client_abc123)

Device Lifecycle Flow

sequenceDiagram
    participant Admin as Admin
    participant Internal as Internal API
    participant Device as Device
    participant OTP as OTP Flow
    participant OAuth as OAuth2 API

    Admin->>Internal: 1. Create Organization
    Admin->>Internal: 2. Create Environment (auto-generates client pool)
    Admin->>Internal: 3. Register Device
    Admin->>Internal: 4. Create Device Application
    Admin->>Internal: 5. Generate OTP

    Device->>OTP: 6. Activate with OTP
    OTP->>Device: 7. Return client credentials + token endpoint

    Device->>OAuth: 8. Request token (client credentials flow)
    OAuth->>Device: 9. Return JWT access token

    Device->>External: 10. Use token for API calls

JWT Token Claims

Tokens contain comprehensive organizational and device context:

{
   "sub": "05243-001",
   "iss": "https://idp.dev.jmeng-nonprod.jumpmind.cloud/client-pool-id",
   "exp": 1692892800,
   "iat": 1692889200,
   "scope": ["device"],
   "client_app_id": "client", // Client application identifier (client, server) 
   "client_id": "d1505d57-05dc-4271-a807-d5ecfd7434c8",
   "metadata": {
      "terminal_type": "kiosk",
      "location": "checkout-3"
   },
   "tags": {
      "country": "US",
      "business_unit_id": "05243",
      "device_id": "*",
      "device_type": "*",
      "state": "NY",
      "store_type": "*",
      "brand": "*",
      "app_id": "pos"
   },
   "primary_server_url": "http://localhost:6140",
   "server_urls": [
      "http://localhost:6140",
      "http://localhost:6141"
   ]
}