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](https://console.authdog.com), 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

1. In the Okta admin dashboard, open **Applications > Applications** and click **Create App Integration**.
2. Choose **SAML 2.0**.
3. Set the **Single sign-on URL** to the ACS URL from Authdog and the **Audience URI** to the SP Entity ID.
4. 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.
5. 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

1. 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.
2. 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:

1. If the connection has a metadata URL, click **Rotate certificate** — Authdog re-fetches the metadata and stores the new certificate.
2. 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](/docs/sso) | Understand the SSO model and discovery |
| [SCIM provisioning](/docs/concepts/provisioning) | Sync Okta users and groups over SCIM |
| [Audit logs](/docs/audit-logs) | Find the rotation and sign-in events |