Organization SSO

Configure SAML

Organization SSO is available to organizations enabled for the rollout. An administrator opens the organization SSO settings and enters the identity provider entity ID, HTTPS SSO URL, signing certificate, and email claim name. You can upload identity provider metadata XML instead. BoringCache shows its service provider metadata URL on that page.

Configure the identity provider to send a signed SAML assertion to the assertion consumer URL in the BoringCache metadata. The assertion must include a stable NameID and the configured email claim. BoringCache uses the NameID within this organization for returning sign-ins. The email claim must match the existing BoringCache account when a member links for the first time.

Members first create and confirm their BoringCache accounts, accept their invitations, and link those accounts with a recent independent sign-in and a SAML response. A SAML assertion does not create a BoringCache account or assign an organization role.

Google Workspace setup

Use Google Workspace as your organization's SAML identity provider. The ordinary Sign in with Google button authenticates your BoringCache account; it does not satisfy organization SSO. This setup requires a Google Workspace super administrator, a BoringCache organization administrator, and SSO enabled for the organization. If Organization SSO is missing from organization Settings, contact support before creating the Google application.

1. In Google Admin, open Apps → Web and mobile apps → Add app → Add custom SAML app. Name it BoringCache and download the IdP metadata.
2. In BoringCache organization Settings → Organization SSO, upload that XML, set Email claim name to email, keep Connection mode Off, and save. Open Identity provider setup metadata to obtain the service provider values.
3. In Google's service provider settings, use the values below. Finish the application and enable User access only for the pilot users or group.

Google defaults Name ID to the primary email address. If you use that default with format EMAIL, renaming the address changes the SSO identity. Never assign a former member's Name ID to another person: returning sign-ins use the linked Name ID, not the email claim. Prefer an immutable custom directory attribute for continued use. Group claims do not assign BoringCache roles.

If a member's Google primary email differs from their existing BoringCache account email, create a single-value custom Email attribute in Google Admin under Directory → Users → More options → Manage custom attributes. Set that user's attribute to their BoringCache account email, then map the custom attribute to email in the SAML app instead of Primary email. Create the custom attribute before opening the SAML app wizard so it appears in the field selector. Keep Name ID separate: it identifies the linked Google identity on returning sign-ins.

Sign in to BoringCache again using your existing account method, then select Link my account within 15 minutes. The mapped email claim must match that account. The primary organization administrator must also select Test SSO and confirm Configuration test: Passed. Testing the connection and linking an account are separate actions. Select Optional mode for the pilot after both succeed.

Use BoringCache's organization SSO entry point for subsequent sign-ins. Google's Test SAML login button and app launcher initiate a different flow that BoringCache does not accept. If linking fails, check the separate email mapping, exact metadata URLs, app assignment, and recent BoringCache sign-in before starting again. Google access changes can take up to 24 hours.

See Google's custom SAML app instructions for the Admin console controls. Complete the enforcement and recovery checks below before requiring SSO.

Enable enforcement

The primary organization administrator tests the current connection using their account, registers a BoringCache passkey, and saves the recovery codes. That administrator then reviews existing organization and workspace tokens and MCP connections. Revoke or replace legacy scoped credentials and reconnect MCP clients before selecting Required mode.

Optional mode lets members link and use organization SSO while existing account sign-in still works. Required mode requires a current organization SSO grant for browser, CLI, and MCP access. An ordinary account sign-in still permits access to a personal account and organizations that do not require SSO.

Updating the identity provider URL, entity ID, certificate list, or email claim invalidates the connection test and existing organization grants. Upload new signing certificates before retiring old ones, then test the updated connection before relying on it.

CLI and machine access

Choose an organization workspace in the CLI browser approval flow after signing in with that organization's SSO. Human CLI tokens and MCP connections expire no later than the organization SSO proof, up to eight hours. Repeat organization sign-in to issue a new human credential after expiry. User-wide tokens cannot access a required SSO organization.

Organization administrators can approve scoped machine credentials after recent organization SSO. Machine credentials have their own expiry and revocation. Removing the approving member does not revoke an approved machine credential; administrators should review and rotate any reusable secret the departing member knew. Workload OIDC remains available for CI where configured.

Recovery and offboarding

If the identity provider connection stops working, the primary organization administrator can sign in to the BoringCache account with a passkey and use one unused recovery code to change the connection mode to Optional or Off. Recovery changes enforcement; it does not grant organization access. BoringCache emails the primary administrator after recovery.

Removing a member or disabling their linked SSO identity revokes their organization grants and human credentials. A registry bearer token already issued can remain valid for up to five minutes. A direct storage URL already issued can remain valid for up to 24 hours, depending on the storage connection and transfer size. An operation already in progress may finish. Provider-side account disablement is detected at the next SAML sign-in. Existing BoringCache organization grants can remain valid for up to eight hours unless an administrator removes the member or disables the linked identity. This release does not provide automatic directory provisioning or SAML Single Logout.