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-or-common

Optional Configuration Variables

# Token Configuration
# Determines which token to use for extracting user information
# - 'id': Extract user info from ID token (default, recommended)
# - 'access': Extract user info from access token
# If token extraction fails, the system will automatically fallback to Graph API
ENTRA_TOKEN_KIND=id

ENTRA_GRAPH_URL=https://graph.microsoft.com

# Custom Claim Mappings (defaults are shown)
ENTRA_USERNAME_CLAIM=preferred_username
ENTRA_GROUPS_CLAIM=groups
ENTRA_EMAIL_CLAIM=upn
ENTRA_NAME_CLAIM=name

Token Kind Configuration

The ENTRA_TOKEN_KIND variable determines how user information is extracted:

Screenshot: Azure Token Kind

  • id (default, recommended): Extracts user info from ID token
  • Fast: Local JWT decoding, no network calls
  • Standard: OpenID Connect standard approach

  • Contains standard user claims: username, email, name, groups

  • access: Extracts user info from access token

  • Used when ID token is not available

  • May not contain all user claims

  • Automatic fallback: If token extraction fails, the system automatically falls back to Microsoft Graph API

Example Configuration: 

# Use ID token for user info (recommended - fast, standard OIDC)
ENTRA_TOKEN_KIND=id

# Use access token for user info (alternative)
ENTRA_TOKEN_KIND=access

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: Without these permissions, the groups field in user info will be empty, but authentication will still work.

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. Token Kind Configuration

  15. If using ENTRA_TOKEN_KIND=id but ID token is not available, system will fallback to access token
  16. If using ENTRA_TOKEN_KIND=access, ensure access token contains user claims
  17. Check logs to see which token extraction method was used

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