Skip to content

Help

Set up SSO and SCIM for your organization

Tested with:Databasezy API v1 · zb CLI 0.1

Team and Enterprise organizations can let members sign in to the portal through their company’s identity provider (OIDC or SAML), require it for everyone at a verified email domain, and provision members and teams automatically with SCIM. Setup is done through the API today: the Configure SAML button on the Members page is not active yet. Every step needs the org:manage permission (owners and admins).

402 plan_limit: “SSO and SCIM provisioning need the Team or Enterprise plan”

Section titled “402 plan_limit: “SSO and SCIM provisioning need the Team or Enterprise plan””

SSO, domain enforcement and SCIM are part of Team and Enterprise. On Free or Solo every SSO route answers this error. See Changing plans.

Register Databasezy as an application in your identity provider, then add the connection. Changes need a session that passed two-factor authentication if your organization requires it.

shell
# OIDC: active at once
zb api POST /v1/orgs/{org}/sso/connections -d '{
"kind": "oidc", "name": "Okta",
"issuer_url": "https://example.okta.com",
"client_id": "...", "client_secret": "...",
"default_role": "member"
}'
# SAML: give the IdP metadata URL (or the XML in idp_metadata_xml)
zb api POST /v1/orgs/{org}/sso/connections -d '{
"kind": "saml", "name": "Entra ID",
"idp_metadata_url": "https://login.example.com/federationmetadata.xml"
}'

The response includes callback_url: register it at your identity provider as the redirect URI (OIDC) or the ACS URL (SAML). default_role is the organization role for people who arrive through SSO or SCIM without a group mapping; it defaults to member (project access only).

A SAML connection stays pending until it is registered with our SAML bridge. If it does not become active, read its last_error:

shell
zb api GET /v1/orgs/{org}/sso/connections
shell
zb api POST /v1/orgs/{org}/sso/domains -d '{"domain": "example.com"}'

The answer names a TXT record to create: _databasezy-challenge.example.com with the value databasezy-verification=<token>. After it is published in DNS, verify it:

shell
zb api POST /v1/orgs/{org}/sso/domains/<domain_id>/actions/verify

If verification fails, check that the record name and value match exactly and that DNS has propagated, then retry. A domain can be verified by only one organization.

shell
zb api PATCH /v1/orgs/{org}/sso/domains/<domain_id> -d '{"enforce_sso": true}'

From then on, members whose email is at that domain must reach the organization through your identity provider. Owners are exempt, so you cannot lock yourself out. Enforcement needs a verified domain and an active connection.

403 sso_required: “requires signing in with its identity provider”

Section titled “403 sso_required: “requires signing in with its identity provider””

Your organization enforces SSO for your email domain and you signed in another way (for example with a password). Sign out, then sign in through your company’s identity provider. If you do not know how, ask your organization’s admin.

SCIM lets Okta, Entra ID and other providers create, update and remove members and teams for you.

  1. Create a token. It starts with zbscim_ and is shown once; store it in your identity provider straight away.

    shell
    zb api POST /v1/orgs/{org}/sso/scim-tokens -d '{"name": "okta"}'
  2. In your identity provider, set the SCIM base URL to https://api.databasezy.com/scim/v2 and use the token as the bearer token.

  3. Push users and groups. Users become members with the connection’s default role. Groups become teams; set what each group grants with zb api PATCH /v1/orgs/{org}/sso/scim-groups/<group_id> -d '{"team_role": "developer", "org_role": "developer"}'. When a person is in several mapped groups, the most privileged one wins.

Deactivating or deleting a user in your identity provider removes their membership and team memberships. Owners are never changed by SCIM. Revoke a token you no longer use with zb api DELETE /v1/orgs/{org}/sso/scim-tokens/<token_id>.

A user created by SCIM has no Databasezy password. They claim the account the first time they sign in through SSO, or with a verified email at your domain. If the email already belongs to an existing Databasezy account, linking it needs your organization to have verified that email’s domain.

Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket, category account) and include the connection id and kind, the connection’s status and last_error, the domain, your identity provider, the exact error text and the time in UTC. Never paste client secrets, SCIM tokens, passwords, API keys or patient data (PHI) into a ticket. See How to get help.