Authdog

Identity guide

Authentication & SSO

Enterprise single sign-on lets users sign in through their organization's identity provider while your app consumes one consistent Authdog session. This guide configures a SAML or OIDC connection, tests it safely, and wires it into lifecycle and authorization.

Prerequisites

  • An Authdog project and target environment.
  • Administrator access to the Authdog console and the customer's IdP.
  • A non-production customer organization and test user.
  • For SAML: the IdP SSO URL and signing certificate, or a metadata URL/XML.
  • For OIDC: the discovery document URL, client ID, and client secret.
  • The customer's approved email domains.

Authdog's current catalog includes Okta and JumpCloud over SAML, Microsoft Entra ID and BeyondTrust over OIDC, and Ping Identity over SAML, plus generic SAML and OIDC connectors for everything else.

Implementation

1. Create the enterprise connection

In Authentication → Providers, filter to Enterprise, choose a vendor or generic connector, and name it after the customer and IdP. Connections are scoped to the environment, never reuse staging URLs or credentials in production.

2. Exchange protocol configuration

For SAML, copy Authdog's SP-initiated sign-in URL, ACS URL, and entity ID into the IdP, then paste the IdP's SSO URL and certificate back into Authdog (via metadata URL, XML, or manual entry). Re-fetch metadata before the upstream certificate expires, it doesn't auto-refresh. For OIDC, register the exact callback URL Authdog displays, then enter the discovery URL, client ID, and client secret.

3. Configure domain discovery

Add comma-separated email domains under Email domains (for SSO discovery). A domain entry matches that domain and its subdomains, so keep domains non-overlapping across active connections, resolution uses the first match and duplicates route unpredictably.

4. Test before rollout

Use the connection's Test action, then sign in through the hosted portal with a discovery-domain address. Confirm the user reaches the right IdP, gets a stable subject and verified email, and your backend accepts the session. Authdog links identities to an existing user only through verified email.

5. Delegate setup when appropriate

The Admin Portal can give a verified customer administrator a short-lived, organization-scoped setup link without console access. Generate it from your backend only after authorizing that administrator, then independently test the resulting connection.

Security considerations

  • Pin SAML trust to the certificate received through trusted metadata or a secure exchange.
  • Track certificate expiry and coordinate rotation before the old one is removed.
  • Require HTTPS for discovery, SSO, logout, and callback URLs.
  • Store OIDC client secrets only in Authdog and the IdP, never in browser code.
  • Preserve a recovery sign-in path while testing policy changes.
  • Treat Admin Portal URLs as temporary bearer credentials, never 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: verify both the SSO URL and signing certificate are present; re-import metadata if fields changed upstream.

OIDC callback fails: compare the IdP allowlist with the callback URL currently shown by Authdog, a custom-domain change can silently move it.

Wrong connection wins: remove overlapping discovery domains; parent domains include subdomains.

Next steps