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 exampleapps.contoso.com. - Somewhere to keep secrets for the installation, such as Azure Key Vault.
Permissions
| Item | Value | Why |
|---|---|---|
| Sign-in scopes | openid profile email | ID token with the user's id, name and email |
| ID token claim | groups | Group membership in the token (the Hub also reads memberships from the directory) |
| Graph application permissions | User.Read.All, GroupMember.Read.All | For 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
- In the Microsoft Entra admin center, go to Entra ID › App registrations and select New registration.
- Add a Web redirect URI:
https://auth.<domain>/callback. - Add
https://auth.<domain>/signed-outas 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.) - Under Token configuration, add the
groupsclaim to the ID token. - Under Certificates & secrets, create a client secret, or upload a certificate.
- 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):
| Variable | Value |
|---|---|
TC_OIDC_ISSUER | https://login.microsoftonline.com/<tenant-id>/v2.0 |
TC_OIDC_CLIENT_ID | The application (client) ID |
TC_OIDC_CLIENT_SECRET | The client secret, or use a certificate (next two rows) |
TC_OIDC_CLIENT_CERT_KEY | PEM private key of the certificate |
TC_OIDC_CLIENT_CERT_THUMBPRINT | The 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_URL | Leave empty |
TC_PUBLIC_SCHEME / TC_PUBLIC_PORT | https / 443 |
TC_SESSION_SECRET | A random secret of at least 32 characters |
TC_INTERNAL_TOKEN | A 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.
Keep TC_SESSION_SECRET, TC_INTERNAL_TOKEN and the client secret out of source control. Rotating TC_SESSION_SECRET signs everyone out.
Verify
- Open
https://console.<domain>in a private window. You should land on the Microsoft sign-in page. - Sign in as a member of the admin group. Admin should appear in the sidebar.
- Open Admin › Sign-in. It shows "Microsoft Entra ID (this installation)".
- Sign in as someone from another Entra tenant. They should be refused.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| "Sign-in unavailable: The identity provider is not reachable" | The Edge can't fetch the issuer's discovery document | Check TC_OIDC_ISSUER and outbound network access. |
AADSTS50011 redirect URI mismatch | The redirect URI in Entra doesn't match | Register exactly https://auth.<domain>/callback. |
| "Token is from tenant …, expected …" | A user from another tenant | Expected. 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 cookies | Start again; allow cookies for auth.<domain>. |
| No Admin in the sidebar | Not in the admin group | Add the user to the group named by TC_ADMIN_GROUP. |
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.