Single Sign-On

Single sign-on (SSO) lets your team sign in to Breakwater through your own identity provider: Okta, Microsoft Entra ID, Google Workspace, or any provider that speaks OpenID Connect or SAML 2.0. New teammates can be added automatically the first time they sign in, and people you remove from your identity provider lose access when their Breakwater session runs out, or at once with SCIM provisioning.

Only owners can set up and change single sign-on.

Setting it up

Go to Settings in the vendor portal and choose Set up under Single sign-on.
Pick OpenID Connect or SAML.
- OpenID Connect: create an app in your provider (a "web" app using the authorization code flow), set its redirect URI to the one Breakwater shows you, and enter the provider's issuer URL, client ID and client secret.
- SAML: create a SAML app in your provider with Breakwater's ACS URL and entity ID, then give Breakwater your provider's metadata URL or paste its metadata XML. Send a persistent or email-format NameID, and sign the response or the assertion. If the NameID isn't an email address, send the email in an email attribute (or set the attribute name).
Choose who gets in (below), and save.
Choose Test connection and sign in at your provider. The test signs nobody in and changes nothing. It shows what your provider sent and what would happen on a real sign-in.
Choose Turn on single sign-on.

Your team signs in from the link on the settings page (/sso/<your-company-id>), or by choosing Sign in with SSO on the vendor login page and entering your company ID.

Who gets in

Add people automatically on their first sign-in. When this is on, anyone your provider signs in with a verified email at one of your allowed domains joins your team at the role for new people: viewer or member. Owners change roles on the Team page as usual. When it's off, only people already on your team can sign in through your provider; everyone else needs an invitation.
Allowed email domains. You can list a domain once an owner or admin of your team has an email address there. Personal email providers (gmail.com, outlook.com and the like) can't be listed.
People who already have a Breakwater account link it the first time they sign in through your provider, by entering its password (and their two-factor code, if they use one). Someone whose account signs in with Google or GitHub and has no password confirms with that account instead. After that, your provider signs them straight in.

Requiring single sign-on

Turn on Require single sign-on to make everyone except owners sign in through your provider. Signing in with Google or GitHub doesn't count: your team still goes through your provider. Owners can still sign in with their password and two-factor authentication, so a provider outage can't lock your team out. You need two-factor authentication on your own account to turn this on.

A sign-in through your provider counts as two-factor authentication if you also require two-factor: your provider is responsible for the second factor.

Accepting an invitation with SSO

When single sign-on is on, invitations to your team offer Accept with SSO: the person signs in to your provider as the invited address, and joins without making a Breakwater password. Someone who already has a Breakwater account enters its password once to link it. They can still accept with a password instead.

SCIM provisioning

With SCIM, your identity provider tells Breakwater when people join and leave.

Assigning someone to Breakwater in your provider sends them an invitation at the role for new people. It shows on the Team page as from your identity provider, and doesn't expire. They accept it by signing in through your provider.
Deactivating or removing someone in your provider takes them off your team at once, as removing them on the Team page does: their Breakwater account and anything else they belong to stay. Their open invitations are cancelled, and while your provider has them deactivated they can't get back in through single sign-on or an invitation.
Reactivating someone sends them a new invitation. They come back at the role for new people.

SCIM never adds anyone to your team by itself: everyone accepts an invitation (or, with automatic adding on, signs in). Roles stay on the Team page unless you use roles from groups.

Turning it on

Set up single sign-on first (it doesn't have to be on).
On the Single sign-on settings page, under SCIM provisioning, choose whether to email invitations, then choose Turn on SCIM. With emails off, invitations wait on the Team page and people accept them by signing in at your team's sign-in link; someone without a Breakwater account then needs a verified email at one of your allowed domains.
Copy the SCIM base URL and the token into your provider. The token is shown once; Regenerate token makes a new one.
- Okta: in the app's Provisioning tab, choose SCIM 2.0, enter the base URL, use the "HTTP Header" authentication mode with the token, and enable Create Users, Update User Attributes and Deactivate Users. The unique identifier is userName (the email).
- Microsoft Entra ID: in the enterprise app's Provisioning, choose Automatic, enter the base URL as the tenant URL and the token as the secret token, and test the connection.

The first sync invites everyone assigned to Breakwater in your provider at once, so you might turn off the invitation emails until it's done.

If your provider deactivates the last owner of your team, Breakwater refuses with " is the last owner of . Add another owner in Breakwater first." and changes nothing; your provider shows the error until another owner is added.

Turn off SCIM stops the token working, cancels open invitations from your provider, and forgets who it had deactivated. Nobody is removed from the team.

Roles from groups

Your identity provider's groups can decide your team's roles. Map a group to viewer, member or admin under Roles from groups on the Single sign-on settings page, then turn it on.

Someone in several mapped groups gets the highest of their roles. Someone in no mapped group gets the role for new people.
Owners are never changed by groups. Make someone an owner on the Team page; groups stop setting their role. Owners stay hand-picked so a mistake in your provider can't lock you out.
While groups decide someone's role, the Team page shows it as Set by identity provider and it can't be changed there, except to make them an owner.
Groups never add or remove anyone from your team; they only set roles.
Turning roles from groups off leaves everyone's role as it is, and you manage roles on the Team page again.

Groups can reach Breakwater two ways. If you use both, SCIM groups win and sign-in groups aren't used.

From SCIM

With SCIM provisioning on, your provider can push groups and their members. Roles change as soon as it does.

Okta: in the app's Push Groups tab, push the groups you want to use. Assigning people to the app and pushing groups are separate steps.
Microsoft Entra ID: assign the groups to the enterprise app; provisioning sends them and their members.

The groups appear on the settings page; choose a role for each, then Turn on under From SCIM. Pending invitations from your provider follow the groups too.

Without SCIM, your provider can send each person's groups when they sign in. A role changes at the person's next sign-in through your provider; changing a mapping applies at once to everyone who has signed in since you turned this on. Use Test connection to see the groups your provider sends.

Okta (OpenID Connect): add a groups claim to the ID token with a filter for the groups you want (or "Matches regex" .*). Breakwater asks for the groups scope when your authorization server offers it. Okta (SAML): add a group attribute statement named groups.
Microsoft Entra ID: under Token configuration (OpenID Connect) or Attributes & Claims (SAML), add a group claim and choose Groups assigned to the application. Entra sends group object IDs: map those, or configure it to send names. If someone is in too many groups, Entra leaves the claim out and Breakwater refuses their sign-in rather than guessing; sending only the groups assigned to the application avoids this.
Google Workspace (SAML): add a Group membership mapping named groups in the app's attribute mapping, with the groups to send (up to 75). Google sends group names, including groups someone belongs to through another group; if you rename a group in Google, update its mapping here. Google's OpenID Connect doesn't send groups.

The claim (or SAML attribute) is called groups unless you change it. Group values must match exactly, including case. Changing the claim name clears the groups Breakwater has recorded, so people whose role comes from sign-in groups get the role for new people until they next sign in.

Removing someone

Remove them in your identity provider. With SCIM provisioning on, that takes them off your team at once. Without it, they lose access to Breakwater when their session runs out, at the length you set under Sign in again after (8 hours unless you change it). Removing someone only on the Team page isn't enough while they're still in your provider and automatic adding is on: they'd be added again on their next sign-in.

Removing someone doesn't revoke vendor auth tokens (vtok_...). They're shared team credentials; rotate any the person had access to.

Changing settings

Changing any connection setting (issuer, client ID or secret, SAML certificate or URLs) turns single sign-on off until you test again. Owners can still sign in with a password meanwhile.
Changing the provider itself (protocol, issuer, client ID or SAML entity ID) unlinks everyone. Each person links again, or is added again, on their next sign-in.
Turn off or Delete connection ends everyone's single sign-on sessions at once; they sign in with a password from then on.

Every change, test and sign-in through your provider is recorded in your audit log.