Skip to content

Microsoft Entra ID single sign-on

Microsoft Entra ID (formerly Azure Active Directory) signs a tenant's users in to Myra AI Workspace through the organisation's own directory. Myra supports Entra over both protocols: OpenID Connect (OIDC) and SAML 2.0. A tenant may enable either protocol, or both.

Single sign-on authenticates existing accounts only — it does not create users. Provision the users first (manually, or through SCIM provisioning), then enable single sign-on so those users sign in through Entra.

Required role: tenant admin or admin (the SSO_MANAGE permission).

Note: The examples below use the production admin-API host ai-api-admin.myra.eu. On the integration environment, substitute ai-api-admin-int.myra.eu. Always register the exact host and scheme (https) that the Myra admin panel and the SP metadata display — a mismatch is the most common cause of a rejected sign-in.

Prerequisites

Before you begin, ensure the following conditions are met:

  • An Entra directory in which you can create an app registration (the Application Administrator or Cloud Application Administrator role in Entra, or a global administrator).
  • The tenant's users already exist in Myra AI Workspace, each with an email address in a domain you control.
  • The Myra tenant ID — a UUID. Open the tenant, then the Single sign-on (SSO) section: the SAML panel displays the service-provider URLs with this UUID already embedded. The SAML endpoints use this UUID, not the tenant slug.

Setting up OIDC sign-in

Registering the application in Entra

  1. Sign in to the Microsoft Entra admin center.
  2. Open Applications → App registrations → New registration.
  3. Enter a name, for example Myra AI Workspace.
  4. Under Supported account types, select Accounts in this organizational directory only (single-tenant).
    • This is the correct choice for signing in your own organisation's users.

  5. Under Redirect URI, select the platform Web and enter the Myra OIDC callback URL exactly:

    https://ai-api-admin.myra.eu/admin/auth/oidc/callback
    • This is a single, fixed callback URL. It is not tenant-specific — Myra recovers the tenant from the signed login state, not from the URL.
    • Select Register. -> The application's Overview page shows the Application (client) ID and the Directory (tenant) ID. Record both.

Creating a client secret

  1. Open the registered application → Certificates & secrets → Client secrets → New client secret.
  2. Enter a description and an expiry.
  3. Select Add.
  4. Copy the secret Value immediately. -> Entra shows the secret value only once. Store it securely; you paste it into Myra in a later step.

Entra frequently omits the email claim from the id_token. Myra resolves the user by the claim precedence email → preferred_username → upn, so sign-in still works without email, but adding the claim makes the mapping explicit.

  1. Open the registered application → Token configuration → Add optional claim.
  2. Select the token type ID.
  3. Select the claim email.
  4. Select Add.
  5. If Entra prompts to turn on the Microsoft Graph email permission, accept it.

The requested scopes are openid, email, and profile. If your directory requires admin consent for these scopes, grant it once so users are not blocked at first sign-in.

  1. Open the registered application → API permissions.
  2. Verify that Microsoft Graph lists the delegated permissions openid, email, and profile.
  3. Select Grant admin consent for [directory]. -> A missing admin consent returns the sign-in error AADSTS65001 (see Troubleshooting).

Configuring the OIDC panel in Myra

  1. Open Administration → Tenants.
  2. Select the tenant, then open its edit dialog.
  3. Open the Single sign-on (SSO) section.
  4. Select the Single sign-on (OIDC) enabled checkbox.

  5. In the Issuer URL field, enter the Entra issuer for your directory:

    https://login.microsoftonline.com/<directory-tenant-id>/v2.0
    • Replace <directory-tenant-id> with the Directory (tenant) ID recorded earlier.
    • In the Client ID field, enter the Application (client) ID.
    • In the Client secret field, paste the secret Value.
    • Leave the Subject claim drop-down list set to oid.
    • oid is the stable Entra directory object identifier. Do not use a mutable claim.
    • In the Allowed email domains field, enter the comma-separated domains whose users may sign in, for example corp.example, sub.corp.example.
    • This is the verified-domain allowlist. Entra may only sign in users at these domains.
    • If required, map an Entra group or directory attribute to Myra groups using the Group attribute and Group mapping fields.
    • Save the dialog. -> The Single sign-on (OIDC) enabled checkbox stays selected, and the tenant's users can now sign in through Entra.

Hardening controls

Two hardening controls set the directory tenant pin and the guest sign-in policy. Set them in the OIDC panel — the Entra directory ID field and the Allow guest sign-in option — or through the admin API (the entra_tenant_id / allow_guest_signin fields shown below).

  • entra_tenant_id (panel: Entra directory ID) — the directory GUID. When set, Myra rejects any id_token whose tid claim is not this directory, even if the issuer and audience match — defence in depth against a token from another directory that merely lists Myra in its audience. This field is required when the Issuer URL uses the templated {tenantid} form (see Multi-directory app registrations).
  • allow_guest_signin (panel: Allow guest sign-in) — default false. When false, an Entra B2B guest identity (a #EXT# marker in the upn/preferred_username claim) is rejected at login. Enable it only if guests must sign in.

The admin-API equivalent — send the complete configuration, as a PUT is a full replacement, so include every OIDC field (omit entra_tenant_id to clear the pin):

curl -X PUT https://ai-api-admin.myra.eu/admin/v1/tenants/<tenant-id>/sso-config \
  -H "Content-Type: application/json" \
  -d '{
    "issuer": "https://login.microsoftonline.com/<directory-tenant-id>/v2.0",
    "client_id": "<application-client-id>",
    "client_secret": "<secret-value>",
    "subject_claim": "oid",
    "allowed_email_domains": "corp.example, sub.corp.example",
    "entra_tenant_id": "<directory-tenant-id>",
    "allow_guest_signin": false,
    "enabled": true
  }'

Note: Myra pins the token's tid to entra_tenant_id for both the v1 (https://sts.windows.net/<tid>/) and v2 (https://login.microsoftonline.com/<tid>/v2.0) token forms. Each configuration matches the one issuer form its Issuer URL declares.

Multi-directory app registrations (advanced)

Each Myra tenant pins exactly one Entra directory. A single Myra tenant cannot accept users from several directories — the tid pin admits only the one directory named by entra_tenant_id.

Use this section only when the app registration itself is multi-directory — that is, it was created with the Accounts in any organizational directory account type, so Entra returns the templated discovery issuer rather than a fixed one. In that case:

  1. Set the Issuer URL to the templated form:

    https://login.microsoftonline.com/{tenantid}/v2.0

  2. Set entra_tenant_id to the directory GUID this Myra tenant serves.

    • Myra fills the {tenantid} placeholder with this GUID and then matches the issuer exactly.
    • entra_tenant_id is required here. If it is unset, the literal {tenantid} never matches the token issuer and every sign-in is rejected.

To serve a second Entra directory, create a second Myra tenant with its own entra_tenant_id.

Setting up SAML sign-in

Use SAML when the organisation standardises on SAML 2.0 rather than OIDC. Myra acts as the SAML service provider (SP); Entra is the identity provider (IdP).

Reading the SP values from Myra

  1. Open Administration → Tenants → the tenant → edit dialog → Single sign-on (SSO).
  2. Select the SAML 2.0 SSO checkbox. -> The panel displays the SP entity ID / metadata URL and the ACS (Assertion Consumer Service) URL to register in Entra. These use the admin-API host over HTTPS.

The SP URLs follow this pattern, where <tenant-id> is the Myra tenant UUID:

IdP field (Entra) Myra SP value
Identifier (Entity ID) https://ai-api-admin.myra.eu/admin/auth/saml/<tenant-id>/metadata
Reply URL (ACS) https://ai-api-admin.myra.eu/admin/auth/saml/<tenant-id>/acs
Logout URL https://ai-api-admin.myra.eu/admin/auth/saml/<tenant-id>/sls

Note: Register the values exactly as the Myra panel and the SP /metadata document show them. The SP metadata is authoritative.

Registering the enterprise application in Entra

  1. In the Entra admin center, open Applications → Enterprise applications → New application → Create your own application.
  2. Enter a name, select Integrate any other application you don't find in the gallery (Non-gallery), then select Create.
  3. Open the new application → Single sign-on → SAML.
  4. In Basic SAML Configuration, enter the Myra SP values from the table above: the Identifier (Entity ID), the Reply URL (ACS), and the Logout URL.
  5. Under Attributes & Claims, set the Unique User Identifier (Name ID) to a stable value — the user's user.mail (email address) or user.objectid (persistent object identifier).
    • Myra rejects a transient NameID. Accepted formats are persistent, emailAddress, unspecified, X509SubjectName, kerberos, and WindowsDomainQualifiedName.
  6. In the SAML Certificates section, download the Certificate (Base64).
  7. Record the Azure AD Identifier (the IdP entity ID) and the Login URL (the IdP SSO URL) from the Set up section.
  8. Assign the tenant's users to the application under Users and groups.

Configuring the SAML panel in Myra

  1. In the tenant edit dialog → Single sign-on (SSO) → SAML 2.0 SSO, enter the values from Entra.
  2. In the IdP entity ID field, enter the Azure AD Identifier.
  3. In the IdP SSO URL field, enter the Login URL.
  4. In the IdP signing certificate (PEM) field, paste the downloaded certificate.
  5. In the NameID format drop-down list, select the format that matches the Entra Name ID choice.
  6. In the Allowed email domains field, enter the permitted domains.
  7. If the organisation uses Single Logout, enter the Entra logout endpoint in the Single Logout URL field.
    • The Single Logout endpoint appears in the SP metadata only when this field is set.
  8. If the organisation requires signed authentication requests, select the Sign authentication requests option.
    • Signed requests need a gateway-wide SP signing key. If the key is not provisioned, the request path fails closed. Contact the platform operator before enabling this option.
  9. Save the dialog. -> The tenant's users can sign in through Entra over SAML.

Testing the sign-in

  1. Open the Myra sign-in page.
  2. Enter an email address in an allowed domain. -> The Continue with SSO button appears.
  3. Select Continue with SSO. -> The browser redirects to Entra, authenticates, and returns to Myra with an active session.

If a domain is configured for both OIDC and SAML, Myra uses OIDC.

Troubleshooting

The table lists the Entra errors most often seen during setup and their remedy. Myra maps an identity-provider error to a sanitised message and returns HTTP 403 at the callback — it never reflects the raw Entra error_description.

Symptom Cause Remedy
AADSTS65001 — consent required Admin consent was not granted for the requested scopes Grant admin consent on the app registration's API permissions page
AADSTS50011 — redirect URI mismatch The registered redirect URI does not match Myra's callback exactly Register https://ai-api-admin.myra.eu/admin/auth/oidc/callback with no trailing characters
Sign-in denied at Myra with 403 A Conditional Access policy blocked the sign-in, or the user cancelled Review the Entra Conditional Access policy for the user
User signed in but is not recognized The token carried no email, preferred_username, or upn in an allowed domain Add the email optional claim, or confirm the user's domain is in Allowed email domains
Guest cannot sign in allow_guest_signin is false and the identity is an Entra B2B guest (#EXT#) Enable the Allow guest sign-in option in the OIDC panel (or set allow_guest_signin via the admin API), if guests are intended
tid_mismatch in the audit log The token came from a different Entra directory than entra_tenant_id Confirm entra_tenant_id is the correct directory GUID

For the runtime endpoints and the fail-closed token verification, see Admin API authentication. For a non-Entra identity provider, see Generic OIDC provider and Generic SAML 2.0 provider.