Guides
Start typing to search…

Microsoft Entra (Azure AD)

Previously known as Azure AD

This guide explains how to integrate Microsoft Entra ID (previously known as Azure Active Directory) as an OAuth login provider for your Facets Control Plane.

Note: Azure Active Directory was renamed to Microsoft Entra ID in 2023. All functionality remains the same, but the portal and service names have changed. This guide uses the current terminology.

Prerequisites

  • An Azure account with an active subscription
  • Admin access to your organization's Microsoft Entra ID tenant
  • Admin access to your Facets Control Plane

Step 1: Register an Application in Microsoft Entra ID

1.1 Access the Microsoft Entra Admin Center

  1. Sign in to the Microsoft Entra admin center or Azure Portal
  2. If you manage multiple tenants, use the Settings icon to select your target tenant

1.2 Navigate to App Registrations

There are several ways to access App registrations:

Option 1 - Search (Easiest):

  • Use the search bar at the top and type "App registrations"
  • Click on App registrations from the results

Option 2 - Menu Navigation:

  • In Microsoft Entra admin center: Go to Applications > App registrations
  • In Azure Portal: Click Microsoft Entra ID from sidebar, then App registrations under Manage

Option 3 - Direct URL:

  • Navigate directly to: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade

1.3 Create a New App Registration

  1. Click + New registration
  2. Configure your application:
    • Name: Enter a meaningful name (e.g., "Facets Control Plane Login" or "facetsdemo app")
    • Supported account types: Select "Accounts in this organizational directory only (Single tenant)" for enterprise use
    • Redirect URI: Leave blank for now (you'll add this in the next step)
  3. Click Register

1.4 Record Application Credentials

After registration, you'll be taken to the application's Overview page. Record these values:

  • Application (client) ID - You'll need this for Facets configuration
  • Directory (tenant) ID - Used to construct the Issuer URL

Step 2: Configure Redirect URI

  1. In your app registration, navigate to Manage > Authentication

  2. Check the Platform configurations section:

    • If you already have redirect URIs configured: Skip to Step 3
    • If not: Click + Add a platform → Select Web

  3. Under Web > Redirect URIs, add or verify your redirect URI in this format: https://control-plane-url/login/oauth2/code/registration-ID

  4. Click Save or Configure

Note: Replace control-plane-url with your organization's Control Plane URL, registration-ID with a unique identifier (use lowercase, no spaces or special characters), which exactly matches the one you will use as the "Registration ID" in Facets. You can have multiple redirect URIs for different environments (production, staging, local development)

Step 3: Create Client Secret

  1. Navigate to Manage > Certificates & secrets. Select Client secrets tab
  2. Click + New client secret, add a description (e.g., "Facets OAuth Integration")
  3. Select an expiration period: Recommended: 6 months or 12 months, Maximum: 24 months
  4. Click Add

⚠️ CRITICAL: Copy the Value field immediately and store it securely. This secret value is never displayed again after you navigate away from this page. If you lose it, you'll need to create a new secret.

Security Best Practice: For production environments, Microsoft recommends using certificates instead of client secrets. Certificates can be configured in the same Certificates & secrets section.

Step 4: Configure OAuth Integration in Facets

4.1 Access OAuth Settings

  1. Log in to your Facets Control Plane. Navigate to Settings > OAuth Integrations. Click Add Integrations
  2. Select Azure AD (or Microsoft Entra ID) from the provider list.
  3. Enter Configuration details.
    1. Registration ID: Unique identifier (must match the one in your Redirect URI) (Ex.microsoft-entra)
    2. Client ID: Application (client) ID from Azure. (Ex. a1b2c3d4-e5f6-7890-abcd-ef1234567890)
    3. Client Secret: Secret value copied earlier. (Ex. abc123...)
    4. Issuer URL : Format: https://login.microsoftonline.com/``tenant-id
    5. Login Button Text: Custom text for login button, (Ex. Login with Microsoft)

Where to find these values:

Client ID & Tenant ID: Microsoft Entra admin center > Your app registration > Overview

Client Secret: The value you copied in Step 3

Issuer URL: Use the format https://login.microsoftonline.com/<tenant-id>, replacing <tenant-id> with your Directory (tenant) ID from the Overview page

4.3 Save and Test

  1. Click Save or Add Integration
  2. Log out of Facets Control Plane
  3. On the login page, you should see your configured login button
  4. Test the OAuth flow by clicking the button and authenticating with your Microsoft credentials

Troubleshooting

Redirect URI Mismatch Error

  • Verify the redirect URI in Azure exactly matches the format: https://<your-cp-url>/login/oauth2/code/<your-registration-id>
  • Ensure the registration ID has no spaces or special characters

Invalid Client Secret

  • Client secrets expire based on the lifetime you selected
  • If expired, create a new client secret and update the value in Facets

Users Cannot Sign In

  • Verify "Supported account types" is set correctly (Single tenant for organization-only access)
  • Check that users exist in your Microsoft Entra ID tenant

Security Recommendations

  1. Rotate Secrets Regularly: Set client secret expiration to 12 months or less and rotate before expiry
  2. Use Certificates (Production): For production deployments, consider using certificate-based authentication instead of client secrets
  3. Restrict Account Types: Use "Single tenant" unless you specifically need multi-tenant support
  4. Monitor Access: Regularly review sign-in logs in Microsoft Entra ID

Additional Resources


Updated 8 days ago