Skip to content

Azure Entra ID App Registration for DepthFusion

This runbook guides you through setting up DepthFusion as a registered application in Azure Entra ID (formerly Azure AD), configuring OIDC authentication, and preparing your test tenant.

Prerequisites

  • Access to an Azure subscription with permissions to register applications (Application Developer role minimum)
  • Azure CLI installed and authenticated (az login)
  • DepthFusion repository cloned locally
  • Test tenant or ability to create one

Register the Application

  1. Navigate to Azure Portal
  2. Go to https://portal.azure.com

  3. Select Azure Active Directory (or search for it)

  4. Create a New App Registration

  5. Click App registrations in the left sidebar
  6. Click + New registration
  7. Fill in the registration details:
    • Name: DepthFusion
    • Supported account types: Accounts in this organizational directory only (Single tenant)
    • Redirect URI: Platform: Mobile and desktop applications
    • Add two URIs:
      1. http://localhost:8080/callback (for local development)
      2. depthfusion://auth/callback (for deep linking / native apps)

  8. Click Register

  9. Note the IDs

  10. Copy the Application (client) ID — this is your DEPTHFUSION_ENTRA_CLIENT_ID
  11. Copy the Directory (tenant) ID — this is your DEPTHFUSION_ENTRA_TENANT_ID

Configure PKCE

  1. Enable Public Client Flow
  2. In your app registration, go to Authentication in the left sidebar
  3. Under Advanced settings, toggle Allow public client flows to Yes

  4. Click Save

  5. Verify Redirect URIs

  6. Confirm both redirect URIs are listed under Redirect URIs
  7. For mobile/desktop app types, PKCE is automatically enforced

Group Claims

  1. Add Groups Claim to Tokens
  2. Go to Token configuration in the left sidebar
  3. Click + Add groups claim
  4. Select Security groups (for testing with security groups)
  5. Under ID and Access tokens, select which claims should include groups

  6. Click Add

  7. Verify Configuration

  8. The token will now include a groups claim with object IDs of the user's group memberships

Required API Permissions

  1. Add Microsoft Graph Permissions
  2. Go to API permissions in the left sidebar
  3. Click + Add a permission
  4. Select Microsoft Graph
  5. Choose Delegated permissions
  6. Search for and add the following:
    • openid (already implicit)
    • profile (UserRead.All or profile scope)
    • email (already implicit)
    • offline_access (for refresh tokens)
    • User.Read (for user profile info)

  7. Click Add permissions

  8. Grant Admin Consent (if required)

  9. Click Grant admin consent for [Tenant]
  10. Confirm the action

Test Tenant Setup

Create a Test User

  1. Navigate to Users
  2. Go to Azure Active Directory > Users > New user
  3. Fill in:
    • User principal name: testuser@yourtenant.onmicrosoft.com
    • Display name: Test User
    • Password: Auto-generate or set your own (note: you must change on first login if auto-generated)

  4. Click Create

  5. Set a Permanent Password (optional, for automation)

  6. Go to the user's profile
  7. Click Reset password
  8. Un-check Reset password on next sign-in if you want a permanent test password
  9. Copy the temporary password and save it

Create a Test Group and Add User

  1. Create Security Group
  2. Go to Azure Active Directory > Groups > New group
  3. Fill in:
    • Group type: Security
    • Group name: depthfusion-users
    • Group description: Test group for DepthFusion OIDC testing

  4. Click Create

  5. Add Test User to Group

  6. Open the newly created group
  7. Click Members > + Add members
  8. Search for and select testuser@yourtenant.onmicrosoft.com

  9. Click Select

  10. Note the Group Object ID

  11. From the group's overview page, copy the Object ID
  12. This is useful for testing group claims in tokens

Environment Variables

Create a file at tests/fixtures/entra/test-tenant.env with the following variables (copy from test-tenant.env.example and fill in your values):

# Your Azure Entra Tenant ID
DEPTHFUSION_ENTRA_TENANT_ID=your-tenant-id-here

# Your registered application's client ID
DEPTHFUSION_ENTRA_CLIENT_ID=your-client-id-here

# Microsoft Entra ID authority endpoint
DEPTHFUSION_ENTRA_AUTHORITY=https://login.microsoftonline.com/your-tenant-id-here

# JWKS (JSON Web Key Set) endpoint for token validation
DEPTHFUSION_JWKS_URI=https://login.microsoftonline.com/your-tenant-id-here/discovery/v2.0/keys

# Token audience (typically the client ID)
DEPTHFUSION_ENTRA_AUDIENCE=api://your-client-id-here

# Token issuer URL (for JWT validation)
DEPTHFUSION_TOKEN_ISSUER=https://sts.windows.net/your-tenant-id-here/

# Test user UPN
DEPTHFUSION_TEST_USER_UPN=testuser@yourtenant.onmicrosoft.com

# Test group name or object ID
DEPTHFUSION_TEST_USER_GROUP=depthfusion-users

Do not commit this file to git. It contains tenant-specific secrets. Add it to .gitignore.

Troubleshooting

Token Validation Fails

  • Problem: JWT signature validation fails
  • Solution: Ensure DEPTHFUSION_JWKS_URI is correct and publicly accessible. Verify the JWKS contains the key referenced in the token's kid header.

Redirect URI Not Recognized

  • Problem: Authorization flow redirects to an error page
  • Solution: Double-check the exact redirect URIs in the app registration match what your client is sending (case-sensitive, including trailing slashes).

Groups Claim Not in Token

  • Problem: User is in a group but the groups claim is missing from the token
  • Solution:
  • Verify the group claim is configured in Token configuration
  • Ensure the user is actually a member of the group (check in Members tab)
  • For large numbers of groups, groups claims may need group assignment or filtering

PKCE Validation Error

  • Problem: Authorization server rejects code_challenge parameter
  • Solution: Ensure you've enabled Allow public client flows in the app's Authentication settings.

Scope Not Granted

  • Problem: Authorization fails with "Requested scopes exceed granted consent"
  • Solution: Grant admin consent in API permissions or have the test user consent manually during the first auth flow.

Next Steps

  • Implement OIDC client code to exchange authorization codes for tokens
  • Store tokens securely (avoid localStorage in web apps; use HTTP-only cookies)
  • Validate JWTs using the JWKS endpoint
  • Implement token refresh using offline_access scope if long-lived sessions are needed