Authdog
Identity guide

Authentication & SSO

Enterprise single sign-on lets users authenticate through their organization's identity provider while your application consumes one Authdog session model. Authdog supports SAML 2.0 and OpenID Connect (OIDC), multiple enterprise connections in an environment, and email-domain discovery. Use this guide to configure a connection, test it safely, and integrate it with user 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 X.509 signing certificate, or IdP metadata URL/XML.
  • For OIDC: the discovery document URL, client ID, and client secret.
  • The customer's approved email domains.
  • A backend that validates the resulting Authdog session before serving protected data.

Authdog's current provider catalog includes Okta and JumpCloud over SAML, Microsoft Entra ID and BeyondTrust over OIDC, and Ping Identity over SAML. Generic SAML 2.0 and OIDC connectors cover other compatible providers.

Implementation

1. Create the enterprise connection

In the Authdog console:

  1. Select the target project and environment.
  2. Open Authentication → Providers.
  3. Filter to Enterprise.
  4. Choose a vendor connector or generic protocol connector.
  5. Give the connection a name that identifies the customer and IdP.

Connections are scoped to the environment. Configure and test staging separately from production; do not reuse staging URLs or credentials in production.

2. Exchange protocol configuration

For SAML, copy Authdog's displayed values into the IdP:

  • SP-initiated sign-in URL
  • ACS / Reply URL
  • SP Entity ID / audience
  • SP metadata XML, where the IdP supports metadata import

Then enter the IdP SSO URL and X.509 signing certificate in Authdog. Metadata can be fetched from a URL or pasted as XML. Import occurs only when an operator selects Fetch or Parse & autofill; it does not continuously refresh.

Optional SAML controls include logout, login hints, signed requests, protocol binding, and request template. Use RSA-SHA256 and SHA-256 when request signing is required. SHA-1 options exist for legacy compatibility, not as a preferred default.

For OIDC, register the exact callback URL displayed by Authdog at the IdP. Enter the connection name, discovery URL, client ID, and client secret. Use a URL that serves the expected discovery document; an issuer base URL is insufficient when it does not expose that document at the supplied location.

3. Configure domain discovery

Add one or more comma-separated entries under Email domains (for SSO discovery):

acme.com, eu.acme.com

A domain entry matches that exact domain and its subdomains. Therefore, acme.com already matches eu.acme.com. Only active enterprise connections participate in discovery.

Keep domains non-overlapping across active connections. Resolution uses the first active matching connection returned for the environment, so duplicate or parent/child overlap can produce unpredictable routing.

4. Test before rollout

Use the connection's Test action before inviting users. Test SP-initiated sign-in and a normal sign-in through the hosted Account Portal or your embedded interface using a discovery-domain address. Confirm:

  • The user reaches the intended IdP.
  • The IdP sends a stable subject and expected verified email.
  • Authdog creates or links the intended user.
  • Your backend accepts the Authdog session.
  • MFA and conditional-access rules at the IdP complete as expected.
  • Logout works if you enabled federation logout.

Authdog links identities to an existing user only through verified email. Enterprise users can otherwise be created just in time on first successful sign-in. For pre-provisioning and automated deactivation, pair SSO with User provisioning with SCIM.

5. Delegate setup when appropriate

The Admin Portal can give a verified customer administrator a short-lived, organization-scoped SSO setup flow without console access. Generate the link from your backend only after authorizing that administrator for the organization. Treat completion of the hosted flow as a setup attempt, then independently test the resulting connection.

Security considerations

  • Pin SAML trust to the certificate received through trusted metadata or secure administrator exchange.
  • Track certificate expiry and coordinate rotation before the old certificate is removed.
  • Require HTTPS for discovery, SSO, logout, metadata, and callback URLs.
  • Store OIDC client secrets only in Authdog and the IdP; never expose them to browser code.
  • Preserve a recovery sign-in path while testing policy changes to avoid operator lockout.
  • Verify customer administrators before generating self-service setup links.
  • Treat Admin Portal URLs as temporary bearer credentials and never log them.
  • Validate sessions and permissions on the backend. Reaching an SSO callback is not authorization.

Validation checklist

  • Connection is active in the intended environment.
  • IdP configuration uses 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.
  • Stable subject and verified email produce the intended Authdog user.
  • IdP MFA and conditional-access tests pass.
  • Backend rejects missing or invalid sessions.
  • Production test uses production URLs, certificate, and credentials.
  • Recovery access remains available to operators.

Troubleshooting

SAML configuration is rejected: verify that both the SSO URL and signing certificate are present. Re-import or re-parse current metadata when fields changed upstream.

OIDC callback fails: compare the IdP allowlist with the callback URL currently displayed by Authdog. A custom-domain change can change this URL.

Discovery does not select a connection: confirm connection is active and user's email domain matches a configured entry.

Wrong connection wins: remove overlapping entries. Parent domains include subdomains.

Existing user becomes duplicated: inspect whether IdP email was verified and stable. Authdog's identity linking depends on verified email.

Logout behaves differently from sign-in: federation logout is optional and must be configured and tested separately.

Next steps