Skip to content
Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// admin

OIDC / single sign-on

Overview

Signing in through your organisation's existing identity provider (OpenID Connect). What SSO means for users, what basebox needs for it and where the line runs between your task as administrator and that of the Platform Operator.

What it is for

With single sign-on, your employees sign in to basebox with the account they use every day anyway – for example Microsoft Entra ID (Azure AD), Okta or another OpenID Connect provider. Benefits:

  • no additional passwords, and your password and MFA policies apply automatically,
  • central blocking: whoever is deactivated at the provider can no longer enter basebox,
  • less support: forgotten-password cases land with your provider, not with basebox.

How basebox authenticates

Internally, basebox uses Keycloak as its identity provider (OIDC). Every sign-in – local account, LDAP user or SSO – goes through Keycloak; the frontend talks to Keycloak via OpenID Connect, and the application server verifies the issued tokens.

For SSO, your identity provider is registered in Keycloak as an Identity Provider (identity brokering). The flow for users:

  1. Users open basebox and click sign in.
  2. Keycloak redirects them to your identity provider.
  3. There they sign in as usual (including MFA, if configured).
  4. Your provider confirms the identity to Keycloak; basebox signs the person in.

From the user's perspective: one click, the familiar sign-in page, done.

Where to find the setting

Not in the basebox administration, but in the Keycloak Admin Console (on basebox Server at https://<your-basebox-domain>/auth, realm usually primary) under Identity Providers. The Platform Operator has access to it. In basebox Cloud, basebox sets up SSO for you – contact support@basebox.ai.

Step by step

What you contribute as an administrator:

  1. Name the provider – which OpenID Connect provider, which tenant.
  2. Have a client registered with your provider – your identity team creates an application for basebox there and receives client ID and client secret. The redirect URI to enter there is supplied by the Platform Operator from Keycloak (pattern: https://<your-basebox-domain>/auth/realms/<realm>/broker/<alias>/endpoint).
  3. Provide the discovery URL – your provider's .well-known/openid-configuration address.
  4. Clarify the user population – may all accounts of the provider use basebox, or only one group? The restriction is applied at the provider (application assignment) or via Keycloak.
  5. Hand over to the Platform Operator, who registers and tests the identity provider in Keycloak.

What happens in basebox afterwards:

  • On the first SSO login, the person's basebox account is created or matched to an existing account by e-mail address.
  • The role (administrator/user) is assigned in basebox; it does not come from the provider.
  • Groups for sharing are created in basebox.

Notes

Note

  • SSO does not replace licence seats. Every signed-in person occupies a user seat.
  • The first administrator remains a local account in Keycloak – it is your lifeline if the external provider is unreachable. Keep the credentials safe.
  • LDAP or OIDC? LDAP synchronises accounts from a directory and verifies passwords there; OIDC delegates the entire sign-in to your provider. Both can be combined. See LDAP integration.
  • For Platform Operators: the relevant frontend variables are VITE_BB_OIDC_DOMAIN (ends with /auth/realms/), VITE_BB_OIDC_FORCE_REALM (usually primary) and VITE_BB_OIDC_CLIENT_ID; on the server side AISRV_OIDC_IDP_URL and AISRV_OIDC_AUD. Typical failure patterns (redirect loop, "iss does not match") are in the FAQ.

Do not change the issuer on a hunch

The application server uses the issuer to check that a token really comes from your Keycloak. If it is set to a foreign issuer, that issuer's tokens could gain access to your instance. Changes to it belong in the hands of the Platform Operator.

Frequently asked questions

Can users still sign in with a password when SSO is active? Local accounts remain usable as long as they exist. Whether password sign-in is hidden is decided by the Keycloak configuration.

What happens if our identity provider is down? SSO sign-ins fail until it is reachable again. Sessions already signed in continue until the token expires. Local accounts work unchanged.

Does SSO also apply to the API? No. The API uses API keys issued by administrators – see API keys.

Does our provider get to see chat content? No. The provider only confirms the identity; content stays in basebox.

Need help? Contact support