Access & Authentication

BullSequana AI uses Keycloak for authentication, single sign-on, and organization membership. Keycloak normally federates with the enterprise identity provider instead of replacing it as the source of user identities.

Sign-in flow

For most users, access works as follows:

1. Open the BullSequana AI URL supplied for the deployment.
2. Select Sign in.
3. Authenticate with the configured enterprise identity provider.
4. Return to the portal with the roles and Keycloak Organization memberships assigned to the account.

The same SSO session is used across supported platform services. A deployment can federate Keycloak with Microsoft Entra ID, LDAP, Active Directory, another Keycloak instance, or another supported identity provider.

Organizations and tenants

A Keycloak Organization represents a BullSequana AI tenant. Its immutable Organization UUID is the tenant identifier used by the portal, BSQAI API, and tenant-scoped application records.

Users who belong to one organization enter that tenant automatically. Users who belong to more than one organization select the active organization in the portal. Changing it reloads tenant-scoped data so records cached for the previous tenant are not shown in the new context.

The active tenant applies to:

• chats and responses
• files, folders, and RAG selections
• Agents and MCP Servers
• API keys and model presets
• configuration, branding, translations, and web-search providers
• document-intelligence configurations and runs

Requests for identifiers owned by another tenant return not found. This avoids disclosing whether the resource exists outside the active tenant.

Tenant selection in the API

JWT users with more than one Organization membership send the selected Organization UUID in X-Tenant-Id:

curl "https://api.<platform-domain>/v1/models" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "X-Tenant-Id: <keycloak-organization-uuid>"

The header is optional when the token has exactly one Organization membership. Browser WebSocket connections use the tenant_id query parameter instead.

API keys are tenant-bound when created. The BSQAI API resolves their tenant from the key, so an API key cannot be moved between organizations.

See Use local models via API for complete authentication examples.

Component SSO enrollment

Platform components do not require manual Keycloak client creation. When a component has SSO enabled, generated Argo CD hook resources:

1. create or update the OIDC client, scopes, protocol mappers, groups, and roles before the component deploys
2. preserve an existing client secret during reconciliation
3. remove component-specific identity resources when the application is deleted

BullSequana AI 1.3.0 also reconciles Organization support and the organization UUID claim on existing realms. This allows upgraded environments to use the same tenant-selection model as fresh deployments.

See Keycloak and Configuration model.

Multi-factor authentication

The identity administrator can enforce additional authentication steps, including one-time-password authenticators, through Keycloak or the federated identity provider. Apply the organization’s production identity policy rather than creating a separate weaker policy for the platform.

Development and demonstration clusters

When federation is not configured, an administrator can create a local Keycloak user for testing:

1. Open the Keycloak administration console.
2. Select the dataplatform realm.
3. Open Users and select Create user.
4. Set the username, email, first name, and last name.
5. Add a password on the user’s Credentials tab.
6. Add the user to the required Organization and assign the platform roles needed for the test.

Local users are intended for non-production environments.

Related pages

• Portal guide
• Administration and operations
• Keycloak
• Security model
• Multi-tenancy and tiered RBAC