Supported Providers

Azure AD Setup

Azure Active Directory (now Microsoft Entra ID) provides enterprise-grade authentication and authorization for organizations using Microsoft's cloud identity platform. This guide shows you how to integrate Azure AD with your Zudoku documentation site.

Prerequisites

An Azure subscription with Azure Active Directory
Administrative access to register applications in Azure AD
Your Azure AD tenant ID

Setup Steps

Register an Application in Azure AD

In the Azure Portal:
- Navigate to Azure Active Directory → App registrations
- Click New registration
- Configure your application:
  - Name: Enter a descriptive name (e.g., "Zudoku Documentation")
  - Supported account types: Choose based on your needs:
    - Single tenant (your organization only)
    - Multitenant (any Azure AD directory)
    - Multitenant + personal Microsoft accounts
  - Redirect URI:
    - Platform: Single-page application (SPA)
    - URI: https://your-site.com/oauth/callback
- Click Register
Configure Authentication Settings

In your newly registered application:
- Go to Authentication in the left menu
- Under Single-page application, add redirect URIs:
  - Production: https://your-site.com/oauth/callback
  - Preview (wildcard): https://*.your-domain.com/oauth/callback
  - Local Development: http://localhost:3000/oauth/callback
- Implicit grant and hybrid flows should remain disabled — Zudoku uses the more secure Authorization Code flow with PKCE
- Configure Supported account types if needed
- Save your changes
Configure API Permissions (Optional)

If you need specific permissions:
- Go to API permissions
- Click Add a permission
- Select Microsoft Graph → Delegated permissions
- Add permissions like User.Read, email, profile, openid
- Grant admin consent if required by your organization

Configure Zudoku

Get your application details from the Azure Portal:

Go to Overview page of your app registration
Copy the Application (client) ID
Copy the Directory (tenant) ID

Add the configuration to your Zudoku configuration file:

Code
// zudoku.config.ts
export default {
  // ... other configuration
  authentication: {
    type: "entra",
    clientId: "<your-application-client-id>",
    tenantId: "<your-tenant-id>",
    scopes: ["openid", "profile", "email"], // Optional: customize scopes
  },
  // ... other configuration
};

Configuration Options

Single Tenant vs Multitenant

For single tenant (organization-only access):

Code
authentication: {
  type: "entra",
  clientId: "<your-application-client-id>",
  tenantId: "<your-tenant-id>",
  scopes: ["openid", "profile", "email"],
}

For multitenant (any Azure AD organization), use tenantId: "common" or "organizations" — this is also the default if tenantId is omitted:

Code
authentication: {
  type: "entra",
  clientId: "<your-application-client-id>",
  tenantId: "common",
  scopes: ["openid", "profile", "email"],
}

Custom Scopes and Permissions

Request additional Microsoft Graph API scopes:

Code
authentication: {
  type: "entra",
  clientId: "<your-application-client-id>",
  tenantId: "<your-tenant-id>",
  scopes: [
    "openid",
    "profile",
    "email",
    "User.Read",
    "GroupMember.Read.All" // For group-based access control
  ],
}

Protected Routes

Protect specific documentation routes using the protectedRoutes configuration:

Code
{
  // ... other configuration
  authentication: {
    type: "entra",
    // ... Azure AD config
  },
  protectedRoutes: [
    "/api/*",        // Protect all API documentation
    "/internal/*",   // Protect internal documentation
    "/admin/*"       // Protect admin sections
  ],
}

Advanced Configuration

Conditional Access Policies

Azure AD supports conditional access policies that can:

Require multi-factor authentication
Restrict access by location
Enforce device compliance
Control session lifetime

Configure these in Azure AD Portal under Security → Conditional Access.

App Roles and Groups

To implement role-based access control:

In your app registration, go to App roles
Create custom roles (e.g., "Documentation.Read", "Documentation.Admin")
Assign roles to users or groups in Enterprise applications
Access role claims in your application

B2B Guest Access

To allow external partners access:

Enable B2B collaboration in Azure AD
Configure external collaboration settings
Invite guest users to your directory
Grant appropriate permissions to your application

Azure AD B2C usually handles sign-up via a separate user flow. To send users there, point Register at the URL of that flow (or any other page):

Code
authentication: {
  type: "azureb2c",
  // ...

  // Absolute URL → external redirect, relative path → in-app navigate
  signUp: { url: "https://your-tenant.b2clogin.com/your-tenant.onmicrosoft.com/B2C_1_SignUp/oauth2/v2.0/authorize?..." },

  // Hide Register entirely. Visual only — sign-ups are still controlled by your B2C policy.
  disableSignUp: true,
}

User Data

Azure AD provides rich user profile data through OpenID Connect:

name - User's display name
email - User's email address
picture - Profile picture URL (when available)
email_verified - Email verification status
preferred_username - User's UPN (User Principal Name)
Additional claims based on your API permissions

Troubleshooting

Common Issues

Invalid Client Error: Ensure the client ID is correct and the application is properly registered.
Redirect URI Mismatch: The redirect URI must exactly match one configured in Azure AD, including protocol and path.
Tenant Access Issues: For single-tenant apps, ensure users are from the correct tenant and tenantId is set to that tenant's GUID. For multi-tenant, use tenantId: "common" or "organizations".
Missing User Information: Check that required API permissions are granted and admin consent is provided if needed.
Token Validation Errors: Ensure your tenantId is correct. If you use a CIAM tenant (*.ciamlogin.com), set the issuer option to override the default issuer instead.
Authentication Not Working: Verify your tenantId and client ID are correct, and that your app registration is configured as a Single-page application (SPA) with the correct redirect URIs.

Security Best Practices

Use single-tenant configuration unless multi-tenant is specifically required
Implement conditional access policies for sensitive documentation
Regularly review and audit app permissions
Monitor sign-in logs in Azure AD for suspicious activity
Use app roles for fine-grained access control

Next Steps

Explore Microsoft identity platform documentation
Learn about protecting routes in your documentation
Implement app roles for advanced authorization

Edit this page

Last modified on July 16, 2026

Clerk OpenID Connect