From c7cbb93bfeeb08f597f1392a1672c13455b95e82 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Fri, 23 May 2025 17:16:29 -0400 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20docs:=20Add=20OpenID=20Connect=20to?= =?UTF-8?q?ken=20reuse=20feature=20documentation=20(#308)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Introduced a new section on reusing access and refresh tokens from OpenID Connect providers, specifically for Azure Entra ID. - Added detailed configuration steps and environment variables for enabling token reuse. - Created a dedicated page for "Re-use OpenID Tokens for Login Session" with prerequisites and troubleshooting tips. - Updated existing documentation to reference the new token reuse feature. --- .../authentication/OAuth2-OIDC/azure.mdx | 6 + .../authentication/OAuth2-OIDC/index.mdx | 3 +- .../OAuth2-OIDC/token-reuse.mdx | 103 ++++++++++++++++++ pages/docs/configuration/dotenv.mdx | 22 +++- 4 files changed, 132 insertions(+), 2 deletions(-) create mode 100644 pages/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx diff --git a/pages/docs/configuration/authentication/OAuth2-OIDC/azure.mdx b/pages/docs/configuration/authentication/OAuth2-OIDC/azure.mdx index 8773404..7fc840c 100644 --- a/pages/docs/configuration/authentication/OAuth2-OIDC/azure.mdx +++ b/pages/docs/configuration/authentication/OAuth2-OIDC/azure.mdx @@ -63,3 +63,9 @@ OPENID_USE_END_SESSION_ENDPOINT=true > Note: If using docker, run `docker compose up -d` to apply the .env configuration changes +## Advanced: Token Reuse + +LibreChat supports reusing Azure Entra ID tokens for session management, which can provide better integration with your Azure environment. This feature allows LibreChat to use Azure's refresh tokens instead of managing its own session tokens. + +To learn more about this feature and how to configure it, see [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse). + diff --git a/pages/docs/configuration/authentication/OAuth2-OIDC/index.mdx b/pages/docs/configuration/authentication/OAuth2-OIDC/index.mdx index 9815145..fefa2bf 100644 --- a/pages/docs/configuration/authentication/OAuth2-OIDC/index.mdx +++ b/pages/docs/configuration/authentication/OAuth2-OIDC/index.mdx @@ -26,4 +26,5 @@ This section will cover how to configure OAuth2 and OpenID Connect with LibreCha ## OpenID Connect - [AWS Cognito](/docs/configuration/authentication/OAuth2-OIDC/aws) - [Azure Entra/AD](/docs/configuration/authentication/OAuth2-OIDC/azure) - - [Keycloak](/docs/configuration/authentication/OAuth2-OIDC/keycloak) \ No newline at end of file + - [Keycloak](/docs/configuration/authentication/OAuth2-OIDC/keycloak) + - [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse) \ No newline at end of file diff --git a/pages/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx b/pages/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx new file mode 100644 index 0000000..d11a053 --- /dev/null +++ b/pages/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx @@ -0,0 +1,103 @@ +--- +title: OpenID Connect Token Reuse +description: How to configure OpenID Connect token reuse with LibreChat +--- + +# OpenID Connect Token Reuse + +LibreChat supports reusing access and refresh tokens issued by your OpenID Connect provider (like Azure Entra ID) to manage user authentication state. When this feature is active, the refresh token passed to the user as a cookie is issued by your OpenID provider instead of LibreChat, allowing LibreChat servers to refresh it and request access tokens from your provider. + +## Prerequisites + +- A configured OpenID Connect provider (like Azure Entra ID) +- Basic OpenID Connect setup completed + +## Configuration Steps + +1. Set `OPENID_REUSE_TOKENS=true` in your environment variables. + +2. Configure your OpenID provider (using Azure Entra ID as an example): + - Go to the Azure Portal and navigate to your app registration + - Click on "Expose API" in the left menu + - Click "Add" next to "Application ID URI" + - Enter your API URI (e.g., "api://librechat") and save + +![image](https://github.com/user-attachments/assets/95bcd3ef-ed54-4002-9c74-a98d15673e71) + +3. Create an API scope: + - In the "Expose API" section, click "Add a scope" + - Configure the scope with appropriate permissions + - Save the scope configuration + +![image](https://github.com/user-attachments/assets/6f7a7170-92cd-4816-a1a8-dcacb592c893) + +4. Configure API permissions: + - Go to "API permissions" in the left menu + - Click "Add a permission" + - Under "APIs my organization uses", search for your app + - Select "Delegated permissions" and choose the appropriate scope (e.g., "access_user") + +![image](https://github.com/user-attachments/assets/d0b23d65-ae39-4eb8-9f4d-97f18c627045) + +![image](https://github.com/user-attachments/assets/67d09375-5b80-45e2-89e6-3bd0a00288e4) + +![image](https://github.com/user-attachments/assets/1f85ae5e-4be2-4a68-b663-4152f32fa108) + +5. Set the required scope in your environment: + ```bash filename=".env" + OPENID_SCOPE=api://librechat/.default openid profile email offline_access + ``` + Note: The `offline_access` scope is required to obtain a refresh token for reuse. + +6. Grant admin consent: + - Go to Enterprise Applications in Azure Portal + - Find your LibreChat application + - Navigate to Security > Permissions + - Click "Grant admin consent" + +![image](https://github.com/user-attachments/assets/d3a8b1f3-0f0a-4a90-92d9-9df91e665c8d) + +7. Accept the requested permissions in the popup + +![image](https://github.com/user-attachments/assets/cc3eb15a-994e-49fb-b212-f94260d787d3) + +8. Clear LibreChat cache and restart the service. + +## Environment Variables + +```bash filename=".env" +# OpenID Token Reuse Configuration +OPENID_REUSE_TOKENS=true +OPENID_SCOPE=api://librechat/.default openid profile email offline_access +OPENID_JWKS_URL_CACHE_ENABLED=true +OPENID_JWKS_URL_CACHE_TIME=600000 # 10 minutes in milliseconds +OPENID_ON_BEHALF_FLOW_FOR_USERINFRO_REQUIRED=true +OPENID_ON_BEHALF_FLOW_USERINFRO_SCOPE=user.read +OPENID_USE_END_SESSION_ENDPOINT=true +``` + +## Additional Configuration Options + +- `OPENID_JWKS_URL_CACHE_ENABLED`: Enables caching of signing key verification results to prevent excessive HTTP requests to the JWKS endpoint +- `OPENID_JWKS_URL_CACHE_TIME`: Cache duration in milliseconds (default: 600000 ms / 10 minutes) +- `OPENID_ON_BEHALF_FLOW_FOR_USERINFRO_REQUIRED`: Enables on-behalf-of flow for user info +- `OPENID_ON_BEHALF_FLOW_USERINFRO_SCOPE`: Scope for user info in on-behalf-of flow +- `OPENID_USE_END_SESSION_ENDPOINT`: Enables use of the end session endpoint for logout + +## Security Considerations + +- Ensure proper token storage and handling +- Implement appropriate token refresh mechanisms +- Monitor token usage and implement rate limiting if necessary +- Regularly rotate client secrets +- Use secure cookie settings for token storage + +## Troubleshooting + +If you encounter issues with token reuse: + +1. Verify all required scopes are properly configured +2. Check that admin consent has been granted +3. Ensure the API permissions are correctly set up +4. Verify the token cache is working as expected +5. Check the application logs for any authentication errors \ No newline at end of file diff --git a/pages/docs/configuration/dotenv.mdx b/pages/docs/configuration/dotenv.mdx index d2cd95e..1319c50 100644 --- a/pages/docs/configuration/dotenv.mdx +++ b/pages/docs/configuration/dotenv.mdx @@ -995,6 +995,26 @@ For more information: ]} /> +##### OpenID Connect Token Reuse + +LibreChat supports reusing access and refresh tokens issued by your OpenID Connect provider (like Azure Entra ID) to manage user authentication state. When this feature is active, the refresh token passed to the user as a cookie is issued by your OpenID provider instead of LibreChat. + + + + +For detailed configuration steps and prerequisites, see [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse). + + #### [LDAP/AD Authentication](/docs/configuration/authentication/ldap) For more information: **[LDAP/AD Authentication](/docs/configuration/authentication/ldap)** @@ -1170,4 +1190,4 @@ If you are using Redis, you will need to set the following variables: ['REDIS_KEY_PREFIX', 'string', 'Prefix for Redis keys', '# REDIS_KEY_PREFIX="librechat-staging:"'], ['REDIS_MAX_LISTENERS', 'number', 'Maximum number of event listeners allowed for the Redis client instance', '# REDIS_MAX_LISTENERS=20'], ]} -/> +/> \ No newline at end of file