Single sign on

Since version 3.7.0 users can sign in to Databucket through any OpenID Connect provider, e.g. Microsoft Entra ID (Azure AD), Google, Okta or Keycloak. The login page then shows a Sign in with ... button next to the user name and password form.

How it works

Single sign-on only authenticates the user. Everything else stays in Databucket:

• A person can sign in only if a Databucket user with the same email already exists. Accounts are not created automatically. Create the user in Databucket first (see Manage users) and enter the email the person has at the identity provider.
• Roles, projects and teams are still assigned in Databucket.
• The user name and password login and the API keep working as before.

Emails are compared case-insensitively, and since 3.7.0 every user must have a unique email. When upgrading an existing database, run the upgrade script first (see Installation → Upgrading).

After signing in at the provider the user lands back in Databucket:

• user assigned to one project → goes straight into it,
• user assigned to several projects → chooses the project from a list,
• otherwise → the login page shows the reason (see Troubleshooting).

Register Databucket at the provider

Register Databucket as a web application (a confidential client using the authorization code flow) and note its client ID and client secret.

Setting at the provider	Value
Redirect URI	<databucket url>/login/oauth2/code/oidc, e.g. https://databucket.example.com/login/oauth2/code/oidc
Post logout redirect URI (only with provider-logout: true)	<databucket url>/login
Scopes	openid email profile

<databucket url> is the address users open in the browser, including the context path when Databucket runs under one (e.g. https://example.com/databucket).

Configuration

Add the sso section to your configuration file (see Installation):

sso:
  enabled: true
  provider: microsoft          # button style: microsoft, google, okta, keycloak or generic
  name:                        # "Sign in with <name>"; empty = the provider's name
  issuer-uri: https://login.microsoftonline.com/<tenant id>/v2.0
  client-id: <client id>
  client-secret: <client secret>

Property	Default	Description
sso.enabled	false	Shows the SSO button and enables the SSO endpoints.
sso.provider	generic	Style of the button: microsoft, google, okta, keycloak or generic. Any OpenID Connect provider works with generic.
sso.name		Text after "Sign in with". When empty, the provider's name is used (SSO for generic).
sso.issuer-uri		Issuer of the provider. Databucket reads the provider's settings from <issuer-uri>/.well-known/openid-configuration.
sso.client-id		Client ID from the provider.
sso.client-secret		Client secret from the provider.
sso.scopes	openid, email, profile	Requested scopes.
sso.email-claim	email	Claim of the ID token compared with the users' emails.
sso.provider-logout	false	Logging out of Databucket also logs out of the provider, see Logout.
sso.code-ttl-seconds	120	How long the short-lived sign-in code handed to the browser after the provider login is valid.

Like any Spring Boot property, they can also be set as environment variables, which is handy for the secret: SSO_ENABLED=true, SSO_ISSUER_URI=..., SSO_CLIENT_ID=..., SSO_CLIENT_SECRET=....

Databucket contacts the provider only when someone clicks the SSO button. If the provider is unreachable, Databucket still starts and the user name and password login works. Clicking the SSO button then shows a "not available" message.

Provider examples

Microsoft Entra ID (Azure AD)

1. App registrations → New registration, platform Web, redirect URI <databucket url>/login/oauth2/code/oidc.
2. Certificates & secrets → New client secret.
3. Token configuration → Add optional claim → ID → email. Entra ID does not send the email by default.

sso:
  enabled: true
  provider: microsoft
  issuer-uri: https://login.microsoftonline.com/<directory (tenant) id>/v2.0
  client-id: <application (client) id>
  client-secret: <client secret value>

Use your tenant ID in the issuer, not common or organizations. When the users' emails in Databucket are their sign-in names (UPN), you can use email-claim: preferred_username instead of adding the optional claim.

Google

1. Google Cloud console → APIs & Services → Credentials → Create credentials → OAuth client ID, type Web application.
2. Add <databucket url>/login/oauth2/code/oidc to Authorized redirect URIs.

sso:
  enabled: true
  provider: google
  issuer-uri: https://accounts.google.com
  client-id: <client id>.apps.googleusercontent.com
  client-secret: <client secret>

Google has no logout endpoint for applications, so provider-logout has no effect with Google.

Okta

1. Applications → Create App Integration → OIDC → Web Application.
2. Sign-in redirect URI <databucket url>/login/oauth2/code/oidc; with provider-logout: true also Sign-out redirect URI <databucket url>/login.

sso:
  enabled: true
  provider: okta
  issuer-uri: https://<your org>.okta.com/oauth2/default
  client-id: <client id>
  client-secret: <client secret>

Keycloak

1. In your realm: Clients → Create client, type OpenID Connect, Client authentication: On, Standard flow enabled.
2. Valid redirect URIs <databucket url>/login/oauth2/code/oidc; with provider-logout: true also Valid post logout redirect URIs <databucket url>/login.
3. Copy the secret from the Credentials tab.
4. Users need an email, and it must be verified (Keycloak sends email_verified, and Databucket refuses unverified emails).

sso:
  enabled: true
  provider: keycloak
  issuer-uri: https://<keycloak host>/realms/<realm>
  client-id: databucket
  client-secret: <client secret>

Logout

By default, Logout in Databucket ends only the Databucket session. The session at the provider stays, so the next click on the SSO button signs the user in without asking for the password again. This is the usual behaviour with Microsoft or Google accounts.

With sso.provider-logout: true, logging out of Databucket after an SSO sign-in also ends the session at the provider. Afterwards the provider sends the user back to the Databucket login page. Keep in mind:

• With Microsoft or Google this signs the user out of their whole account (mail, Teams, ...), not only Databucket.
• The provider may ask the user to confirm the logout (Keycloak does).
• <databucket url>/login must be allowed as a post logout redirect URI at the provider.
• Users who signed in with a user name and password are logged out of Databucket only.

Several instances and reverse proxies

The SSO login keeps no state on the server, so it works with several Databucket instances behind a load balancer without sticky sessions. All instances must use the same jwt.secret.

Behind a reverse proxy, Databucket builds the redirect URI from the X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Port headers. It trusts them only from internal addresses (10.x, 172.16–31.x, 192.168.x, localhost). If the provider reports a redirect URI mismatch, e.g. http:// instead of https://, check that the proxy sends these headers.

Troubleshooting

When the SSO sign-in does not succeed, the login page shows one of these messages:

Message	Reason
There is no Databucket account for your email address.	No Databucket user has the email sent by the provider. Create the user, or correct their email.
Your Databucket account is disabled.	The Databucket user is disabled.
Your email address is not verified at the identity provider.	The provider marked the email as unverified (email_verified: false).
The identity provider did not send your email address.	The ID token has no email claim. Add the claim at the provider (Entra ID: optional claim email), check that the email scope is allowed, or change sso.email-claim.
Single sign-on is not available at the moment.	Databucket cannot read the provider's configuration from issuer-uri. Check the URL and that Databucket can reach the provider. The server log shows the details.
Signing in with the identity provider failed.	The provider returned an error, or the client ID or secret is wrong. The server log shows the details.
User access has expired! / The user is not assigned to any project!	The same checks as for the user name and password login.

Each SSO sign-in and each refusal is written to the server log by the pl.databucket.server.operation.auth logger, with the email and the reason.