relyra

Relyra

Relyra is a strict-by-default SAML 2.0 Service Provider library for Elixir and Phoenix. Requires Elixir ~> 1.19 (see mix.exs). It is for teams that need enterprise SSO without becoming SAML experts.

Add the dependency:

{:relyra, "~> 1.5"}

Published docs: hexdocs.pm/relyra — Getting Started is the hexdocs home page; the README is the GitHub evaluator router.

Quick Look

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

Presets fill safe defaults underneath — see the Okta runbook for the full receipt.

Start Here

Use one Day-1 route:

1. Browse the documentation overview — Day-1, Day-2, and Reference sections.
2. Install the library and scaffold the host app with mix relyra.install.
3. Follow Getting Started.
4. Prove a local sign-in with the Relyra.TestSupport macro (setup_saml_connection/2, post_saml_response/2) — see Getting Started §3.
5. Choose exactly one first-class provider runbook.
6. Return to the production follow-ons after the first provider is working.

The README is the router. The full onboarding narrative lives in guides/getting_started.md.

If you want the high-level map of what this library is helping you get done, read Jobs To Be Done And User Flows after Getting Started.

Batteries Included Support

Relyra ships 4 first-class presets plus a generic SAML runbook covering 7 IdP families.

First-class batteries-included support (shipped preset module + verified runbook):

• Okta
• Microsoft Entra ID
• Google Workspace
• ADFS

In this repo, "batteries included" means the provider has a shipped preset module, a repo-native runbook, provider-specific field vocabulary, and Day-1 guidance that ends in a concrete receipt.

Use these runbooks only after you complete the local TestSupport proof in Getting Started:

• Okta runbook
• Microsoft Entra ID runbook
• Google Workspace runbook
• ADFS runbook

Custom SAML And Generic Runbook Providers

• Generic SAML runbook: Supported for IdP families without a first-class preset. The operator runbook at guides/recipes/generic_saml.md covers Ping, OneLogin, Shibboleth, Keycloak, IBM Security Verify, CyberArk, and Oracle Access Manager with vendor decoder tables and field-mapping guidance. Use it after the local TestSupport proof and before you start translating your provider's admin vocabulary.
• Custom SAML: Supported when you bring your own IdP-specific field mapping and operator verification beyond the generic runbook tables.
• Not yet shipped: Any provider without a shipped preset module and verified runbook is not first-class batteries-included support.

Relyra does not claim batteries-included support beyond the four first-class presets and the generic SAML runbook families named above.

What Ships In The Library

• Strict SP-initiated login and ACS validation.
• Hardened XML, signature, and protocol checks.
• Provider presets for Okta, Microsoft Entra ID, Google Workspace, and ADFS, plus a generic SAML runbook for seven additional IdP families.
• Relyra.TestSupport and Relyra.TestSupport.FakeIdP for local proof.
• mix relyra.install for minimal host-app scaffolding.
• Optional LiveAdmin, metadata lifecycle, certificate lifecycle, telemetry, audit seams, scheduled refresh, and diagnostic surfaces for later-stage operator workflows.

What Does Not Ship

• OIDC or OAuth flows.
• A hosted broker runtime.
• SCIM lifecycle ownership.
• First-class batteries-included support for providers beyond the four shipped presets and the generic SAML runbook families.

Day-2 And Operator Guides

These surfaces matter after Day-1, but they should not compete with onboarding:

• Getting Started for the canonical Day-1 path.
• Production Ecto path — cluster-safe stores and migrations.
• Incident playbook — evidence surfaces — login trace, telemetry, and audit triage.
• Troubleshooting — SAML error atom decoder.
• Logout recipe — SLO strategy and session boundaries.
• Identity Mapping And Provisioning for the host-owned decision about local account anchors, login-time JIT, and the Relyra.UserMapper seam after the first provider works.
• Jobs To Be Done And User Flows for the implementation-level mental model of the adoption and operations journey.
• Security policy for supported algorithms, disclosure, and release posture.
• Security review packet for auditors and release review.
• Security boundary for reviewer-oriented architecture notes.
• LedgerLoop demo app — a runnable reference app, not part of the Hex package, showing Relyra embedded in a Phoenix SaaS host with Ecto-backed stores and browser-visible receipts.

LiveAdmin is optional. Metadata refresh, certificate rollover, audit review, telemetry wiring, and diagnostic bundles belong after the first successful provider login, not before it.