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.
