Issue: Document offline_access Scope for Microsoft OAuth Summary #148

New Issue

2026-02-15T17:15:22-05:00

yindo commented

2026-02-15 17:15:22 -05:00

Originally created by @Classic298 on GitHub (Feb 12, 2026).

Issue: Document `offline_access` Scope for Microsoft OAuth

Summary

The Microsoft OAuth documentation should recommend adding offline_access to the OAuth scopes to enable token refresh and prevent session expiration issues.

What is `offline_access`?

The offline_access scope is a standard OAuth 2.0 scope that instructs Microsoft's identity platform to return a refresh token alongside the access token during authentication.

Scope	What Microsoft Returns
`openid email profile` (current default)	`access_token` only
`openid email profile offline_access`	`access_token` + `refresh_token`

Microsoft's access tokens expire after approximately 1 hour. Without a refresh token, there is no way to obtain a new access token without requiring the user to re-authenticate.

Why It Matters

Open WebUI stores the OAuth session server-side and includes middleware that automatically refreshes tokens before they expire. However, this refresh mechanism only works if a refresh token was provided during initial authentication.

Without offline_access:

User logs in via Microsoft OAuth
Access token expires after ~1 hour
Middleware attempts to refresh → fails (no refresh token)
OAuth session is deleted
Repeated warnings appear in logs: No OAuth session found for user X, session Y
Features requiring Microsoft Graph API access stop working (MCP tool servers with system_oauth, OneDrive integration, profile picture updates)

With offline_access:

User logs in via Microsoft OAuth
Access token expires after ~1 hour
Middleware automatically refreshes the token using the refresh token
User remains authenticated seamlessly
Microsoft Graph API features continue working indefinitely

Symptoms of Missing `offline_access`

Log warnings that appear repeatedly after users have been logged in for more than 1 hour:

WARNING | No refresh token available for session xxx
ERROR   | Failed to refresh token for session xxx
WARNING | Token refresh failed for user xxx, deleting session
WARNING | No OAuth session found for user xxx, session xxx

These warnings are harmless for basic chat functionality (which uses Open WebUI's JWT, not the OAuth token), but indicate that:

Microsoft Graph API integrations will fail
MCP tool servers using auth_type: "system_oauth" will not work
OneDrive/SharePoint file access may fail
Profile picture refresh from Microsoft will fail

References

Microsoft Identity Platform Scopes Documentation

"On the Microsoft identity platform (requests made to the v2.0 endpoint), your app must explicitly request the offline_access scope, to receive refresh tokens."
Open WebUI OAuth middleware: backend/open_webui/utils/oauth.py - _perform_token_refresh() method requires refresh token to function

Impact

User Experience: Eliminates need to re-authenticate every hour when using Microsoft integrations
Log Cleanliness: Removes repetitive warning messages
Feature Completeness: Ensures MCP and OneDrive integrations work reliably
Security: Uses standard OAuth refresh flow rather than forcing frequent re-authentication

Originally created by @Classic298 on GitHub (Feb 12, 2026). ## Issue: Document `offline_access` Scope for Microsoft OAuth ### Summary The Microsoft OAuth documentation should recommend adding `offline_access` to the OAuth scopes to enable token refresh and prevent session expiration issues. --- ### What is `offline_access`? The `offline_access` scope is a standard OAuth 2.0 scope that instructs Microsoft's identity platform to return a **refresh token** alongside the access token during authentication. | Scope | What Microsoft Returns | |-------|----------------------| | `openid email profile` (current default) | `access_token` only | | `openid email profile offline_access` | `access_token` + `refresh_token` | Microsoft's access tokens expire after approximately 1 hour. Without a refresh token, there is no way to obtain a new access token without requiring the user to re-authenticate. --- ### Why It Matters Open WebUI stores the OAuth session server-side and includes middleware that automatically refreshes tokens before they expire. However, this refresh mechanism **only works if a refresh token was provided during initial authentication**. **Without `offline_access`:** 1. User logs in via Microsoft OAuth 2. Access token expires after ~1 hour 3. Middleware attempts to refresh → fails (no refresh token) 4. OAuth session is deleted 5. Repeated warnings appear in logs: `No OAuth session found for user X, session Y` 6. Features requiring Microsoft Graph API access stop working (MCP tool servers with `system_oauth`, OneDrive integration, profile picture updates) **With `offline_access`:** 1. User logs in via Microsoft OAuth 2. Access token expires after ~1 hour 3. Middleware automatically refreshes the token using the refresh token 4. User remains authenticated seamlessly 5. Microsoft Graph API features continue working indefinitely --- ### Symptoms of Missing `offline_access` Log warnings that appear repeatedly after users have been logged in for more than 1 hour: ``` WARNING | No refresh token available for session xxx ERROR | Failed to refresh token for session xxx WARNING | Token refresh failed for user xxx, deleting session WARNING | No OAuth session found for user xxx, session xxx ``` These warnings are harmless for basic chat functionality (which uses Open WebUI's JWT, not the OAuth token), but indicate that: - Microsoft Graph API integrations will fail - MCP tool servers using `auth_type: "system_oauth"` will not work - OneDrive/SharePoint file access may fail - Profile picture refresh from Microsoft will fail --- ### Recommended Documentation Update **File:** `docs/features/sso.md` (Microsoft section) **Current documentation shows:** ``` OAUTH_SCOPES - Scopes to request. Defaults to openid email profile ``` **Suggested addition:** > **Token Refresh Support** > > To enable automatic token refresh and prevent session expiration after ~1 hour, add the `offline_access` scope: > > ```bash > OAUTH_SCOPES=openid email profile offline_access > MICROSOFT_OAUTH_SCOPE=openid email profile offline_access > ``` > > The `offline_access` scope instructs Microsoft to return a refresh token, which Open WebUI uses to automatically obtain new access tokens before they expire. This is required for: > - Long-running sessions without re-authentication > - MCP tool servers using `system_oauth` authentication > - OneDrive/SharePoint integration > - Automatic profile picture updates > > **Note:** No additional configuration is required in Microsoft Entra ID. The `offline_access` scope is available by default for web applications with client secrets. --- ### References - [Microsoft Identity Platform Scopes Documentation](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc#the-offline_access-scope) > *"On the Microsoft identity platform (requests made to the v2.0 endpoint), your app must explicitly request the `offline_access` scope, to receive refresh tokens."* - Open WebUI OAuth middleware: `backend/open_webui/utils/oauth.py` - `_perform_token_refresh()` method requires refresh token to function --- ### Impact - **User Experience:** Eliminates need to re-authenticate every hour when using Microsoft integrations - **Log Cleanliness:** Removes repetitive warning messages - **Feature Completeness:** Ensures MCP and OneDrive integrations work reliably - **Security:** Uses standard OAuth refresh flow rather than forcing frequent re-authentication

yindo closed this issue

2026-02-15 17:15:22 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: open-webui/docs#148

Issue: Document offline_access Scope for Microsoft OAuth Summary #148

Issue: Document offline_access Scope for Microsoft OAuth