Authdog
Log In

Identity guide

Authentication & SSO

Your users should sign in with their company's identity provider and land in one Authdog session your app already understands.

Create the SAML or OIDC connection, prove it with one test user, then attach domain discovery so the right people are routed there. Keep a recovery sign-in until that test is boring.

Prerequisites

  • An Authdog project and the environment you are configuring. Start outside production.
  • Admin access to the Authdog console and to the customer's IdP.
  • A non-production customer organization and a test user in that IdP.
  • For SAML: the IdP SSO URL and signing certificate, or a metadata URL or XML file.
  • For OIDC: the discovery document URL, client ID, and client secret.
  • The email domains the customer has approved for this connection.

The catalog today is Okta and JumpCloud over SAML, Microsoft Entra ID and BeyondTrust over OIDC, and Ping Identity over SAML. Everyone else uses the generic SAML or OIDC connector. Pick the vendor connector when it exists. You will exchange fewer fields.

Implementation

1. Create the connection in the right environment

Open Authentication → Providers, filter to Enterprise, and choose the vendor or the generic connector. Name it after the customer and the IdP, so six months later you know which certificate you are rotating. The connection lives in this environment only. Staging URLs and staging credentials never get pasted into production.

2. Trade the protocol details, then stop and read them back

SAML. Copy Authdog's SP-initiated sign-in URL, ACS URL, and entity ID into the IdP. Paste the IdP SSO URL and signing certificate back into Authdog, from a metadata URL, XML, or the fields themselves. Metadata does not refresh itself. Re-fetch it before the upstream certificate expires, or sign-in will fail on the morning the cert dies.

OIDC. Register the callback URL Authdog is showing you, exactly, in the IdP. Then enter the discovery URL, client ID, and client secret. If you change the identity domain later, the callback moves. Update the IdP allowlist in the same change.

3. Route by email domain, without overlaps

Under Email domains (for SSO discovery), add the domains as a comma-separated list. An entry matches that domain and its subdomains. Keep domains from overlapping across active connections. Resolution takes the first match, and a duplicate will send someone to the wrong IdP with no useful error.

Test an address on the exact domain and one on a subdomain you expect to match. Test an address that should not match, and confirm it does not land on this customer's connection.

4. Test the connection before anyone else uses it

Use the connection's Test action with the assigned test user. Then sign in through the hosted portal with an address on the discovery domain. You want three things: the browser reaches the right IdP, the user comes back with a stable subject and a verified email, and your backend accepts the session. Authdog links that login to an existing user only when the email is verified. An unverified address must not merge two people.

The Admin Portal can give a verified customer administrator a short-lived, organization-scoped link, so they can finish setup without a console seat. Generate that link from your backend, after you have authorized that person. Treat the URL like a bearer credential. Do not put it in logs or chat. When they are done, run the same Test action yourself. Their word that it works is not the test.

Security considerations

  • Trust the SAML certificate you received through metadata or a channel you control. Do not accept one pasted into a ticket from an unknown sender.
  • Track certificate expiry and rotate before the old certificate is removed.
  • Require HTTPS on discovery, SSO, logout, and callback URLs.
  • Keep the OIDC client secret in Authdog and in the IdP. It does not belong in the browser.
  • Leave a recovery sign-in in place while you change federation or MFA.
  • Treat Admin Portal URLs as temporary credentials. They expire. Do not log them.

Validation checklist

  • Connection is active in the intended environment.
  • IdP configuration uses the current Authdog ACS, entity ID, or callback URL.
  • Test action completes for an assigned test user.
  • Domain discovery routes exact domains and expected subdomains correctly.
  • No active connection has an overlapping discovery domain.
  • Backend rejects missing or invalid sessions.
  • Production test uses production URLs, certificate, and credentials.

Troubleshooting

SAML configuration is rejected. The SSO URL or the signing certificate is missing. If the IdP rotated metadata, re-import it. A half-updated certificate looks like a successful save and fails at sign-in.

The OIDC callback fails. Compare the IdP allowlist with the callback URL Authdog shows right now. A custom-domain change moves that URL without telling the IdP.

The wrong connection wins. Remove overlapping discovery domains. A parent domain includes its subdomains, so two connections cannot both claim customer.com and eu.customer.com.

Next steps