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 can also start at your IdP. Clicking Shorebird’s app tile in your IdP’s dashboard, such as the Okta dashboard, signs the member in and opens the console, the same as Continue with SSO. The exception: if several of your domains’ connections use the same IdP entity ID, sign-in must start at Shorebird, because Shorebird can’t tell which domain the tile is for.
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. To have your IdP add and deactivate people, set up SCIM provisioning.
An existing account moves onto SSO. The first time someone with a Shorebird account at your domain signs in with SSO, their Google or Microsoft sign-in is replaced and their other sessions are signed out. Their organizations, app access, and billing carry over. For other sign-in changes, see Account access and ownership.

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.

Once SSO works, you can make it the only way in. Until then, people at your domain can still sign in with Google or Microsoft. A domain’s requirement can also be Google or Microsoft rather than SSO, so this works without a SAML connection too.

You need the Owner enterprise role. Admins see the setting but can’t change it.

In the Shorebird Console, open Enterprise in the sidebar, then its Security tab.
In the Sign-in method card for the domain, choose SAML SSO only, Google only or Microsoft only. A method can be chosen only after someone at the domain has signed in with it, so a misconfigured method can’t lock everyone out; until then the card says Not available until someone tests it. SAML SSO only appears once Shorebird has enabled your SAML connection.
Click Require SAML SSO (or Require Google or Require Microsoft), type the domain to confirm, and click Require.

From then on, everyone with an email address at that domain signs in that way. Google and Microsoft requirements accept only an account your company manages, a Google Workspace account or a work Microsoft account, not a personal account registered with a work address. Someone who tries another way is sent to your IdP, for SAML, or sees, for a Microsoft requirement:

Sign in with Microsoft
Your organization requires signing in with the Microsoft account it manages for this email address.

Sessions opened another way before the change end within 15 minutes. API keys, service account keys and CI sign-ins keep working. Each change is recorded in the enterprise’s audit log as enterprise_domain.sign_in_method_update.

To lift the requirement, choose Any method and click Allow any method.

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. A response signed or digested with SHA-1 is also rejected, so configure your IdP to sign with RSA-SHA256 and digest with SHA-256.
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.