Authio docs

Single Sign-On

OIDC connections

The generic path for any OpenID Connect IdP. Three values in — issuer, client id, client secret — and Authio runs the full authorization-code + PKCE flow.

Part of Authio Lobby

An OIDC connection federates an organization to any IdP that speaks OpenID Connect — Okta, Auth0, Keycloak, Google, PingFederate, or a generic provider. It’s the right choice whenever the IdP offers OIDC (it’s less brittle than SAML). For Microsoft Entra ID specifically, prefer One-click Microsoft, which produces exactly this kind of connection without anyone copying values by hand.

What you provide

  • oidc_issuer — the issuer URL (https). Authio appends /.well-known/openid-configuration and runs discovery to find the authorization, token, and JWKS endpoints.
  • oidc_client_id — the client id of the application the IdP admin registered for Authio.
  • oidc_client_secret — the client secret. Authio seals it with envelope encryption and only opens it at sign-in.
  • oidc_scopes — optional; defaults to openid email profile.

What the IdP admin copies back: the callback URL

The only value that flows the other direction is Authio’s redirect / callback URL, which the admin registers on the IdP application. It is per-connection:

https://sso.authio.com/v1/sso/connections/{connection_id}/callback

where {connection_id} is the sso_… id. Authio shows this exact URL inline (with a copy button) when you create the connection, so there’s no chicken-and-egg: the draft connection is minted first, then you hand the callback URL to the IdP.

What Authio does at sign-in

  • Builds the authorization request with response_type=code, the connection’s scopes, a state, a nonce, and a PKCE code_challenge (S256).
  • Exchanges the code at the token endpoint (client_secret_post + the PKCE code_verifier).
  • Validates the id_token against the IdP’s JWKS — issuer, audience (must contain the client id), nonce, and expiry — and resolves the email from email, preferred_username, or upn.
  • Mints an Authio session and redirects to your app’s redirect_uri (subject to the same RelayState host allow-list described on the SP-initiated login URL page).
The Lobby is protocol-aware. Both SAML and OIDC connections share the same initiate URL — /v1/sso/connections/{id}/initiate — and the SSO service dispatches on the stored protocol. An org can hold one OIDC and one SAML connection at once.

Creating one

Connections are created the same three ways as any SSO connection (see the overview): the org Features → Single Sign-On section in your dashboard, a one-time SSO Setup Portal link, or the embedded SSO Connection widget. In each, choose OIDC, paste issuer / client id / client secret, hand the displayed callback URL to the IdP, and save. The connection flips to active once the IdP side is wired up.

Related