Okta Integration

Shoehorn supports Okta as both an authentication provider (OIDC) and an orgdata provider (Okta Management API for user/team sync). This guide walks through the exact Okta app configuration, Helm values, and troubleshooting mapped to the error codes Shoehorn emits on /auth-error.

Prerequisites

An Okta organization with admin access
Shoehorn deployed via the Helm chart: see Helm deployment
Your Shoehorn domain (e.g. shoehorn.example.com) reachable from browsers that will sign in

1. Create the Okta App

In the Okta admin console, go to Applications → Create App Integration and select:

Sign-in method: OIDC – OpenID Connect
Application type: Web Application

Then configure the following fields exactly: the non-default values matter:

Field	Value
App name	`Shoehorn`
Client authentication	`Client secret`
Proof of possession (PKCE)	`Require PKCE as additional verification`
Client secrets	Generate one and copy it: you will store this as `OKTA_CLIENT_SECRET`
Grant type	☑ `Authorization Code` ☑ `Refresh Token`
Refresh token behavior	`Rotate token after every use`
Sign-in redirect URIs	`https://<your-domain>/api/v1/auth/callback`
Sign-out redirect URIs	`https://<your-domain>`
Login initiated by	`App Only`
Controlled access	Assign to the Okta groups that should have Shoehorn access

Save, then copy the Client ID: you will store this as OKTA_CLIENT_ID.

Optional: sign-on policy

If users cannot sign in after completing the rest of this guide, check Applications → Shoehorn → Sign On → Sign On Policy. A permissive starting rule is:

Catch-all rule: Access = Allowed, Authentication = Any 2 factor types

Tighten this once signing in works end-to-end.

2. Add the Groups Claim

Okta does not include group membership in the ID token by default. Without this claim, Shoehorn cannot map your Okta groups to Shoehorn roles: logins will land on /auth-error?code=GROUPS_CLAIM_MISSING.

Security → API → Authorization Servers: select the default authorization server (or your custom one)
Claims tab → Add Claim

Field	Value
Name	`groups`
Include in token type	`ID Token`, `Always`
Value type	`Groups`
Filter	`Matches regex`, value `.*`
Include in	`Any scope`

Save. Use Okta’s Token Preview (same authorization server page) to confirm the token now carries a groups array.

3. Add the Tenant (`okta_org`) Claim

Required for production. Without it, every login fails with INVALID_CLAIMS and the user lands on /auth-error. Shoehorn uses this claim as the tenant id for every request; if it’s missing, the request is rejected.

Go to Security → API → Authorization Servers and select the same authorization server you used for the groups claim
Open the Claims tab and click Add Claim

Field	Value
Name	`okta_org`
Include in token type	`ID Token`, `Always`
Value type	`Expression`
Value	Your Okta org id, or an expression that returns it. A literal like `"acme"` works for a single-tenant deploy. For per-user attribution use something like `user.organization`.
Include in	`Any scope`

The value is an opaque tenant id, so pick something stable. Once a user has signed in with one value, switching to another would orphan their existing data.

Use Okta’s Token Preview to confirm the ID token now carries okta_org.

4. (Optional) Create an API Token for Orgdata Sync

If you want Shoehorn to sync users and teams proactively from Okta: rather than only resolving memberships on individual logins:

Security → API → Tokens → Create Token
Name: Shoehorn Orgdata Sync
Copy the token: you will store this as OKTA_API_TOKEN

The token runs as the creating user. If that user loses read access to users or groups, sync breaks silently: prefer creating the token as a dedicated service account.

5. Configure Shoehorn (Helm)

The chart’s examples/values-okta.yaml is the canonical reference. It stays in sync with the chart schema. Copy it and fill in the CHANGE_ME markers.

The Okta-specific keys you’ll set:

Path	Source
`auth.provider: okta`	required
`auth.okta.domain`	step 1 — bare host, no scheme
`auth.okta.clientId`	step 1
`auth.okta.clientSecretRef.key`	the key inside your Secret that holds the client secret
`auth.okta.apiTokenSecretRef.key`	the key holding the Management API token, only if you enable orgdata sync (step 4)
`auth.orgdata.enabled: true`	to sync users and teams from Okta
`rbac.roleAssignment.tenantAdmin.user` or `.group`	a single email or Okta group; the matching account gets `tenant:admin` on first sign-in while no roles exist yet

For the secret keys (okta_client_secret, okta_api_token, session/JWT keys, postgres/valkey/meili keys), follow the secret-creation command in the chart’s README or values-okta.yaml header. Postgres and DB passwords must be URL-safe: use openssl rand -hex, not -base64.

The chart’s schema enforces that auth.okta.domain and auth.okta.clientId are set whenever auth.provider: okta. helm install refuses with a minLength: got 0, want 1 error if either is missing, and rejects the example placeholders (your-org.okta.com, 0oaXXXXXXXXXXXXXX) with a field-named error.

6. How It All Connects

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

User visits https://shoehorn.example.com → Shoehorn redirects to Okta
User authenticates in Okta → Okta redirects back to /api/v1/auth/callback with an ID token
Shoehorn verifies the ID token signature against Okta’s JWKS (fetched from auth.okta.domain), then validates issuer and audience
If the user doesn’t exist in Shoehorn, it JIT-provisions them using sub, email, and groups claims
Shoehorn resolves roles:
- First it checks rbac.roleAssignment.tenantAdmin.user/.group against the user’s email/Okta groups (bootstrap path, only while the roles table is empty)
- Then it applies Shoehorn-side group → role mappings configured under Admin → Directory → Teams
If auth.orgdata.enabled, a targeted sync fires for the new user so team-based mappings resolve immediately rather than waiting for the next scheduled sync

Logout follows the OIDC RP-initiated logout spec:

User clicks Sign out → browser hits /api/v1/auth/logout
Shoehorn clears its session, then discovers Okta’s end_session_endpoint and redirects the browser there
Okta clears its own session and redirects back to your Shoehorn domain
The user lands signed-out; re-opening Shoehorn prompts Okta login afresh

7. Troubleshooting

When login fails, Shoehorn redirects to /auth-error?code=<CODE>. The code tells you where to look:

Symptom / `code`	Likely cause	Fix
`code=GROUPS_CLAIM_MISSING`	Groups claim not configured on the authorization server	Repeat step 2. Use Okta’s Token Preview to confirm the claim appears.
`code=INVALID_CLAIMS`	`okta_org` claim missing or empty	Repeat step 3. Use Token Preview to confirm `okta_org` is set.
`code=NO_ROLES`	User has Okta groups, but none 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`	`OKTA_DOMAIN` is the full URL, not the bare domain, or the token endpoint is unreachable	Use `your-org.okta.com`, no scheme, no slash. Check your cluster’s egress network path to Okta.
`code=JWKS_UNAVAILABLE`	Shoehorn couldn’t fetch Okta’s signing keys	Usually transient. If it persists, verify `OKTA_DOMAIN` and your cluster’s egress network path to Okta.
Login redirects back to Okta in a loop	Session cookie expiring at epoch 0 (very old Shoehorn build)	Upgrade to Shoehorn ≥ v0.4.3.
Test Connection fails with “invalid API token”	Token was revoked or the creating user was deactivated	Recreate the token as a dedicated service account.
Test Connection fails with “host unreachable”	`OKTA_DOMAIN` contains the full URL	Use `your-org.okta.com`, no scheme, no slash.
After logout, user is auto-signed back in	`end_session_endpoint` not called: misconfigured app	Confirm Sign-out redirect URIs in the Okta app includes `https://<your-domain>`.

Decoding the ID token

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

iss matches https://<domain> (or https://<domain>/oauth2/<authz-server-id> if you use a custom authorization server)
aud equals your OKTA_CLIENT_ID
groups contains the expected array
sub is the stable Okta user ID (e.g. 00uXXXXXXXXXXXXXX)

Using the admin Test Connection button

Once deployed, visit Admin → Integrations → External → Okta in Shoehorn. The Test Connection button calls the Okta Management API with your stored token and returns a green banner on success or the exact upstream error on failure. It’s the fastest way to verify OKTA_API_TOKEN before investigating deeper.

8. Provider Matrix

Shoehorn lets you mix auth and orgdata providers:

Authentication	Orgdata	Supported
Okta	Okta	✅ Most common
Okta	Zitadel	✅
Zitadel	Okta	✅
Okta	none (orgdata disabled)	✅ Relies on `rbac.roleAssignment.tenantAdmin` + in-app role assignment