Merge pull request #131 from cheahjs/feat/oauth-docs

feat: add docs on configuring oauth

docs/tutorial/sso.md

@@ -5,8 +5,63 @@ title: "Federated Authentication Support"
 
 # Federated Authentication Support
 
-Open WebUI itself does not have support for federated authentication schemes such as SSO, OAuth, SAML, or OIDC.
-However, it is able to delegate authentication to an authenticating reverse proxy to achieve a similar effect as SSO.
+Open WebUI supports several forms of federated authentication:
+
+1. OAuth
+  1. Google
+  1. Microsoft
+  1. OIDC
+1. Trusted Header
+
+## OAuth
+
+There are several global configuration options for OAuth:
+
+1. `ENABLE_OAUTH_SIGNUP` - if `true`, allows accounts to be created when logging in with OAuth. Distinct from `ENABLE_SIGNUP`.
+1. `OAUTH_MERGE_ACCOUNTS_BY_EMAIL` - allows logging into an account that matches the email address provided by the OAuth provider.
+    - This is considered insecure as not all OAuth providers verify email addresses, and may allow accounts to be hijacked.
+
+### Google
+
+To configure a Google OAuth client, please refer to [Google's documentation](https://support.google.com/cloud/answer/6158849) on how to create a Google OAuth client for a **web application**.
+The allowed redirect URI should include `<open-webui>/oauth/google/callback`.
+
+The following environment variables are required:
+
+1. `GOOGLE_CLIENT_ID` - Google OAuth client ID
+1. `GOOGLE_CLIENT_SECRET` - Google OAuth client secret
+
+### Microsoft
+
+To configure a Microsoft OAuth client, please refer to [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) on how to create a Microsoft OAuth client for a **web application**.
+The allowed redirect URI should include `<open-webui>/oauth/microsoft/callback`.
+
+Support for Microsoft OAuth is currently limited to a single tenant, that is a single Entra organization or personal Microsoft accounts.
+
+The following environment variables are required:
+
+1. `MICROSOFT_CLIENT_ID` - Microsoft OAuth client ID
+1. `MICROSOFT_CLIENT_SECRET` - Microsoft OAuth client secret
+1. `MICROSOFT_CLIENT_TENANT_ID` - Microsoft tenant ID - use `9188040d-6c67-4c5b-b112-36a304b66dad` for personal accounts
+
+### OIDC
+
+Any authentication provider that supports OIDC can be configured.
+The `email` claim is required.
+`name` and `picture` claims are used if available.
+The allowed redirect URI should include `<open-webui>/oauth/oidc/callback`.
+
+The following environment variables are used:
+
+1. `OAUTH_CLIENT_ID` - OIDC client ID
+1. `OAUTH_CLIENT_SECRET` - OIDC client secret
+1. `OPENID_PROVIDER_URL` - OIDC well known URL, for example `https://accounts.google.com/.well-known/openid-configuration`
+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`
+
+## Trusted Header
+
+Open WebUI is able to delegate authentication to an authenticating reverse proxy that passes in the user's details in HTTP headers.
 There are several example configurations that are provided in this page.
 
 :::danger
@@ -16,7 +71,7 @@ Make sure to allow only the authenticating proxy access to Open WebUI, such as s
 
 :::
 
-## Generic Configuration
+### Generic Configuration
 
 When the `WEBUI_AUTH_TRUSTED_EMAIL_HEADER` environment variable is set, Open WebUI will use the value of the header specified as the email address of the user, handling automatic registration and login.
 
@@ -24,7 +79,7 @@ For example, setting `WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-User-Email` and passing
 
 Optionally, you can also define the `WEBUI_AUTH_TRUSTED_NAME_HEADER` to determine the name of any user being created using trusted headers. This has no effect if the user already exists.
 
-## Tailscale Serve
+### Tailscale Serve
 
 [Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve) allows you to share a service within your tailnet, and Tailscale will set the header `Tailscale-User-Login` with the email address of the requester.
 
@@ -61,6 +116,7 @@ services:
     environment:
       - HOST=127.0.0.1
       - WEBUI_AUTH_TRUSTED_EMAIL_HEADER=Tailscale-User-Login
+      - WEBUI_AUTH_TRUSTED_NAME_HEADER=Tailscale-User-Name
     restart: unless-stopped
   tailscale:
     image: tailscale/tailscale:latest
@@ -92,7 +148,7 @@ You will need use Tailscale's ACLs to restrict access to only port 443.
 
 :::
 
-## Cloudflare Tunnel with Cloudflare Access
+### Cloudflare Tunnel with Cloudflare Access
 
 [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel/) can be used with [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) to protect Open WebUI with SSO.
 This is barely documented by Cloudflare, but `Cf-Access-Authenticated-User-Email` is set with the email address of the authenticated user.
@@ -124,7 +180,7 @@ volumes:
 
 ```
 
-## oauth2-proxy
+### oauth2-proxy
 
 [oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/) is an authenticating reverse proxy that implements social OAuth providers and OIDC support.
 
@@ -140,6 +196,7 @@ services:
     environment:
       - 'HOST=127.0.0.1'
       - 'WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-Forwarded-Email'
+      - 'WEBUI_AUTH_TRUSTED_NAME_HEADER=X-Forwarded-User'
     restart: unless-stopped
   oauth2-proxy:
     image: quay.io/oauth2-proxy/oauth2-proxy:v7.6.0
@@ -158,14 +215,14 @@ services:
       - 4180:4180/tcp
 ```
 
-## Authelia
+### Authelia
 
 [Authelia](https://www.authelia.com/) can be configured to return a header for use with trusted header authentication.
 Documentation is available [here](https://www.authelia.com/integration/trusted-header-sso/introduction/).
 
 No example configs are provided due to the complexity of deploying Authelia.
 
-## Authentik
+### Authentik
 
 [Authentik](https://goauthentik.io/) can be configured to return a header for use with trusted header authentication.
 Documentation is available [here](https://docs.goauthentik.io/docs/providers/proxy/).