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.

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

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 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.

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.

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 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.

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

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.

To let members start from their Okta dashboard, set:

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.

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 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.