Connect Open WebUI to Keycloak

Connect Open WebUI to Keycloak through OIDC with explicit role claims, denied-access tests, session checks and a controlled recovery administrator.

Last updated

In short

  • OIDC sign-in and document authorization are separate controls.
  • Use explicit application roles and test absent or malformed claims.
  • Preserve a controlled recovery path before changing authentication.
On this page (6)

Integrations · Part of Private AI

Decide what SSO should authorize

Keycloak can authenticate people entering Open WebUI and provide claims used for application roles or groups. That establishes an identity boundary around the AI interface. It does not by itself prove that a person can see only the right documents, use only approved models or access only their own conversations.

This is a documented reference procedure. The upstream Keycloak tutorial is itself marked as a community contribution, and its development-server examples are not a production deployment specification. Use the current Open WebUI SSO reference alongside the documentation for the exact releases selected for your pilot.

Prepare a configuration record

Pin the Open WebUI image release and digest, Keycloak release, public application URL and realm issuer. Keep the application behind HTTPS and restrict the administration endpoints. A production Keycloak deployment requires its own database, hostname and proxy configuration; starting a development server is not the finished identity service.

Setting Reference value or source Check before enabling
Client ID Dedicated client such as open-webui No reuse of an unrelated application’s credentials
Client authentication Confidential application credential Secret stored outside the public repository
Discovery URL Realm’s OIDC discovery document Expected HTTPS issuer and reachable signing keys
Redirect URI Exact callback generated/documented for the application No broad wildcard
User roles Application-specific user and administrator claims No accidental mapping from general directory admin groups
Registration Explicitly chosen OAuth account-creation behavior Unassigned users cannot self-enroll

Use the supported OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET and OPENID_PROVIDER_URL settings for the chosen release. Verify effective configuration after startup: some Open WebUI settings persist in the application database, so changing an environment variable is not sufficient evidence that the active value changed.

Map a small role vocabulary

Define two application-specific roles, for example ai-user and ai-admin, rather than granting administrator privileges to every authenticated person. Configure the role-claim path and the allowed/admin role lists consistently. The SSO documentation describes OAuth role management and notes that role updates take effect through a subsequent login; inspect the selected release’s behavior for active sessions as well.

Synthetic identity Claim Expected result
Alice ai-user Can use the approved AI workspace
Ben No permitted application role Cannot gain access through the chosen login policy
Clara ai-admin Can administer only through the deliberately granted role
Dana Malformed or unexpected claim Clear rejection or the explicitly documented safe default
Alice after removal Role removed Access ends within the agreed revocation interval

Do not assume Keycloak’s default nested realm-role structure matches the claim name expected by the application. Create a client-specific mapper if necessary, inspect a synthetic token and document the exact resulting claim. Keep unnecessary directory memberships out of the token.

Test the data boundary separately

After sign-in works, create a small workspace with two harmless knowledge documents and different permitted users. Check browsing, retrieval, citations, conversation sharing and direct API requests. A user who cannot see a knowledge item in the interface must also be unable to retrieve it through another available route.

For models, test whether the user can select an unapproved provider, change a connection, invoke tools or upload a file to an external processing service. These are application permissions and egress controls, not properties guaranteed by OIDC. Use the permission-aware RAG design if the corpus contains different document-level access rules.

Disable any authentication bypass that is not part of the documented design. Trusted-header authentication requires a proxy that strips untrusted incoming identity headers and prevents direct backend access. It should not accidentally coexist with an exposed route that lets a caller supply their own identity.

Rehearse account linking and offboarding

If Open WebUI already contains local accounts, establish how an OIDC identity links to them before enabling general registration. Test an email rename, a reused address and a user who already owns conversations. Do not merge identities merely because a display name matches.

Remove Alice’s role while she has an active browser tab and API credential. Observe each separately, then repeat after disabling her Keycloak account. Record which sessions survive until expiry and which credentials require application-side revocation. Make the measured result part of the organization’s offboarding procedure.

Keep an approved recovery administrator available while introducing SSO. Protect it with separate controls and record its use. This is an operational recovery path, not a general alternative for employees who fail the identity policy.

Licence, backup and upgrade acceptance

Review the Open WebUI licence for branding and distribution obligations. An OIDC feature being available does not settle every enterprise support or redistribution requirement. Record the exact entitlement and service scope selected for production.

Back up the application database, configuration and secrets needed for recovery, plus the Keycloak state relevant to the client. Before an upgrade, retain a matching database backup and rerun login, denied-role, administrator and knowledge-access tests. If an upgrade changes stored configuration or account mappings, restoring the prior image alone may not reverse it.

Accept the integration only when the test record demonstrates correct identity linking, least-privilege roles, deliberate data access, measurable revocation and a usable recovery path. A successful login screenshot covers only the first part of that evidence.

Sources and further reading

Use the linked documentation to confirm the version, edition and contract that apply to your project.

Connect identity to our AI pilot

Bring the intended AI user groups, administrator policy, document boundaries and existing Open WebUI accounts.