SAML with Okta

Goal: login through Okta works and your admin user gets org_admin. Okta sends no attribute statements by default, so unlike authentik the mapping step here is mandatory — the okta preset just fixes the names you use (email, name, groups), so you don't have to type Microsoft claim URIs into Okta.

1. Create the app integration

Admin console → Applications → Applications → Create App Integration

• Sign-in method: SAML 2.0 → Next.
• App name: OrbitalReg → Next.

SAML settings (General):

• Single sign-on URL: https://<domain>/saml/acs — https, no trailing slash. Leave "Use this for Recipient URL and Destination URL" checked.
• Audience URI (SP Entity ID): https://<domain>/saml/metadata — must match saml.entityID exactly.
• Name ID format: EmailAddress.
• Application username: Email.

Okta posts the SAML response to the single sign-on URL (POST binding) by default — nothing to change for the ACS. If you enable signed requests validation under Show Advanced Settings → Signed Requests, upload the OrbitalReg SP certificate (sp.crt) there; OrbitalReg signs its AuthnRequests, and Okta rejects signed requests it cannot verify.

2. Attribute statements

Still in the SAML settings, add:

Attribute Statements:

Name	Name format	Value
email	Unspecified	user.email
name	Unspecified	user.displayName

Group Attribute Statements:

Name	Name format	Filter
groups	Unspecified	Matches regex .* (or Starts with: orbital- to limit exposure)

The names email / name / groups are exactly what the okta preset reads. If you prefer other names, keep them consistent with saml.claimEmail / claimName / claimGroups overrides.

Finish the wizard ("I'm an Okta customer adding an internal app").

3. Create the admin group + assignments

• Directory → Groups → Add group: orbital-admins; add your user.
• Applications → OrbitalReg → Assignments: assign the group (or the users) to the app — unassigned users get a 403 from Okta before OrbitalReg is ever involved.

4. Copy the metadata URL

Applications → OrbitalReg → Sign On tab → "SAML Setup" / Metadata URL (form: https://<org>.okta.com/app/<app-id>/sso/saml/metadata). This becomes saml.idpMetadataURL.

5. Values + deploy

Complete example: charts/orbitalreg/values-okta.yaml.example. Essentials:

saml:
  enabled: true
  idpPreset: "okta"
  rootURL: "https://registry.example.com"
  entityID: "https://registry.example.com/saml/metadata"
  idpMetadataURL: "https://<org>.okta.com/app/<app-id>/sso/saml/metadata"
  existingSecret: "orbitalreg-saml-sp"

auth:
  adminGroups:
    - "orbital-admins"        # Okta group NAME (not ID)

helm upgrade orbitalreg charts/orbitalreg -n <ns> -f values-okta.yaml

6. Verify

Log out fully (including the Okta session), log in, then check https://<domain>/auth/whoami: groups contains orbital-admins, roles contains org_admin. If groups is empty, add your login email to auth.adminGroups as a temporary fallback and debug the group statement afterwards.

Troubleshooting

Symptom	Cause	Fix
Pod crashes, saml init failed	Metadata URL wrong/unreachable (typo in app-id, org URL, TLS interception)	curl the metadata URL from the pod network
Okta error 403 "user is not assigned"	User/group not assigned to the app	Applications → Assignments
"response code null" on login click	Metadata fetched through a proxy/internal alias so endpoint URLs don't match your Okta org	Use the canonical https://<org>.okta.com/... metadata URL
HTTP 405 after Okta login	Response arrives as GET — someone switched the app to Redirect binding, or the SSO URL points at a non-ACS path	Keep the default POST binding; SSO URL exactly https://<domain>/saml/acs
404 on /saml/acs	Trailing slash / different path in the Single sign-on URL	Exact URL, no trailing slash
405 opening /saml/acs in a browser	Normal — GET on a POST-only endpoint	Not an error
Login works but roles: reader	Group filter doesn't include your group, or group name ≠ auth.adminGroups entry	Widen the regex filter; match the Okta group name exactly
Okta "invalid signature on AuthnRequest"	Signed-requests validation enabled with wrong/missing SP cert	Upload the current sp.crt under Signed Requests, or disable validation
groups empty in whoami	Group Attribute Statement missing, name ≠ groups (preset), or stale session	Add the statement; re-login completely

Reference: what OrbitalReg reads (preset okta)

OrbitalReg expects	SAML attribute name
Email (identity)	email
Groups (→ role)	groups
Display name	name

See the SSO overview for role mapping and claim-name overrides.