Copy page

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 Dev Portal 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

1. 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., "Dev Portal 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

2. 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 — Dev Portal uses the more secure Authorization Code flow with PKCE
   • Configure Supported account types if needed
   • Save your changes

3. 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

4. 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 Dev Portal configuration file:

   Code
   // zudoku.config.ts
   export default {
     // ... other configuration
     authentication: {
       type: "openid",
       clientId: "<your-application-client-id>",
       issuer: "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
       scopes: ["openid", "profile", "email"], // Optional: customize scopes
     },
     // ... other configuration
   };

Configuration Options

Single Tenant vs Multitenant

For single tenant (organization-only access):

Code
authentication: {
  type: "openid",
  clientId: "<your-application-client-id>",
  issuer: "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
  scopes: ["openid", "profile", "email"],
}

For multitenant (any Azure AD organization):

Code
authentication: {
  type: "openid",
  clientId: "<your-application-client-id>",
  issuer: "https://login.microsoftonline.com/common/v2.0",
  scopes: ["openid", "profile", "email"],
}

Custom Scopes and Permissions

Request additional Microsoft Graph API scopes:

Code
authentication: {
  type: "openid",
  clientId: "<your-application-client-id>",
  issuer: "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
  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: "openid",
    // ... 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:

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

B2B Guest Access

To allow external partners access:

1. Enable B2B collaboration in Azure AD
2. Configure external collaboration settings
3. Invite guest users to your directory
4. Grant appropriate permissions to your application

Customizing Sign-up

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

1. Invalid Client Error: Ensure the client ID is correct and the application is properly registered.

2. Redirect URI Mismatch: The redirect URI must exactly match one configured in Azure AD, including protocol and path.

3. Tenant Access Issues: For single-tenant apps, ensure users are from the correct tenant. For multi-tenant, verify the issuer URL uses "common" or "organizations".

4. Missing User Information: Check that required API permissions are granted and admin consent is provided if needed.

5. Token Validation Errors: Ensure your issuer URL is correct and includes the /v2.0 endpoint for the Microsoft identity platform.

6. Authentication Not Working: Verify your issuer URL 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