Enable Microsoft Entra ID SSO for OPAQUE¶

This guide walks you through integrating Microsoft Entra ID (formerly Azure Active Directory) with OPAQUE, which is backed by Auth0. This integration enables single sign-on (SSO), allowing users to access OPAQUE with their existing Entra credentials—eliminating the need for separate username and password management.

Before you begin¶

Before integrating Entra SSO with OPAQUE, ensure you have:

• Access to the Azure portal with permissions to create App registrations and manage enterprise applications.
• Access to the Entra application configuration and the ability to securely share application details with OPAQUE.
• A list of the users who should have admin roles in OPAQUE.

Integration overview¶

At a high level, you will:

1. Create and configure an Entra App registration for OPAQUE.
2. Collect the required Entra values (tenant domain/ID, client ID, client secret).
3. Provide those values to OPAQUE to complete the Entra SSO configuration.
4. Assign users in Entra and validate sign-in.
5. Confirm admin access in OPAQUE.

In this guide, you’ll register an application in Microsoft Entra ID, generate credentials, and provide a small set of values to OPAQUE so we can enable your Entra SSO connection. You’ll then assign users and validate sign-in.

Step 1. Create an app registration in Microsoft Entra ID¶

1. Sign in to the Azure portal.
2. Navigate to Microsoft Entra ID → App registrations.
3. Select New registration.
4. Configure the application:
   • Name: OPAQUE SSO (or your preferred name)
   • Supported account types: Accounts in this organizational directory only (Single tenant)
   • Redirect URL
     • Platform: Web
     • URL: https://opaque.us.auth0.com/login/callback
5. Click Register.

Record your Entra values¶

From the App registration Overview page, record:

• Application (client) ID (for example, b35d632b-e7f9-4ced-ae01-d359f9a14568)
• Directory (tenant) ID (for example, e4ab718c-3334-4f94-ba08-09c69c746e0a)
• Tenant domain (for example: yourtenant.onmicrosoft.com)

Step 2. Create a client secret¶

1. In your app registration, go to Certificates & secrets.
2. Under Client secrets, select New client secret.
3. Add a description (for example: Auth0 Integration) and choose an expiration period consistent with your security policy.
4. Click Add.
5. IMPORTANT: Copy the secret value immediately and store it securely—you won’t be able to view it again.

Step 3. Configure authentication, permissions, and token claims¶

Next you’ll ensure Entra sends the right tokens and claims for OPAQUE/Auth0 to identify users reliably (especially their email address).

Configure authentication settings¶

1. In the app registration, go to Authentication.
2. Confirm the redirect URI is present under Web.
3. Under Implicit grant and hybrid flows, enable ID tokens.
4. Click Save.

Configure API permissions¶

1. Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions.
2. Add:
   • openid
   • profile
   • email
3. Select Grant admin consent for your tenant.

Configure token claims¶

To ensure Auth0 receives a usable email value:

1. Go to Token configuration → Add optional claim.
2. Select token type: ID
3. Add:
   • email
   • upn (User Principal Name)
4. Accept any prompts related to required Graph permissions.

Step 4. Provide your Entra app details to OPAQUE¶

To complete the SSO setup, share the following Entra application details with your OPAQUE contact, using your company-approved secure sharing method. Do not send the client secret in plain text (for example, directly in an email). Use an encrypted or access-controlled sharing method appropriate for your organization.

• Tenant domain (for example: yourtenant.onmicrosoft.com)
• Directory (tenant) ID
• Application (client) ID
• Client secret value
• The email domain your users will sign in with (for example: @example.com)

Step 5. Assign users in Entra and validate first sign-in¶

Once the app is registered, assign users (or groups) and verify that a test user can sign in end-to-end.

Assign users to the application¶

If your tenant requires assignment, ensure users are assigned to the application:

1. Go to Enterprise applications → your app → Users and groups.
2. Confirm the user is assigned (or add the user/group).

Ensure users have an email value Entra can send¶

A common issue during initial testing is that Auth0 receives an empty email claim. To avoid this, make sure the user’s profile has an email populated:

• In Azure Portal, open the user → Properties → Contact information → set Email.

Test sign-in¶

1. Navigate to your OPAQUE application URL and select Log in.
2. Sign in with an Entra user.
3. If the user is not yet assigned to an OPAQUE organization, the login may fail with an “unassigned” message. In that case, continue to the next section and confirm the user is properly assigned in Entra and added to the correct OPAQUE organization.

Step 6. Confirm OPAQUE admin access¶

You’ll typically validate two users:

• One user who should be an OPAQUE org admin.
• One user who should be a standard OPAQUE user.

If your designated admin signs in successfully but does not yet have admin privileges, send your OPAQUE contact the admin’s name and email and confirm they signed in. OPAQUE can then assign the appropriate admin role.

Troubleshooting sign-in issues¶

Need help?¶

• For Entra-related questions:
  • Refer to the Microsoft Entra documentation.
• For OPAQUE-related questions:
  • Refer to the Opaque documentation.
  • Contact OPAQUE support: support@opaque.co.