Skip to main content

SSO with Microsoft Entra ID

This guide covers setting up Microsoft Entra ID (formerly Azure AD) sign-in for a DAGZ team deployment. After completing it, your team signs into the DAGZ console and the zb CLI with their Entra accounts.

Choose a setup path​

There are two ways to set up Entra SSO:

  • Your own app registration. You create the app registration in your own Entra tenant. This gives your IT/security team full control: governance, conditional access policies, redirect URI changes, lifecycle. Recommended for organizations with Entra admin access and any kind of app review process.
  • DAGZ-provided app registration. DAGZ creates the app registration and sends you a configuration file. You skip the Entra portal work and go straight to step 6. Choose this if your team doesn't have Entra admin access, or wants the fastest path to running. The app lives in DAGZ's tenant; your IT team won't see it under your own App registrations.

If you're going with the DAGZ-provided registration, complete the steps in DAGZ-provided path setup below, then skip to step 6.

The rest of this guide (after the next section) covers setting up your own app registration.

DAGZ-provided path setup​

Three steps: find your tenant ID, build the configuration file, and grant admin consent.

Find your tenant ID​

Open Tenant Overview in the Entra admin center and copy the Tenant ID value.

Build the configuration file​

Save the following as dagz-entra-oidc.json. Replace YOUR_TENANT_ID with the value from the previous step.

{
  "tenant_id": "YOUR_TENANT_ID",
  "client_id": "ba19eeca-d646-4682-95b5-a13a245eba27",
  "jwks_uri": "https://login.microsoftonline.com/YOUR_TENANT_ID/discovery/v2.0/keys"
}

The client_id above is DAGZ's public OIDC client identifier, shared across all customers using the DAGZ-provided path. This is by design: OIDC public clients (SPAs) have no client secret, and the client ID is the same value Microsoft embeds in the consent URL below.

The DAGZ-provided app registration is multi-tenant. Before any of your team can sign in, an admin in your tenant must consent to the app on behalf of your organization.

Open this URL:

https://login.microsoftonline.com/organizations/adminconsent?client_id=ba19eeca-d646-4682-95b5-a13a245eba27

Sign in as a Global Administrator, Application Administrator, Cloud Application Administrator, or Privileged Role Administrator in your tenant. Review the requested permissions (openid, profile, email, User.Read) and approve.

After consent, users in your tenant can sign in to DAGZ without further prompts. If you skip this step, the first user to sign in sees an "admin approval required" screen.

Prerequisites​

  • Admin access to the Entra portal for your tenant.
  • The DAGZ console URL. This guide uses https://dagz.example.com as a placeholder; substitute your own.
  • DAGZ deployed and reachable, with no auth provider configured yet.

1. Register the application​

Open the Microsoft Entra admin center and sign in. Go to App registrations in the left nav and click New registration. Fill in:

  • Name: DAGZ (or any internal label).
  • Supported account types: select Accounts in this organizational directory only (single tenant).

Leave Redirect URI empty for now. Click Register.

After registration, copy these values from the Overview page:

  • Application (client) ID, referred to below as client_id.
  • Directory (tenant) ID, referred to below as tenant_id.
Single-tenant only

Choose Accounts in this organizational directory only. A multi-tenant configuration lets accounts from other Entra tenants reach the sign-in endpoint, which broadens the set of accounts that can attempt to sign in to your DAGZ deployment.

2. Configure redirect URIs​

DAGZ uses two sign-in flows: the web console (PKCE authorization code) and the zb CLI (implicit ID token). Each requires its own platform configuration.

In your app registration, go to Authentication.

Web console​

  1. Click Add a platform > Single-page application.
  2. Enter the redirect URI: https://dagz.example.com. No trailing slash, no path.
  3. Click Configure.

CLI​

  1. Click Add a platform > Web.
  2. Enter the redirect URI: https://dagz.example.com/auth/cli/entra_callback.
  3. Under Implicit grant and hybrid flows, check ID tokens (used for implicit and hybrid flows).
  4. Click Configure.

The Authentication page now lists two platforms: one Single-page application and one Web.

3. Configure token claims​

DAGZ reads several optional claims from the ID token to populate user profiles.

  1. Go to Token configuration > Add optional claim.
  2. Select ID for the token type.
  3. Add: email, family_name, given_name, preferred_username, upn.
  4. Click Add. If prompted to enable Microsoft Graph permissions for these claims, accept.

4. Confirm API permissions​

Go to API permissions. The default User.Read (Microsoft Graph, delegated) is sufficient. If your tenant requires admin consent for delegated permissions, click Grant admin consent for {tenant}.

5. Build the configuration file​

Save the following as dagz-entra-oidc.json. Replace {tenant_id} and {client_id} with the values from step 1.

{
  "tenant_id": "{tenant_id}",
  "client_id": "{client_id}",
  "jwks_uri": "https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys"
}

The jwks_uri is your tenant's v2 OIDC signing key endpoint. Substitute the same tenant_id into the path.

6. Run setup in the DAGZ console​

  1. Open https://dagz.example.com in a browser.
  2. The first-time setup screen appears. Choose Microsoft Entra ID.
  3. Click Choose file and upload dagz-entra-oidc.json.
  4. Click Set Up. The page redirects to Microsoft to sign in.
  5. Sign in with the account that should be the first DAGZ admin.
  6. Microsoft redirects back to DAGZ. You are now signed in as Admin.

The configuration is stored in the DAGZ database. Subsequent visits show a Microsoft sign-in button on the login page.

7. Add more users​

Only the bootstrap admin can sign in initially. Add other users through the admin console.

There are two ways to grant access:

  • Per-user permit: grant a specific user (by UPN, e.g. [email protected]).
  • Per-domain permit: grant everyone in a domain (e.g. example.com) a default role.

In the DAGZ console: go to the admin section, choose Permits, and add an entry. The new user can then sign in with the same Microsoft button.

CLI sign-in​

Developers sign in once per machine:

zb login

The CLI opens a browser tab. Sign in with Microsoft. The browser tab closes automatically and the CLI receives a client certificate valid for 90 days.

Troubleshooting​

"AADSTS50020" or tenant mismatch​

The signed-in account is not in your tenant. Confirm the user belongs to the tenant whose ID is in dagz-entra-oidc.json.

"AADSTS50011: Reply URL mismatch"​

The redirect URI in the Entra app registration does not match what DAGZ is sending. Common causes:

  • Trailing slash on the SPA redirect URI. The SPA URI must be the exact origin (https://dagz.example.com), not https://dagz.example.com/.
  • DAGZ is deployed at a different host than registered. Update the SPA platform's redirect URI to match.
  • The CLI redirect URI is registered on the SPA platform instead of the Web platform. Implicit ID token grant only works on the Web platform.

"JWT signing key not found in provider's JWK set"​

The jwks_uri is wrong or unreachable. Verify the URL follows https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys and that the DAGZ pods or containers can reach login.microsoftonline.com over HTTPS.

"Invalid Entra issuer" or "cannot decode oidc claims"​

The ID token is missing a claim DAGZ expects, or comes from an unexpected issuer. Check Token configuration in the app registration and confirm the optional claims listed in step 3 are added. If the issue persists, check the user's profile in Entra: a missing givenName or familyName on the user record can cause decode to fail.

Setup page reappears after the Microsoft redirect​

The browser blocked sessionStorage or third-party cookies. Open DAGZ in a normal window (not private/incognito) and disable extensions that strip session data.