From aaad576cc0f9cf4e7a8eb2defc9cba71d4b1d0d9 Mon Sep 17 00:00:00 2001
From: "Willnow, Patrick" <patrick.willnow@th-luebeck.de>
Date: Wed, 16 Oct 2024 21:55:58 +0200
Subject: [PATCH] Adding docs for oauth role management feature

---
 docs/getting-started/env-configuration.md | 24 +++++++++++++++++++++++
 docs/tutorials/features/sso.md            | 12 ++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/docs/getting-started/env-configuration.md b/docs/getting-started/env-configuration.md
index 6b29fd9..a01b0e6 100644
--- a/docs/getting-started/env-configuration.md
+++ b/docs/getting-started/env-configuration.md
@@ -1031,6 +1031,30 @@ account takeovers.
 - Default: `SSO`
 - Description: Sets the name for the OIDC provider.
 
+#### `ENABLE_OAUTH_ROLE_MANAGEMENT`
+
+- Type: `bool`
+- Default: `False`
+- Description: Enables role management to oauth delegation.
+
+#### `OAUTH_ROLES_CLAIM`
+
+- Type: `str`
+- Default: `roles`
+- Description: Sets the roles claim to look for in the OIDC token.
+
+#### `OAUTH_ALLOWED_ROLES`
+
+- Type: `str`
+- Default: `user,admin`
+- Description: Sets the roles that are allowed access to the platform.
+
+#### `OAUTH_ADMIN_ROLES`
+
+- Type: `str`
+- Default: `admin`
+- Description: Sets the roles that are considered administrators.
+
 #### `GOOGLE_CLIENT_ID`
 
 - Type: `str`
diff --git a/docs/tutorials/features/sso.md b/docs/tutorials/features/sso.md
index 17a41ac..045bb1b 100644
--- a/docs/tutorials/features/sso.md
+++ b/docs/tutorials/features/sso.md
@@ -59,6 +59,18 @@ The following environment variables are used:
 1. `OAUTH_PROVIDER_NAME` - Name of the provider to show on the UI, defaults to SSO
 1. `OAUTH_SCOPES` - Scopes to request. Defaults to `openid email profile`
 
+### OAuth Role Management
+
+Any OAuth provider that can be configured to return roles in the access token can be used to manage roles in Open WebUI.
+To use this feature set `ENABLE_OAUTH_ROLE_MANAGEMENT` to `true`.
+You can configure the following environment variables to match the roles returned by the OAuth provider:
+
+1. `OAUTH_ROLES_CLAIM` - The claim that contains the roles. Defaults to `roles`. Can also be nested, for example `user.roles`.
+1. `OAUTH_ALLOWED_ROLES` - A comma-separated list of roles that are allowed to log in (receive open webui role `user`).
+1. `OAUTH_ADMIN_ROLES` - A comma-separated list of roles that are allowed to log in as an admin (receive open webui role `admin`).
+
+:::info If changing the role of a logged in user, they will need to log out and log back in to receive the new role. :::
+
 ## Trusted Header
 
 Open WebUI is able to delegate authentication to an authenticating reverse proxy that passes in the user's details in HTTP headers.