Skip to content

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.

  • 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

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

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.

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.

  1. Go to Expose an API
  2. Set the Application ID URI to api://{client_id} (the default Entra suggests is fine)
  3. Add a scope:
    • Scope name: access_as_user
    • Who can consent: Admins and users
    • Fill in the consent display names and descriptions, then add
  4. 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.

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.

  1. Go to Token configuration → Add groups claim
  2. Select Security groups
  3. 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.

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.

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).

  1. Go to API permissions → Add a permission → Microsoft Graph → Application permissions
  2. Add User.Read.All, Group.Read.All, and GroupMember.Read.All
  3. 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.

  1. Go to Certificates & secrets → Client secrets → New client secret
  2. Set a description and expiry, then add
  3. 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.

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.

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.

Once installed, a browser login flows end-to-end:

  1. User visits https://idp.acme.internal → Shoehorn redirects to Entra
  2. User authenticates → Entra redirects back to /api/v1/auth/callback with an access token for api://{client_id} (the reason step 2 matters)
  3. Shoehorn verifies the token against the tenant’s JWKS, then checks the issuer, the audience, and that the token’s tid claim matches ENTRA_TENANT_ID
  4. If the user doesn’t exist in Shoehorn, it JIT-provisions them from the token claims
  5. 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
  6. 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.

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).

When debugging claim issues, paste the token into jwt.ms and check:

  • iss is https://login.microsoftonline.com/<tenant>/v2.0 (a https://sts.windows.net/<tenant>/ issuer means you’re getting a v1.0 token, so fix requestedAccessTokenVersion in step 2)
  • aud is your ENTRA_CLIENT_ID or api://<client_id>
  • tid matches your ENTRA_TENANT_ID
  • groups carries the expected GUID array (or _claim_names if you’re over the overage limit)

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).

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