# Set up SSO with Okta

This page covers the Okta half of an SSO connection. The Bird half (verifying a domain, testing, activating, and requiring SSO) is the same for every provider and lives on [SSO and provisioning](/docs/knowledge-base/account-security/sso).

Okta and Bird each need values from the other, so where you start depends on the protocol. Keep both open as you work.

## SAML

Start in Bird for SAML. A SAML connection's Entity ID and Assertion Consumer Service URL derive from the connection itself, so create it with **I have not set up my provider yet**, register the values it then shows, and come back to **Supply the details**. [Setting up SAML without placeholder values](/docs/knowledge-base/account-security/sso) walks through that flow.

Okta's field names do not match Bird's. Two of them are close enough to swap by mistake, and swapping them sends the sign-in response to a URL that cannot consume it.

| In Bird, under **Register these with your identity provider** | In Okta                                             |
| ------------------------------------------------------------- | --------------------------------------------------- |
| Assertion Consumer Service URL                                | Single sign-on URL                                  |
| Entity ID                                                     | Audience URI (SP Entity ID)                         |
| Sign-in URL for this connection                               | Not an Okta field. Give it to members as a bookmark |

Okta's **Single sign-on URL** is Bird's Assertion Consumer Service URL, not Bird's sign-in URL. If you paste the sign-in URL there, Okta posts each response to the wrong endpoint and the sign-in fails.

### Identify members by their email address

In the SAML app's **Name ID format**, choose `EmailAddress` and set **Application username** to the value you want Bird to key each account on. Bird refuses `Unspecified`, and refuses a response whose NameID format does not match the format the connection expects.

Read [How members are identified](/docs/knowledge-base/account-security/sso) before you decide: the identifier is permanent for anyone who signs in through the connection, so an opaque application username with the address sent separately as an `email` attribute is the stronger choice.

### Assertion validity

Okta signs assertions valid from five minutes before issue to five minutes after. Bird accepts that window. Nothing to configure.

## OIDC

Start in Okta for OIDC. Bird needs the issuer, client ID and client secret to create an OIDC connection, so register the application at Okta first. Bird's **Redirect URI** is the same for every connection and is shown in **Add connection** before you create anything, so you can register it up front.

Create an OIDC web application in Okta and copy its client ID and secret into Bird, with Okta's issuer as the **Issuer**. Bird authenticates to the token endpoint with `client_secret_basic`.

Register Bird's **Redirect URI** as the app's sign-in redirect URI.

### Okta's app tile

To let members start from their Okta dashboard, set:

- **Login initiated by**: Either Okta or App
- **Application visibility**: the tile shown to users
- **Login flow**: Redirect to app to initiate login (OIDC Compliant)
- **Initiate login URI**: the connection's Initiate login URI from Bird

Choose the OIDC-compliant flow. Okta's **Send ID Token directly to app (Okta Simplified)** flow posts a token to Bird rather than redirecting, and Bird does not accept it.

## Assign the application

A member who is not assigned to the Bird application in Okta is refused by Okta, not by Bird. Bird reports the refusal as coming from your identity provider, so check assignments and any conditional-access policy in Okta before re-checking the connection's own settings.

## Rotate the signing certificate

Rotate in Okta first, then in Bird. Bird verifies against the certificates the connection holds, so a Bird connection carrying only the new certificate while Okta still signs with the old one refuses every sign-in until Okta activates the new one. The refusal is a signature error and clears as soon as the two agree.

## Next steps

- [SSO and provisioning](/docs/knowledge-base/account-security/sso): verify a domain, test the connection, and require SSO
- [Set up SSO with Google Workspace](/docs/knowledge-base/account-security/sso-google-workspace)
- [Set up SSO with Microsoft Entra ID](/docs/knowledge-base/account-security/sso-microsoft-entra-id)

## Related resources

- [Should I use an API key or an OAuth token, and how do I rotate one?](/explained/platform/api-key-or-oauth-token-and-how-do-i-rotate-one) (answer)
- [Authentication & API keys](/docs/guides/authentication) (docs)

[Get an implementation brief](/learn/workspace?topic=account-access)