Skip to main content

Microsoft Entra ID (self-hosted)

Overview​

A self-hosted installation signs everyone in with your Microsoft Entra ID tenant. You register one web app in Entra and give its details to the Edge's sign-in service. It's configuration only: no code changes.

Prerequisites​

  • An Entra ID role that can create app registrations and grant admin consent (for example Application Administrator).
  • The installation's domain. Below, <domain> is the domain your apps live under, for example apps.contoso.com.
  • Somewhere to keep secrets for the installation, such as Azure Key Vault.

Permissions​

ItemValueWhy
Sign-in scopesopenid profile emailID token with the user's id, name and email
ID token claimgroupsGroup membership in the token (the Hub also reads memberships from the directory)
Graph application permissionsUser.Read.All, GroupMember.Read.AllFor the planned Graph directory driver: Org Sync will read users, managers, departments and groups (read-only)

Setup steps​

Step 1: Register the app in Entra​

  1. In the Microsoft Entra admin center, go to Entra ID › App registrations and select New registration.
  2. Add a Web redirect URI: https://auth.<domain>/callback.
  3. Add https://auth.<domain>/signed-out as a second Web redirect URI. Entra only returns people to a post-sign-out URL that is registered as a redirect URI. (Don't set it as the front-channel logout URL: that page doesn't clear the session.)
  4. Under Token configuration, add the groups claim to the ID token.
  5. Under Certificates & secrets, create a client secret, or upload a certificate.
  6. Copy the Application (client) ID and the Directory (tenant) ID.

Step 2: Configure the installation​

Set these on the Edge's sign-in service (edge-auth):

VariableValue
TC_OIDC_ISSUERhttps://login.microsoftonline.com/<tenant-id>/v2.0
TC_OIDC_CLIENT_IDThe application (client) ID
TC_OIDC_CLIENT_SECRETThe client secret, or use a certificate (next two rows)
TC_OIDC_CLIENT_CERT_KEYPEM private key of the certificate
TC_OIDC_CLIENT_CERT_THUMBPRINTThe certificate's SHA-1 thumbprint in hex (sent as x5t)
TC_ENTRA_TENANT_ID<tenant-id>. Tokens from any other tenant are refused.
TC_OIDC_INTERNAL_URLLeave empty
TC_PUBLIC_SCHEME / TC_PUBLIC_PORThttps / 443
TC_SESSION_SECRETA random secret of at least 32 characters
TC_INTERNAL_TOKENA random secret shared by the Edge and the Hub

Step 3: Choose the Org Admin group​

On the Hub API, TC_ADMIN_GROUP names the Entra group whose members are Org Admins. The default is IT Admins.

Step 4: Leave development tokens off​

Development tokens are off unless TC_DEV_TOKEN is set. Make sure it isn't set on the Hub API in production; the Hub logs a warning at start-up when they are on.

warning

Keep TC_SESSION_SECRET, TC_INTERNAL_TOKEN and the client secret out of source control. Rotating TC_SESSION_SECRET signs everyone out.

Verify​

  1. Open https://console.<domain> in a private window. You should land on the Microsoft sign-in page.
  2. Sign in as a member of the admin group. Admin should appear in the sidebar.
  3. Open Admin › Sign-in. It shows "Microsoft Entra ID (this installation)".
  4. Sign in as someone from another Entra tenant. They should be refused.

Troubleshooting​

SymptomCauseFix
"Sign-in unavailable: The identity provider is not reachable"The Edge can't fetch the issuer's discovery documentCheck TC_OIDC_ISSUER and outbound network access.
AADSTS50011 redirect URI mismatchThe redirect URI in Entra doesn't matchRegister exactly https://auth.<domain>/callback.
"Token is from tenant …, expected …"A user from another tenantExpected. Remove TC_ENTRA_TENANT_ID only if you really accept other tenants.
"Sign-in expired"The sign-in took more than 10 minutes, or the browser blocked cookiesStart again; allow cookies for auth.<domain>.
No Admin in the sidebarNot in the admin groupAdd the user to the group named by TC_ADMIN_GROUP.
Availability

Reading Hub roles from Entra app roles, a Graph-backed directory driver for Org Sync, and Key Vault for secrets are planned for Azure installations. The local stack uses a mock Entra sign-in page with a fixture organization.

Was this page helpful?