Single sign-on for workspaces

Before you start

• You are an owner or admin of the workspace.
• Your email domain is verified: on the workspace page, under Email domains, add the domain and the DNS TXT record it shows, then select Verify. SSO only signs in addresses at verified domains.
• Your provider can create an OpenID Connect web application with a client secret.

Connect the provider

1. On the workspace page, find Single sign-on and copy the redirect URI (for granite.md it is https://app.granite.md/sso/callback).
2. Create a web application in your provider (steps below) with that redirect URI, and note its issuer URL, client ID, and client secret.
3. Enter the three values in Granite and select Connect. Granite checks the issuer's discovery document at once.
4. Sign out, then sign in with Sign in with SSO using your work email. A successful sign-in shows as Last SSO sign-in.

People new to the workspace join as members, or as guests if you choose so. Granite asks the provider for the openid, email, and profile scopes, uses PKCE and a nonce, and stores the client secret encrypted.

Google Workspace

1. In the Google Cloud console, open APIs & Services → OAuth consent screen and choose Internal, so only your organization's accounts can sign in.
2. Open Credentials → Create credentials → OAuth client ID, choose Web application, and add the redirect URI under Authorized redirect URIs.
3. Issuer URL: https://accounts.google.com. Use the client ID and secret Google shows.

Okta

1. In the Okta Admin Console, open Applications → Create App Integration, choose OIDC - OpenID Connect and Web Application.
2. Add the redirect URI under Sign-in redirect URIs, and assign the people or groups who may use Granite.
3. Issuer URL: your Okta domain, such as https://example.okta.com (or a custom authorization server such as https://example.okta.com/oauth2/default). Copy the client ID and client secret from the app's General tab.

Microsoft Entra ID

1. In the Microsoft Entra admin center, open App registrations → New registration. Choose accounts in this organizational directory only, and add the redirect URI with the Web platform.
2. Under Certificates & secrets, create a client secret and copy its value.
3. Under Token configuration, add the optional claim email to the ID token, so Granite receives the work address.
4. Issuer URL: https://login.microsoftonline.com/<tenant ID>/v2.0. The client ID is the Application (client) ID.

Keycloak

1. In your realm, open Clients → Create client with type OpenID Connect. Turn on Client authentication and keep Standard flow.
2. Add the redirect URI under Valid redirect URIs, and copy the secret from the Credentials tab.
3. Issuer URL: https://keycloak.example.com/realms/<realm>. Make sure users have a verified email.

SAML 2.0

Choose SAML 2.0 under Protocol and give your identity provider's metadata: its URL, or the XML pasted in. After you select Connect, Granite shows its own service provider details to register with the provider:

• Entity ID and metadata URL: https://api.granite.md/v1/sso/saml/<workspace ID>/metadata. Most providers can import everything from this URL.
• Assertion consumer service (HTTP-POST binding): https://api.granite.md/v1/sso/saml/<workspace ID>/acs.
• Name ID: the email address (or send an email attribute).

Granite signs its authentication requests and accepts only signed responses (or signed assertions); it can decrypt encrypted assertions with the certificate in its metadata. Each assertion is accepted once, clocks may differ by up to three minutes, and sign-in can start at Granite or from your provider's app dashboard.

Require SSO

After one successful SSO sign-in you can turn on Require SSO. Then members whose email is at a verified domain cannot sign in with a password or Google/Apple, and sessions they started that way can no longer open the workspace's vaults. The workspace owner can always sign in with a password, so a broken provider setup can be fixed. Changing the issuer, client ID, or secret needs a new test sign-in before SSO can be required again.

Two-step verification is your provider's job for SSO sign-ins: a workspace rule requiring two-step verification counts an SSO session as verified.

Provisioning with SCIM

With SCIM 2.0 your identity provider keeps the workspace's members and groups in step with your directory. On the workspace page, under Provisioning (SCIM), select Turn on provisioning and copy the token; it is shown once. In your provider, set:

• SCIM base URL (tenant URL): https://api.granite.md/scim/v2
• Authentication: bearer token (Okta: HTTP Header; Entra ID: Secret token), the token you copied.
• Unique identifier: userName, the work email. Only emails at your verified domains can be provisioned.

Granite supports creating, updating, deactivating, and deleting users, groups with members, filters on userName, externalId, and displayName, and PATCH. Deactivating or removing someone suspends or removes their membership and signs them out of Granite everywhere at once: their sessions, API tokens, and connected apps stop working. The workspace owner cannot be removed through SCIM. Replacing the token stops the old one immediately.

Troubleshooting

“No single sign-on is set up for this email address”

The email's domain is not verified for a workspace with SSO. Check Email domains.

“… is not at one of the workspace's verified domains”

The provider returned a different email than expected; for Entra ID add the email claim.

“Single sign-on failed”

The redirect URI, client ID, or secret does not match the provider's settings, or the sign-in took longer than 10 minutes.