Okta connects to Authdog over SAML 2.0. Okta stays the system of record for your workforce; Authdog fronts your application and consumes the assertion.
Copy the Authdog SP details
In the Authdog console, select the project and environment, open Authentication > Providers, find Okta, and click Enable. The form shows the service-provider values to paste into Okta:
| Authdog field | Where it goes in Okta |
|---|---|
| Sign-in URL (SP-initiated) | Optional, for IdP- vs SP-initiated flows |
| ACS / Reply URL | Single sign-on URL in the SAML app |
| SP Entity ID (Audience) | Audience URI (SP Entity ID) |
| SP metadata XML | Download and import where Okta accepts metadata |
Each environment has its own connection id, so its own ACS URL.
Create the SAML app in Okta
- In the Okta admin dashboard, open Applications > Applications and click Create App Integration.
- Choose SAML 2.0.
- Set the Single sign-on URL to the ACS URL from Authdog and the Audience URI to the SP Entity ID.
- Map attributes:
email,given_name/firstName,family_name/lastName. Authdog reads standard defaults; custom names can be mapped in the connection's IdP attribute mapping section. - Finish the wizard, then open the Sign On tab and copy the Identity Provider Single Sign-On URL and the X.509 signing certificate. The metadata URL under Metadata details works too.
Configure Authdog
Fastest path: paste the Okta metadata URL into Import from IdP metadata URL and click Fetch. Authdog fills the SSO URL, certificate, and entity ID for you.
| Field | Value |
|---|---|
| IdP SSO URL | Identity Provider Single Sign-On URL from Okta |
| IdP X.509 certificate | The signing certificate PEM from the Sign On tab |
| Email domains | Domains routed to this connection, e.g. acme.com |
Save, then toggle the connection active.
Test the connection
- On the saved connection, click Test connection. Authdog checks required fields, the SSO URL, and that the certificate parses as X.509. With a metadata URL set it also re-fetches the metadata and flags drift (
metadata_mismatch,certificate_mismatch). Each fault comes back with a named code and a fix. - Then run a real login: open the Sign-in URL, complete the Okta prompt, and confirm the user appears under Users with an Okta identity linked.
Rotate the certificate
Okta signing certificates rotate on a schedule you control. To roll without a support ticket:
- If the connection has a metadata URL, click Rotate certificate — Authdog re-fetches the metadata and stores the new certificate.
- Otherwise paste the new PEM from Okta into the certificate field and save.
Every rotation writes a sso_connection_certificate_rotated event to the environment audit log with the actor and the source. The old certificate is not readable afterward.
Troubleshooting
| Symptom | Cause |
|---|---|
invalid_url fault |
SSO URL is not a valid https URL |
invalid_certificate fault |
The PEM is truncated or includes the certificate chain bag — paste only the signing cert |
certificate_mismatch fault |
Okta rotated its cert; run Rotate certificate |
| User looped back to sign-in | Email domain not listed on the connection |
| Works in one environment only | Each environment has its own ACS URL to register in Okta |
Related
| Read | To learn how to |
|---|---|
| Enterprise SSO | Understand the SSO model and discovery |
| SCIM provisioning | Sync Okta users and groups over SCIM |
| Audit logs | Find the rotation and sign-in events |