Skip to content

Microsoft Entra ID (Azure AD) Setup Guide

This guide provides step-by-step instructions for setting up Microsoft Entra ID (formerly Azure AD) as an authentication provider in Jarvis Registry.

Prerequisites

  • An Azure subscription with Entra ID (Azure AD) tenant
  • Access to the Azure Portal with administrative privileges
  • Jarvis Registry deployed and accessible

Step 1: Create App Registration in Azure Portal

  1. Navigate to Azure Portal
  2. Go to Azure Portal
  3. In the search box, type “Azure Entra” and click on it.

  4. On the left menu, click on App registrations and then on New registration.

  5. Create New Registration

  6. Click New registration
  7. Name: Jarvis Registry (or your preferred name)
  8. Supported account types:
    • For single tenant: Accounts in this organizational directory only
  9. Redirect URI:
    • Type: Web
    • URI: https://your-registry-domain/auth/oauth2/callback/entra
    • Replace your-registry-domain with your actual registry URL, use http://localhost:8888/auth/oauth2/callback/entra for local deployment

Azure app register

  1. Register the Application
  2. Click Register
  3. Note down the Application (client) ID and Directory (tenant) ID

Step 2: Configure Authentication

  1. Configure Platform Settings
  2. In your app registration, go to Authentication
  3. Under Platform configurations, ensure your redirect URI is listed
  4. Implicit grant: Enable ID tokens and Access tokens

entra-id-grant

Step 3: Create Client Secret

  1. Generate New Secret
  2. In your app registration, go to Certificates & secrets
  3. Click New client secret
  4. Description: Jarvis Registry Secret
  5. Expires: Choose appropriate expiration (recommended: 12-24 months)

  6. Click Add

  7. Copy the Secret Value

  8. Important: Copy the secret value immediately - it won't be shown again
  9. Store this securely

Step 4: Environment Configuration

Add the following environment variables to your Jarvis Registry deployment:

Required Variables

# Microsoft Entra ID Configuration
ENTRA_CLIENT_ID=your-application-client-id
ENTRA_CLIENT_SECRET=your-client-secret-value
ENTRA_TENANT_ID=your-tenant-id

Required identity claims and shared application

Chat and Registry must use the same Entra app registration (client_id) within each environment. Entra's sub is pairwise per application. Both products store it in users.openidId, so different client IDs would produce different subjects for the same person. Register both applications' callback URLs on that app registration.

Before deployment, configure Token configuration → Add optional claim → ID → xms_edov on the shared app registration. Ensure the ID token also contains the email claim (request the email scope and configure the optional email claim as needed). Inspect claims locally without pasting or logging the token. xms_edov must be the boolean true, not a string.

The auth server always verifies the ID token and requires iss, sub and oid. It reads the standard email claim, never substitutes a UPN, and trusts that email for linking or provisioning only when xms_edov is true. Without a trusted email, an existing stable-identity match can still sign in; a first-time user without such a match is refused. Group membership must also grant a nonempty scope before any user record is created.

Access tokens are used for Microsoft Graph group membership checks, not as identity tokens. A missing or invalid ID token fails login; there is no Graph identity fallback.

See Microsoft's optional claims reference and identity conflict resolution.

Optional display configuration

ENTRA_GRAPH_URL=https://graph.microsoft.com
ENTRA_USERNAME_CLAIM=preferred_username
ENTRA_NAME_CLAIM=name

The username is display information and is never used to match database users. Configure the four scope-group Object IDs described in the scope-group runbook; changing display claim mappings does not change authorization group bindings.

Deployment order

Configure the required optional claims and verify the shared client ID before deployment. Deploy the auth-server and Registry changes together. Remove the legacy email-source and token-selection settings from environment configuration at deployment time, not while the old code is still serving logins. Redis login or refresh records without user_id are rejected with invalid_grant and require a fresh login; do not clear all Redis state.

Existing OpenID users without an issuer are matched and repaired during login. The manual DEMO/PROD cleanup scripts are not a prerequisite for customer deployments. Shared user indexes are unchanged.

Step 5: Test the Setup

  1. Restart Services

  2. Restart the authentication server and registry services

  3. Test Authentication Flow

  4. Navigate to your registry login page
  5. Select "Microsoft Entra ID" as the authentication method
  6. Complete the Microsoft login process
  7. Verify successful authentication and user information retrieval

Step 6: Optional Configurations

Group Membership Access

To retrieve user group memberships from Azure AD, ensure the following permissions are granted:

  1. In Azure Portal → Your app registration → API permissions
  2. Add Microsoft Graph → Delegated permissions:
  3. Group.Read.All - Read all groups
  4. Or Directory.Read.All - Read directory data (includes groups)
  5. Click Grant admin consent (requires admin privileges)

Note: A failed group lookup produces empty scope groups. Both browser and device logins are refused when no scopes resolve, and no user is provisioned.

Custom Scopes

Modify the scopes configuration in oauth2_providers.yml to include additional Microsoft Graph permissions as needed.

Troubleshooting

Common Issues

  1. Invalid Redirect URI
  2. Ensure the redirect URI in Azure matches exactly with your registry callback URL

  3. Check for trailing slashes and protocol (http vs https)

  4. Insufficient Permissions

  5. Verify all required API permissions are granted with admin consent

  6. Check that the user has appropriate permissions in Entra ID

  7. Token Validation Failures

  8. Verify client ID, tenant ID, and client secret are correct

  9. Check token audience and issuer configuration

  10. Sovereign Cloud Issues

  11. For Azure Government or China clouds, set the appropriate ENTRA_GRAPH_URL
  12. Ensure app registration is in the correct cloud environment

  13. Verify OAuth endpoints match your cloud environment

  14. Untrusted email or identity conflict

  15. Confirm the ID token contains email and boolean xms_edov: true for first-time sign-ins.
  16. Confirm Chat and Registry use the same Entra client ID.
  17. Use the identity conflict runbook to diagnose refusals.
  18. Do not replace stored subject or issuer fields to force an account match.

Logs and Debugging

Enable debug logging to troubleshoot authentication issues:

# Set log level to DEBUG in your environment
AUTH_LOG_LEVEL=DEBUG

Check authentication server logs for detailed error messages and token validation information.

Security Considerations

  • Client Secrets: Rotate client secrets regularly and store them securely
  • Token Validation: The implementation validates token signatures, expiration, and audience
  • JWKS Caching: JWKS are cached for 1 hour to reduce API calls while maintaining security