Skip to main content
Video tutorial · 2:51

SSO providers

SSO providers are added on Settings → Sign-in → Add provider (owner). How sign-in, account creation, groups, sessions and sign-out behave is on Sign-in methods; this page covers setting up each provider.

Adding a provider​

  1. Pick the provider type in the catalogue. Types that offer both OpenID Connect and SAML 2.0 ask which one.
  2. Connection — the few values the type needs (for Keycloak: its URL and realm; for Entra ID: the tenant), the client ID and secret, a name and a slug. The slug is part of every address registered at the provider and cannot change later.
  3. Register CertAutoPilot at the provider — the card on the right shows the addresses to copy (built from the public URL) and the steps for that provider:
    • OIDC and GitHub: the redirect URI …/api/v1/auth/sso/<slug>/callback, and for providers with sign-out the post-logout address <public URL>/login;
    • SAML: the entity ID …/api/v1/auth/sso/<slug>/metadata (also the address of the service-provider metadata, which can be downloaded), the ACS URL …/acs, and the single logout URL …/slo.
  4. Test connection reads the provider's discovery document or metadata and checks it (for a saved provider the result is shown in the providers list's Status column).
  5. Save, then Test sign-in, then turn Enabled on.

Everything else — endpoints, signing algorithms, IdP certificates — comes from discovery (OIDC) or metadata (SAML). The Advanced section holds the rest: scopes, client authentication, allowed signing algorithms, a CA certificate for a privately signed provider, the claims for username / e-mail / display name, and the SAML options below. Extra authorization-request parameters can be set through the API only (extra_auth_params); saving the form keeps them. Parameters the flow sets itself (state, nonce, redirect_uri, …) and response_mode, request, request_uri and max_age are refused — they would change how the answer comes back; use prompt=login for a fresh sign-in. Reading UserInfo needs a plain JSON answer: turn off signed UserInfo responses at the provider.

The catalogue​

"Lab-verified" means proven against a real installation in CertAutoPilot's test lab. The other types follow the vendor's documentation and are covered by tests against recorded documents, but have not been run against a real tenant.

TypeProtocolsYou enterStable identityGroupsLab-verified
Microsoft Entra IDOIDC, SAMLOIDC: tenant ID or domain. SAML: the App Federation Metadata URL from the portalOIDC: tenant + object ID (tid, oid). SAML: the objectidentifier attributeGroup object IDs; overage leaves memberships unchangedNo
GoogleOIDC—subNoneNo
Google WorkspaceOIDC, SAMLOIDC: your Workspace domains (required). SAML: the metadata filesub / persistent NameIDOIDC: none. SAML: group membership attributeNo
OktaOIDC, SAMLOIDC: the issuer (org or custom authorization server). SAML: the metadata URLsub / the cap_user_id attribute (Okta user.id)groups claim / attributeNo
KeycloakOIDC, SAMLKeycloak URL, realmsub / persistent NameIDgroups (group mapper)Yes (OIDC and SAML)
AD FSOIDC, SAMLAD FS hostsub / persistent NameID (for example from objectGUID)group claim / Group attributeYes (OIDC and SAML)
Auth0OIDC, SAMLDomain (SAML also the application client ID)sub / NameID (Auth0 user_id)Only through a custom claim (Auth0 Action)No
OneLoginOIDC, SAMLOIDC: subdomain. SAML: the metadata URLsub / NameIDgroups (OIDC)No
PingOneOIDC, SAMLOIDC: region, environment ID. SAML: the metadata URLsub / NameIDgroups (OIDC)No
PingFederateOIDC, SAMLOIDC: base URL. SAML: the metadata URLsub / NameIDAttribute contractNo
GitHubOAuth 2.0Host (empty = github.com; or a GitHub Enterprise Server host); allowed organizationsThe numeric user IDTeams as org/team-slug (optional)Against a test double only
Custom OIDCOIDCThe issuersub (configurable)Configurable claim—
Custom SAML 2.0SAMLMetadata URL, a metadata file, or entity ID + sign-on URL + certificate by handPersistent NameID (or a configured attribute)Configurable attribute—

The stable identity is what ties a CertAutoPilot account to the provider. It is always an identifier the provider never reassigns — never an e-mail address or a name, which can change and be reused. For a custom provider, CertAutoPilot refuses to use an e-mail, preferred_username, name or upn claim as the identity. Numeric identity claims keep every digit.

Verified e-mail. Allowed e-mail domains and the link of a moved account need a verified address: for OIDC the email_verified claim (Entra ID: xms_edov; AD FS: the directory's address counts), for SAML the address of an identity provider your organization runs (Auth0, which anyone can join, needs an email_verified attribute).

Provider notes​

  • Microsoft Entra ID. The organizations / common tenants accept any work account, so they require a list of allowed tenant IDs. Personal Microsoft accounts (consumers, or their tenant 9188040d-6c67-4c5b-b112-36a304b66dad) are refused. Entra sends no email_verified: an address counts as verified only with the optional claim xms_edov (Token configuration → Add optional claim → ID → xms_edov), which allowed e-mail domains need. preferred_username and email can change; the account is tied to tenant and object ID. Group overage (more than 200 groups in a token, 150 in a SAML assertion) leaves memberships unchanged — CertAutoPilot does not query Microsoft Graph.
  • Google. Any Google account can authenticate, so automatic account creation needs allowed e-mail domains. Google has no sign-out endpoint.
  • Google Workspace. OIDC checks the hd claim against your listed domains (the domain sent in the request is only a hint). Google's SAML NameID is the primary e-mail address, which changes when the account is renamed — prefer OIDC for Workspace. Google Workspace SAML has no single logout.
  • Okta. Use the issuer of the authorization server the application uses. For SAML, send cap_user_id = user.id as an attribute statement: it is the identity.
  • Keycloak. Set the client's PKCE method to S256. For SAML, import the service-provider metadata as a client, set Name ID format persistent with Force name ID format on, and add mappers for username, email and a group list named groups. Keycloak requires signed requests from an imported client by default: turn Sign authentication requests on in CertAutoPilot, or turn Client signature required off in Keycloak.
  • AD FS. AD FS issues the address from Active Directory and sends no email_verified; an address it sends counts as verified. Add the relying party trust from the service-provider metadata (it then also has the logout endpoint and the request-signing certificate; no encryption certificate is offered, so AD FS does not encrypt), send an unchanging value such as objectGUID as a persistent NameID, and use SHA-256. A user in a single group gets the group claim as one value; both forms are read.
  • Auth0. Anyone can sign up at a database or social connection, so Auth0 is treated as open for both protocols (automatic account creation needs a restriction). For SAML, add the mapping "email_verified": "email_verified" in the add-on's settings: without it no address counts as verified, and allowed e-mail domains refuse everyone. The issuer ends with a slash. Auth0's SAML add-on signs with SHA-1 by default, which CertAutoPilot refuses: set signatureAlgorithm: rsa-sha256 and digestAlgorithm: sha256. Groups exist only if an Action adds a custom claim.
  • OneLogin. OneLogin does not send email_verified by default; allowed e-mail domains need it.
  • PingFederate. Its discovery document lists the none algorithm; CertAutoPilot never accepts it.
  • PingOne. PingOne's documentation ties PKCE to token authentication none; a confidential client with PKCE has not been verified in a lab.
  • GitHub. There is no ID token: the identity comes from the GitHub API (/user), the e-mail from the primary verified address. Automatic account creation needs a restriction — allowed organizations (membership must be active; pending, hidden or unapproved counts as not a member) or allowed e-mail domains (the primary verified address). If the organization restricts OAuth app access, approve the app; members of an organization that enforces SAML single sign-on need an active SSO session when they approve it. With allowed organizations, only teams of those organizations become groups. A GitHub App (rather than an OAuth App) needs the Email addresses permission for the e-mail and Members for teams; without them the user signs in with no e-mail and the group memberships are left unchanged. GitHub Enterprise Server has no PKCE, so there the flow relies on the state and the client secret. GitHub has no sign-out endpoint.

What is checked​

OpenID Connect

  • The discovery document is read over https with no redirects, size-limited, through the outbound policy (private addresses allowed — on-premises providers live there — but link-local, cloud-metadata and DNS-rebinding addresses refused). An optional CA certificate is added to the system roots. It is re-read every 24 hours; a failed re-read keeps the last good copy.
  • The issuer must match exactly (a trailing slash counts). For Entra ID organizations / common, the token's issuer must be the tenant's own and the tenant must be allowed.
  • ID-token signatures are checked against the provider's keys. Only RSA, ECDSA, RSA-PSS and EdDSA algorithms are accepted — never none or HMAC, whatever the provider lists. Keys are re-fetched when an unknown key ID appears, at most once every 30 seconds.
  • Audience, expiry, state, PKCE and nonce are checked; a token for several audiences must name this client as azp. A state is used once and expires after 10 minutes. A failed re-read of the discovery document keeps the last good one and is retried after 5 minutes.

SAML 2.0

  • Responses larger than 512 KB, with a DOCTYPE, with more than one assertion or more than one SubjectConfirmation, or signed with SHA-1 are refused. A refusal the identity provider sends itself (status other than Success) is shown with its status and message. The clock skew also covers the bearer window (SubjectConfirmationData NotOnOrAfter).
  • The assertion must be signed with one of the provider's signing certificates (a signed response with an unsigned assertion is accepted only with Accept a response whose assertion is not signed itself).
  • Encrypted assertions are not supported: a response with an encrypted assertion is refused with "turn assertion encryption off at the identity provider" (TLS protects the response). The service-provider metadata therefore offers no encryption key, so an identity provider that imports it does not start encrypting.
  • Issuer, Destination (required), Recipient, InResponseTo (on the response and the subject confirmation), Audience (required: every audience restriction must name our entity ID) and the time window (with the clock skew, default 120 seconds, at most 300) are checked. Every assertion is accepted once (replay is refused). NotBefore is optional; NotOnOrAfter is required.
  • A transient NameID is refused as the identity, and an e-mail NameID only with Accept an e-mail address as NameID (refused altogether for open providers such as Auth0, where anyone can sign up with any address) (warned: it changes when the address changes). A NameID that holds an address counts as an e-mail NameID whatever its format says unless it is persistent (Okta's and Google's default is unspecified with the address).
  • IdP-initiated sign-in (default off): an unsolicited response is accepted only with Accept IdP-initiated sign-in on, at most 5 minutes old, and once. It allows login CSRF — a link can sign a browser into the attacker's account — so keep it off unless your users start from the provider's app portal.

GitHub — the token is exchanged with the client secret; the user, e-mails, organization memberships and (optionally) teams are read from the GitHub API.

Every call to a provider times out after 10 seconds and never follows a redirect. When the token request fails, only the HTTP status and the OAuth error fields are kept (in the audit log and the test sign-in result) — never the response body.

Test connection and test sign-in​

  • Test connection fetches and checks the discovery document (OIDC: the endpoints and signing algorithms found are shown) or the metadata (SAML: an unusable document or certificate is reported as the error; the IdP certificates and their expiry are shown on the saved provider). On a saved SAML provider with a metadata URL it also takes over what the identity provider publishes now — after the IdP switched its signing key, run it to apply the new certificate at once. For GitHub it checks the configuration.

  • Test sign-in (saved provider) runs a real sign-in at the provider as you — it works while the provider is still disabled — and comes back to the form with:

    • the identity (the value to give when moving an account to this provider), username, e-mail and groups,
    • every claim or attribute the provider sent,
    • and what a real sign-in would do: create an account, sign in to an existing one, link a waiting account (same username and the account's verified e-mail), or be refused (with the reason).

    Open the settings at the public URL to run it: the provider returns there, and the browser's sign-in cookie is kept per address, so a test started at another address (an IP, a NodePort, an alias) is refused with the address to use.

    No account, identity or session is created. When the provider refuses or its answer does not verify (a wrong secret, signature or redirect address), the form shows The sign-in did not complete with the reason. Results are kept for 10 minutes and only you can read them.

SAML metadata and certificates​

  • Metadata comes from a URL (fetched like an OIDC discovery document, at most 2 MB; a query string such as Entra ID's ?appid= or PingFederate's ?PartnerSpId= is kept), an uploaded file, or entity ID + sign-on URL + certificate (+ optional single logout URL) by hand. A provider from a file keeps the single logout service the file named when it is saved again. CertAutoPilot uses the HTTP-Redirect single sign-on service (a provider offering only HTTP-POST is refused), the HTTP-Redirect single logout service if present, and every signing certificate. Both services must be https.
  • Saving a provider whose metadata URL did not change keeps the stored values (no fetch), so it can be edited or disabled while the identity provider is down. A provider set up from a metadata URL re-reads it at sign-in when it is more than 24 hours old (or at once with Test connection): certificates the provider now publishes replace the stored ones. A rollover where the IdP publishes the new certificate a day ahead needs no change here; an immediate switch at the IdP fails sign-ins until Test connection (or the daily re-read). A failed re-read keeps the stored values and shows the error. Providers set up from a file or by hand keep their certificates until you update them.
  • Service-provider key. Every SAML provider gets its own RSA key and self-signed certificate, used to sign requests (optional for sign-in, always for sign-out). The private key is encrypted under your KEK. To rotate it (save other changes first): Prepare a new certificate (published in the metadata beside the current one) → update the provider → Switch to the new certificate (the new one becomes current, the old one is dropped).

API​

The provider routes are under /api/v1/settings/sign-in/… (owner), and the browser-facing sign-in routes under /api/v1/auth/sso/<slug>/… (public, rate-limited). See the API reference.

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Two-Factor Authentication and Single Sign-On with Keycloak (OIDC)YouTube ↗