# Access & Authentication (/docs/use/access)



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 [#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 [#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 [#tenant-selection-in-the-api]

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

```bash
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](/docs/develop/use-local-models-via-api) for complete authentication examples.

## Component SSO enrollment [#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](/docs/foundation/components/keycloak) and [Configuration model](/docs/deployment/configuration-model#sso-configuration).

## Multi-factor authentication [#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 [#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 [#related-pages]

* [Portal guide](/docs/use/portal)
* [Administration and operations](/docs/administration)
* [Keycloak](/docs/foundation/components/keycloak)
* [Security model](/docs/foundation/security-model)
* [Multi-tenancy and tiered RBAC](/docs/data/multi-tenancy-and-tiered-rbac)