Microsoft Entra ID Integration (included in v0.7.0+)
Shoehorn supports Microsoft Entra ID (formerly Azure AD) as both an authentication provider (OIDC) and an orgdata provider (Microsoft Graph for user and team sync). This guide walks through the exact app registration, the one Entra-specific step that trips up most setups (Expose an API), the Helm values, and troubleshooting mapped to the error codes Shoehorn emits on /auth-error.
Prerequisites
Section titled “Prerequisites”- An Entra tenant where you can register an app. Granting admin consent on the Graph permissions needs a Global Administrator or Privileged Role Administrator.
- Shoehorn deployed via the Helm chart: see Helm deployment
- Your Shoehorn domain (e.g.
idp.acme.internal) reachable from browsers that will sign in
1. Register the App
Section titled “1. Register the App”In the Entra admin center, go to Identity → Applications → App registrations → New registration:
| Field | Value |
|---|---|
| Name | Shoehorn |
| Supported account types | Accounts in this organizational directory only (single-tenant) |
| Redirect URI | Platform Web, value https://<your-domain>/api/v1/auth/callback |
Register, then from the Overview page copy:
- Directory (tenant) ID: you will store this as
ENTRA_TENANT_ID - Application (client) ID: you will store this as
ENTRA_CLIENT_ID
Register the post-logout redirect URI
Section titled “Register the post-logout redirect URI”Under Authentication → Web, add https://<your-domain> to the platform’s redirect URIs. Entra uses it as the post_logout_redirect_uri after sign-out.
Without it, Entra signs the user out but strands them on a generic Microsoft “you’re signed out” page instead of returning to Shoehorn.
2. Expose an API
Section titled “2. Expose an API”This is the step that makes Entra work at all. Skip it and every login fails at signature verification.
If Shoehorn only requested openid profile email, Entra would hand back a Microsoft Graph access token. Graph tokens carry a proprietary value in their header and cannot be validated by anything other than Microsoft, so Shoehorn’s signature check rejects every one of them. To get a normal, verifiable token, the app has to expose its own API and Shoehorn requests a scope on it.
- Go to Expose an API
- Set the Application ID URI to
api://{client_id}(the default Entra suggests is fine) - Add a scope:
- Scope name:
access_as_user - Who can consent:
Admins and users - Fill in the consent display names and descriptions, then add
- Scope name:
- Go to Manifest and set
"requestedAccessTokenVersion": 2
The requestedAccessTokenVersion: 2 line forces v2.0-format access tokens. Without it Entra issues v1.0 tokens whose issuer is https://sts.windows.net/{tenant}/, which fails Shoehorn’s issuer check. The troubleshooting table below maps both failure signatures back to this step.
3. Add the Groups Claim
Section titled “3. Add the Groups Claim”Entra does not include group membership in tokens by default. Without it, Shoehorn cannot map your groups to Shoehorn roles and logins land on /auth-error?code=GROUPS_CLAIM_MISSING.
- Go to Token configuration → Add groups claim
- Select Security groups
- Save
Entra emits groups as object-ID GUIDs, not names. That’s expected. Shoehorn resolves each GUID to its display name through org data sync, so the mapping UI under Admin → Directory → Teams shows readable group names while Shoehorn stores the GUID.
Large directories (200+ groups)
Section titled “Large directories (200+ groups)”A token can only carry about 200 group IDs. Above that, Entra drops the groups claim and signals an overage instead. Shoehorn handles this by falling back to Microsoft Graph to look up the user’s group membership at login, so sign-in still works. It adds a Graph call per login, so if you’re near the limit, switch the groups claim to Groups assigned to the application (in the same Add groups claim dialog). That emits only the groups assigned to the Shoehorn app and keeps you under the cutoff.
4. API Permissions for Org Data Sync
Section titled “4. API Permissions for Org Data Sync”Org data sync reads users, groups, and memberships from Microsoft Graph. It reuses the same app registration and client secret as sign-in, so there’s no separate token to manage (unlike Okta’s API token).
- Go to API permissions → Add a permission → Microsoft Graph → Application permissions
- Add
User.Read.All,Group.Read.All, andGroupMember.Read.All - Click Grant admin consent for {tenant}
These are application permissions, so admin consent is required. Until consent is granted, the green checkmarks stay missing and Test Connection in Shoehorn returns a 502.
5. Create a Client Secret
Section titled “5. Create a Client Secret”- Go to Certificates & secrets → Client secrets → New client secret
- Set a description and expiry, then add
- Copy the Value immediately. Entra only shows it once.
You will store this as ENTRA_CLIENT_SECRET. Microsoft caps client secrets at 24 months and recommends shorter rotation, so set a reminder to roll it before it expires.
The secret goes into a Kubernetes Secret and is referenced from the Helm values through a typed clientSecretRef. Don’t paste the secret into your values file.
6. Configure Shoehorn (Helm)
Section titled “6. Configure Shoehorn (Helm)”The chart’s examples/values-entraid.yaml is the canonical reference. It stays in sync with the chart schema. Copy it and fill in the CHANGE_ME markers.
The Entra-specific keys you’ll set:
| Path | Source |
|---|---|
auth.provider: entra-id |
required |
auth.entraId.tenantId |
step 1, Directory (tenant) ID |
auth.entraId.clientId |
step 1, Application (client) ID |
auth.entraId.clientSecretRef.key |
the key inside your Secret that holds the client secret |
auth.orgdata.enabled: true |
to sync users and teams from Entra |
auth.orgdata.providers: ["entra-id"] |
use Entra as the org data source |
rbac.roleAssignment.tenantAdmin.user or .group |
a single email or Entra group; the matching account gets tenant:admin on first sign-in while no roles exist yet |
These map to the following environment variables in the running services:
| Env var | Value |
|---|---|
AUTH_PROVIDER |
entra-id |
ORGDATA_PROVIDERS |
entra-id |
ENTRA_TENANT_ID |
Directory (tenant) ID |
ENTRA_CLIENT_ID |
Application (client) ID |
ENTRA_CLIENT_SECRET |
client secret value (from the Kubernetes Secret) |
For the secret keys (entra_client_secret, session/JWT keys, postgres/valkey/meili keys), follow the secret-creation command in the values-entraid.yaml header. Postgres and DB passwords must be URL-safe: use openssl rand -hex, not -base64.
The chart’s schema enforces that auth.entraId.tenantId and auth.entraId.clientId are set whenever auth.provider: entra-id. helm install refuses if either is missing.
7. First Admin
Section titled “7. First Admin”Pick the first admin before you install. Set one of rbac.roleAssignment.tenantAdmin.user (a single email) or rbac.roleAssignment.tenantAdmin.group (a single Entra group name). The matching account gets the tenant:admin role on first sign-in, but only while no roles exist in the database yet. This works the same way for every provider.
This works even when Entra doesn’t emit email_verified (it often doesn’t). The operator already controls both the IdP and this setting, so the IdP itself is the gatekeeper.
8. How It All Connects
Section titled “8. How It All Connects”Once installed, a browser login flows end-to-end:
- User visits
https://idp.acme.internal→ Shoehorn redirects to Entra - User authenticates → Entra redirects back to
/api/v1/auth/callbackwith an access token forapi://{client_id}(the reason step 2 matters) - Shoehorn verifies the token against the tenant’s JWKS, then checks the issuer, the audience, and that the token’s
tidclaim matchesENTRA_TENANT_ID - If the user doesn’t exist in Shoehorn, it JIT-provisions them from the token claims
- Shoehorn resolves roles:
- First it checks
rbac.roleAssignment.tenantAdmin.user/.group(bootstrap path, only while the roles table is empty) - Then it applies the group → role mappings configured under Admin → Directory → Teams
- First it checks
- If
auth.orgdata.enabled, a sync resolves the user’s groups to display names and team mappings
Logout follows OIDC RP-initiated logout: Shoehorn clears its session, redirects the browser to Entra’s end_session_endpoint, and Entra returns the user to your registered post-logout URI signed out.
9. Troubleshooting
Section titled “9. Troubleshooting”When login fails, Shoehorn redirects to /auth-error?code=<CODE>. The code tells you where to look:
Symptom / code |
Likely cause | Fix |
|---|---|---|
| Sign-in fails right after the Microsoft redirect, or a signature verification error | Expose an API / requestedAccessTokenVersion: 2 not configured, so Entra returned a Graph token Shoehorn can’t validate |
Repeat step 2. Confirm the access_as_user scope exists and the manifest has "requestedAccessTokenVersion": 2. |
code=GROUPS_CLAIM_MISSING |
Groups claim not added to the app registration | Repeat step 3. |
code=NO_ROLES |
User signed in, but none of their groups map to a Shoehorn role | Configure a mapping under Admin → Directory → Teams, or set rbac.roleAssignment.tenantAdmin.user/.group for the bootstrap path (only fires while no roles exist yet). |
code=INVALID_DOMAIN |
ENTRA_TENANT_ID is wrong, or the token endpoint is unreachable |
Confirm the tenant GUID matches the Directory (tenant) ID. Check your cluster’s egress path to login.microsoftonline.com. |
code=JWKS_UNAVAILABLE |
Shoehorn couldn’t fetch Entra’s signing keys | Usually transient. If it persists, verify ENTRA_TENANT_ID and your cluster’s egress path to login.microsoftonline.com. |
| Test Connection returns 502 | Admin consent not granted for the Graph permissions | Repeat step 4 and click Grant admin consent. |
| After logout, the user lands on a generic Microsoft “signed out” page | Post-logout redirect URI not registered | Add https://<your-domain> to the app’s Web redirect URIs (step 1). |
Decoding the token
Section titled “Decoding the token”When debugging claim issues, paste the token into jwt.ms and check:
issishttps://login.microsoftonline.com/<tenant>/v2.0(ahttps://sts.windows.net/<tenant>/issuer means you’re getting a v1.0 token, so fixrequestedAccessTokenVersionin step 2)audis yourENTRA_CLIENT_IDorapi://<client_id>tidmatches yourENTRA_TENANT_IDgroupscarries the expected GUID array (or_claim_namesif you’re over the overage limit)
Using the admin Test Connection button
Section titled “Using the admin Test Connection button”Once deployed, visit Admin → Integrations → Org Data → Entra ID in Shoehorn. The Test Connection button calls Microsoft Graph with your stored credentials and returns a green banner on success or the exact upstream error on failure. A 502 here almost always means admin consent is still pending (step 4).
10. Provider Matrix
Section titled “10. Provider Matrix”Shoehorn lets you mix auth and orgdata providers:
| Authentication | Orgdata | Supported |
|---|---|---|
| Entra ID | Entra ID | ✅ Most common |
| Entra ID | Okta | ✅ |
| Okta | Entra ID | ✅ |
| Entra ID | none (orgdata disabled) | ✅ Relies on rbac.roleAssignment.tenantAdmin + in-app role assignment |
See Also
Section titled “See Also”- Identity Providers overview: all supported IdPs at a glance
- Okta integration: the Okta setup guide
- Zitadel integration: the Zitadel setup guide
- Group mappings: mapping IdP groups to Shoehorn teams and roles
- Team sync: multi-provider synchronization details
- Helm deployment: full Helm install reference