SAML Single Sign-On

Shorebird supports SAML 2.0 single sign-on (SSO) for teams on the Enterprise plan. Members sign in to the Shorebird Console through your identity provider (IdP) instead of a personal Google or Microsoft account.

SAML is not self-serve yet. The Shorebird team creates the connection for you: send what is described below to contact@shorebird.dev, and Shorebird will activate SSO for your email domain and confirm when it is live.

A SAML connection is keyed to an email domain, such as acme.com:

A member opens the Shorebird Console and clicks Continue with SSO.
They enter their work email address. The domain selects your connection, and they are redirected to your IdP.
After authenticating, the IdP posts a signed assertion back to Shorebird, which signs the member in.

A few consequences of this design are worth knowing before you start:

Sign-in must start at Shorebird. IdP-initiated sign-in, such as clicking the app tile in the Okta dashboard, is not supported.
One connection per email domain. The email address in the assertion must be at the connection’s domain, or sign-in is rejected. If your team uses several domains, send a metadata URL for each one and Shorebird will create a connection per domain.
SSO covers authentication only. Assigning the app to a user in your IdP does not add them to your Shorebird organization. Membership and roles are still managed in organization settings, as described in Organizations.

What to send Shorebird

Two things:

Your IdP metadata URL. In Okta, this is the Identity Provider metadata link on the application’s Sign On tab. The document behind that link already holds the entity ID, the SSO URL, and the signing certificate, and Shorebird reads all three from it directly.
Your email domain, such as acme.com. This is what routes a member’s sign-in to your IdP, and it is the one value the metadata does not contain.

If your IdP publishes no metadata URL

Some providers, Google Workspace among them, offer metadata only as a download. Send the XML file itself, or pull these three values out of it and send those instead:

Value	Where to find it (Okta example)	Example
IdP Entity ID	“Identity Provider Issuer” in the SAML setup instructions	`http://www.okta.com/exk1a2b3c4EXAMPLE`
IdP SSO URL	“Identity Provider Single Sign-On URL”	`https://acme.okta.com/app/acme_shorebird_1/exk1a2b3c4EXAMPLE/sso/saml`
IdP signing certificate	The “X.509 Certificate”, as PEM text	`-----BEGIN CERTIFICATE-----` …

None of the three is optional. The certificate in particular is what Shorebird uses to verify that an assertion really came from your IdP, so send it as PEM text, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

Settings to use in your identity provider

Configure the application in your IdP with these values:

Setting	Value
Single sign-on URL (ACS URL)	`https://auth.shorebird.dev/auth/saml/callback`
Audience URI (SP Entity ID)	`https://auth.shorebird.dev`
Name ID format	`EmailAddress`
Application username	`Email`
Default RelayState	Leave empty
Assertion encryption	Off
Signed authentication requests	Not used, and must not be required

Shorebird does not decrypt assertions, so assertion encryption must stay off, and it does not sign its authentication requests, so the application must not require signed requests.

The email address is the identity

Shorebird identifies a member by email address, read from an attribute named email (or mail, or the OID urn:oid:0.9.2342.19200300.100.1.3), from Entra ID’s default emailaddress claim, or from an EmailAddress or Unspecified Name ID. A Persistent or Transient Name ID is opaque and is never read as an email address, so an IdP configured that way must also send the attribute:

Name	Name format	Value
`email`	Unspecified	`user.email`

Setting up in Okta

In the Okta Admin Console, go to Applications → Applications → Create App Integration, choose SAML 2.0, and click Next. Okta documents this flow in Create SAML app integrations.
Name the app (for example, “Shorebird”) and click Next.
On the Configure SAML screen, fill in the single sign-on URL, audience URI, Name ID format, and application username from Settings to use in your identity provider.
Under Attribute Statements, add the email attribute described above.
Click Next, answer the feedback questions, and click Finish.
On the app’s Sign On tab, copy the Identity Provider metadata link. View SAML setup instructions, on the same tab, shows the issuer, SSO URL, and certificate individually if you ever need them.
Assign the app to the users and groups who should have access to Shorebird.
Email the metadata URL and your email domain, as described in What to send Shorebird, to contact@shorebird.dev.

For background on how the pieces fit together, see Okta’s SAML overview and About single sign-on.

Other SAML 2.0 providers, such as Microsoft Entra ID, Google Workspace, OneLogin, and JumpCloud, work the same way. The field names differ, but the metadata document and the settings Shorebird needs are the same.

After activation

Once Shorebird enables the connection, sign in with a single account first to confirm the setup, then roll the app out to the rest of the team.

Service provider metadata for an active connection is served at https://auth.shorebird.dev/auth/saml/metadata/<your-domain>. Importing that document into your IdP is a quick way to confirm that the ACS URL and entity ID match on both sides.

Rotating the signing certificate

Shorebird does not re-read your metadata on its own. Every certificate it listed when Shorebird last read it is accepted, so a rotation your IdP announced there in advance needs nothing from you; a certificate generated since does. Email contact@shorebird.dev before the old one expires, and Shorebird will re-read your metadata URL. If your connection was created from values sent by hand, send the new certificate as PEM text instead, and the old one too if it is still in use. A certificate Shorebird has never seen breaks sign-in for everyone on the domain the moment your IdP starts signing with it.

Troubleshooting

Message	Likely cause
“No SSO configured for this domain”	The connection has not been created or enabled yet, or the address entered is at a different domain than the one that was registered.
“SSO login failed”	The assertion was rejected. The most common causes are a signing certificate Shorebird has not seen, an asserted email address at a domain other than the connection’s, or no email address anywhere Shorebird reads it from.
Sign-in succeeds, but no apps are visible	Authentication worked, but the account is not a member of the organization yet. Invite the member from organization settings.

Assertions are accepted for up to one hour after they are issued, with a minute of tolerance for clock differences, and each one can be used only once. If sign-in fails only for some members, check that the IdP host’s clock is accurate.

Anything else, or a provider not covered here, is worth an email to contact@shorebird.dev.