Skip to main content

Azure Token Authentication for EmpowerID APIs

EmpowerID integrates Azure Token Authentication to provide secure access to its APIs. This process includes initial authentication using Azure tokens, an internal token exchange mechanism, and identity verification and access management. The Azure token is validated and exchanged for an EmpowerID-specific access token that enforces API access control based on the configured OAuth application permissions.

Authentication Flow​

  1. Receive Azure Token - Client sends request with Azure access token, scope, and EmpowerID OAuth application client ID
  2. Validate and Exchange - EmpowerID validates Azure token and exchanges it for an EmpowerID access token using the specified OAuth application
  3. API Access - EmpowerID access token is used for API calls with appropriate permissions
  4. Identity Verification - User identity is verified or created based on Azure token claims
  5. RBAC Enforcement - Role-Based Access Control checks are performed at API endpoints

Implementation​

Request Format​

Send API request with Azure access token and required headers:

POST /api/services/v1/testapi HTTP/1.1
Host: <EID Server>
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
Authorization: Bearer <Azure Access Token>
scope: <Scope for the API endpoint>
client_id: <ClientID of the EmpowerID OAuth application>
Header ParameterRequired/OptionalDescription
AuthorizationrequiredAzure access token (Bearer format)
scoperequiredScope associated with the API endpoint
client_idrequiredEmpowerID OAuth application client ID for token exchange

Token Exchange Process​

EmpowerID performs the following steps upon receiving the request:

  1. Azure Token Validation - Validates the Azure access token signature and expiration
  2. OAuth Application Lookup - Identifies the EmpowerID OAuth application using the provided client_id
  3. Token Exchange - Exchanges Azure token for EmpowerID access token with appropriate context and permissions
  4. Identity Mapping - Extracts oid (Object ID) from Azure token to identify or create user identity in EmpowerID

Access Control​

After token exchange, EmpowerID enforces access control through:

Token-Based Authorization

  • EmpowerID access token contains permissions defined by the OAuth application
  • API calls use this token for all subsequent requests
  • Token permissions align with EmpowerID's access control policies

Role-Based Access Control (RBAC)

  • Individual API endpoints perform independent RBAC checks
  • Endpoints verify user roles and permissions before processing requests
  • Provides granular access control at the endpoint level

Configuring API Scopes​

Configure OAuth scopes and RBAC checks for your EmpowerID APIs. Refer to the EmpowerID documentation for detailed instructions on adding OAuth scopes to REST API endpoints.