Okta + Relyra

Copy Markdown View Source

Tested against: Okta SAML app UI, April 2026

This is the authoritative Day-1 runbook for the Okta preset. Start here only after the local FakeIdP proof in Getting Started is green.

Tested against

  • Okta SAML 2.0 app integration flow
  • Relyra.Provider.Okta
  • Relyra.Provider.apply_defaults(:okta, ...)

Relyra owns

  • Strict SP-initiated defaults for the Okta preset
  • Signed assertion and signed response requirements
  • Safe default Name ID format and SHA-256 algorithm policy
  • Operator-facing footgun checks for SHA-1 signing and unnecessary IdP-initiated flows

IdP owns

  • The Okta application integration
  • The exact Audience URI (SP Entity ID) and Single sign-on URL values
  • The active signing certificate exported from the Okta admin surface
  • Claim mapping and any org-specific access policy around the app

Host owns

  • Phoenix router wiring, session behavior, and downstream authorization
  • The app's canonical ACS URL and service-provider entity ID
  • Secret management, deployment, and domain ownership

1. Create the SAML app in Okta

In Okta, create a new SAML 2.0 app integration and populate the vendor fields Relyra expects:

  • Audience URI (SP Entity ID): your sp_entity_id
  • Single sign-on URL: your ACS URL
  • Name ID format: leave Unspecified unless you have a strong reason to change it
  • Signature Algorithm: keep RSA-SHA256
  • X.509 Certificate: download the active SHA-256 signing certificate

Okta vocabulary matters here because Relyra's preset hints and operator messages use these exact labels.

2. Configure Relyra

Use the preset so the safe defaults stay aligned with the library's Okta contract:

connection =
  Relyra.Provider.apply_defaults(:okta, [
    sp_entity_id: "https://sp.example.com/metadata",
    acs_url: "https://sp.example.com/saml/acs",
    idp_sso_url: "https://example.okta.com/app/.../sso/saml",
    idp_certificates: ["-----BEGIN CERTIFICATE-----..."]
  ])

Key defaults applied by the preset:

  • allow_idp_initiated?: false
  • require_signed_assertions?: true
  • require_signed_response?: true
  • name_id_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
  • algorithm_policy.signing: :rsa_sha256

3. Proof of success

Use one concrete receipt before treating the provider path as complete:

  • A successful SP-initiated login returns to your host app through the ACS route you configured.
  • The configured sp_entity_id exactly matches Okta's Audience URI (SP Entity ID).
  • The active signing certificate in Relyra matches the one exported from Okta.

Proof receipt:

  • A real Okta login succeeds after the local FakeIdP proof already passed.

4. Common failures

SymptomWhy it happensFix
Audience mismatchOkta's Audience URI (SP Entity ID) does not exactly match sp_entity_idMake the values identical, including trailing slash behavior.
Signed response rejectedThe wrong Okta certificate or a stale certificate is configuredExport the active X.509 Certificate again and update idp_certificates.
Login works in dev but not prodSigning policy drifted to SHA-1 or another weak defaultKeep Signature Algorithm on RSA-SHA256 and preserve the preset defaults.
IdP-initiated login is flakyThe preset is intentionally optimized for SP-initiated flowsLeave allow_idp_initiated? disabled unless you are explicitly supporting that flow.

5. Day-2 notes

  • Re-check the active signing certificate during rotation events.
  • Treat any move toward IdP-initiated login as a deliberate product decision, not a convenience toggle.
  • Keep metadata, audit review, telemetry, and diagnostic-bundle handling in the host application's production follow-on plan.