Set up single sign-on (SAML and OIDC)

Single sign-on lets people sign in to Sternway through their organisation’s identity provider (IdP): Okta, Microsoft Entra ID, Google Workspace, Keycloak or anything else that speaks SAML 2.0 or OpenID Connect.

What SSO does and does not do. The IdP proves who someone is. It never unlocks their data: every member still has their own encryption password, which encrypts their vaults on their devices and never leaves them. After the IdP sign-in, the app asks for that password. Neither the team owner, the IdP nor the server can read a member’s data or reset that password; a recovery kit can.

There are two kinds:

• SAML, per team: a team owner sets it up in the desktop app. Nothing is configured on the server.
• OpenID Connect, per server: the server’s administrator sets STERNWAY_OIDC. It applies to every account on that server.

Set up SAML for a team (owner, desktop)

1. Open Settings › Account & Sync › Teams › (your team), then Single sign-on (SAML) › Set up.
2. The dialog shows what to enter at the IdP: the Entity ID, the Assertion consumer service URL and the Service provider metadata URL (which many IdPs can read instead). They contain the team’s id and stay the same for the life of the team.
3. Create a SAML application at your IdP with those values (see the table below).
4. Back in Sternway, choose the SSO organization name members will type, such as acme. Names are unique on the server, first come, first served.
5. Give Sternway the IdP: its IdP metadata URL and Fetch (your app downloads it, over HTTPS; the server never fetches URLs for a team), or paste the IdP metadata XML, or fill in the IdP entity ID, IdP sign-in URL and Signing certificate by hand.
6. Optionally map the Email attribute and Name attribute, turn on Require SSO for members, and Save.

Sternway shows or needs	Keycloak	Okta	Microsoft Entra ID	Google Workspace
Entity ID	Client ID	Audience URI (SP Entity ID)	Identifier (Entity ID)	Entity ID
Assertion consumer service URL	Valid redirect URIs and Master SAML processing URL	Single sign-on URL	Reply URL	ACS URL
IdP metadata URL	https://<host>/realms/<realm>/protocol/saml/descriptor	Sign On tab › Metadata URL	App Federation Metadata Url	none: download the metadata and paste it
Name ID	format email, Force name ID format on	EmailAddress, Application username Email	user.mail	EMAIL, Primary email
Signing	Sign documents or assertions; Client signature required off	default	default	default

• Keycloak: Clients › Create client › SAML. Turn Client signature required off: Sternway does not sign its requests.
• Okta and Entra ID: starting the app from the Okta dashboard or My Apps is an IdP-initiated sign-in, which Sternway refuses. Hide the tile; members start from Sternway.
• Google Workspace: Admin console › Apps › Web and mobile apps › Add custom SAML app; download the IdP metadata in step 2 of the wizard and paste it.

Rotating the IdP’s certificate: up to two signing certificates are accepted at once. Add the new one as the Second signing certificate (or fetch the metadata again), and remove the old one after the IdP has switched.

Every change is in the team’s audit log (team.saml.updated, team.saml.removed), and so is each member’s SAML sign-in (auth.saml.signin).

Require SSO for members

With Require SSO for members on, members (not the owner) can sign in only through this team’s IdP: a password, a passkey, the server’s OIDC or another team’s IdP is refused with “Your team requires single sign-on”.

• Switching it on signs every member out; they sign in again with SSO.
• The owner keeps password sign-in, so a broken IdP setup can always be repaired.
• It is not offboarding: removing someone at the IdP stops their next SSO sign-in, but a device already signed in stays signed in. To cut someone off, remove them from the team.

Who an IdP email can reach

Before an account is linked to an IdP identity, the IdP’s email is matched only to an account that owns the team, is a member, or has an open invite to it. Invite people to the team first; then they sign in with SSO. The first sign-in links the account to the IdP identity, and later sign-ins follow that link even if the email changes at the IdP.

Set up OpenID Connect for a server (administrator)

Set STERNWAY_OIDC on the server to JSON:

{ "issuer": "https://idp.example.com/realms/main", "clientId": "sternway", "clientSecret": "…", "mode": "hybrid" }

• hybrid allows both password and SSO sign-in; enforced refuses password sign-in and sign-up, and makes recovery-kit recovery need an SSO sign-in for the same account too.
• An existing account is linked to an SSO identity by email only when the IdP marks the email as verified (email_verified: true).
• Optional keys: publicClientId, audiences, scopes (default openid email profile).

See Run the sync server for how to pass variables to the server.

Sign in with SSO (members)

1. In Settings › Account & Sync, choose Sign in with SSO.
2. Type the server address and the team’s SSO organization (leave it empty for the server’s own OIDC sign-in).
3. Before anything opens, Sternway shows the team’s name and the IdP’s host. Continue only if both are yours: someone else may have taken that organization name.
4. Sign in at the IdP in your browser. Sternway continues by itself.
5. Type your Encryption password (the first time, choose one; at least 8 characters).

What is not supported

IdP-initiated sign-in (dashboard tiles), the Artifact binding, encrypted assertions, several IdPs per team, single logout, signed AuthnRequests, SCIM or automatic team membership, and setting SAML up from the phone. Members sign in with SSO on the desktop and on the phone.