diff --git a/pages/docs/configuration/authentication/OAuth2-OIDC/authentik.mdx b/pages/docs/configuration/authentication/OAuth2-OIDC/authentik.mdx index 1bc5796f3..61a040b84 100644 --- a/pages/docs/configuration/authentication/OAuth2-OIDC/authentik.mdx +++ b/pages/docs/configuration/authentication/OAuth2-OIDC/authentik.mdx @@ -6,13 +6,15 @@ description: Learn how to configure LibreChat to use Authentik for user authenti # Authentik 1. **Access Authentik Admin Interface:** + - Open the Authentik Admin Interface in your browser. Can be found at a URL such as: `https://authentik.example.com/if/admin/#/administration/overview`. -> We will use `https://authentik.example.com` as an example URL. Replace this with the URL of your Authentik instance. + > We will use `https://authentik.example.com` as an example URL. Replace this with the URL of your Authentik instance. 2. **Create a new Application and Provider using the wizard:** + - Click on the Applications tab in the left sidebar and click on Applications again. - At the top of the page you should see a button that says `Create with Wizard`. Click on it. -> Note: You can also create an application and provider manually just be sure to link them afterwards. + > Note: You can also create an application and provider manually just be sure to link them afterwards. - You can name the application whatever you want. For this example, we will name it `LibreChat` and click next. - Choose the `OAuth2/OIDC` provider and click next. - Choose your authentication and authorization flows. @@ -20,17 +22,20 @@ description: Learn how to configure LibreChat to use Authentik for user authenti - Under Advanced protocol settings change Subject mode to `Based on the User's Email`. - Click Submit. - Add the new application you created to an Outpost. -> Note: You should also apply any policies for access control that you want to apply to LibreChat at this point. + > Note: You should also apply any policies for access control that you want to apply to LibreChat at this point. 3. **Gather Information for .env:** + - You will need the following information from Authentik: - `Client ID` - `Client Secret` - `OpenID Configuration URL` - > All of these can be found by clicking on the provider you just created. + > All of these can be found by clicking on the provider you just created. 3. **Configure LibreChat:** + - Open the `.env` file and add the following variables: + ```bash filename=".env" OPENID_ISSUER=https://authentik.example.com/application/o/librechat/.well-known/openid-configuration OPENID_CLIENT_ID=[YourClientID] @@ -41,15 +46,20 @@ OPENID_SCOPE=openid profile email # Optional customization below OPENID_BUTTON_LABEL=Login with Authentik OPENID_IMAGE_URL=https://cdn.jsdelivr.net/gh/selfhst/icons/png/authentik.png +# Generate nonce for federated identity providers that require it, i.e. Cognito configured with Entra as an OIDC provider. +OPENID_GENERATE_NONCE=true # Redirects the user to the end session endpoint after logging out -OPENID_USE_END_SESSION_ENDPOINT=true +OPENID_USE_END_SESSION_ENDPOINT=true ``` + > Note: Make sure nothing is wrapped in quotes in your .env and you have allowed social login. 4. **Check Configuration:** + - Restart LibreChat to apply the changes. - Open an Icognito window and navigate to your LibreChat instance. - Underneath the form login there should be a new button that says `Login with Authentik`. - You should be redirected to Authentik to login. - After logging in you should be redirected back to LibreChat and be logged in. - - If you are not redirected back to LibreChat, check Authentik logs for any errors. \ No newline at end of file + - If you are not redirected back to LibreChat, check Authentik logs for any errors. + diff --git a/pages/docs/configuration/authentication/OAuth2-OIDC/aws.mdx b/pages/docs/configuration/authentication/OAuth2-OIDC/aws.mdx index f0e6ab008..752fa3e4a 100644 --- a/pages/docs/configuration/authentication/OAuth2-OIDC/aws.mdx +++ b/pages/docs/configuration/authentication/OAuth2-OIDC/aws.mdx @@ -54,6 +54,7 @@ Under `Advanced app client settings` make sure `Profile` is included in the `Ope ![image](https://github.com/danny-avila/LibreChat/assets/32828263/5b035eae-4a8e-482c-abd5-29cee6502eeb) ## Review and create + You can now make last minute changes, click on `Create user pool` when you're done reviewing the configuration ![image](https://github.com/danny-avila/LibreChat/assets/32828263/dc8b2374-9adb-4065-85dc-a087d625372d) @@ -75,11 +76,11 @@ You can now make last minute changes, click on `Create user pool` when you're do ![image](https://github.com/danny-avila/LibreChat/assets/32828263/dc8ae403-cbff-4aae-9eee-42d7cf3485e7) ![image](https://github.com/danny-avila/LibreChat/assets/32828263/d606f5c8-c60b-4d20-bdb2-d0d69e49ea1e) -3. Go to the `App Integrations` tab +3. Go to the `App Integrations` tab ![image](https://github.com/danny-avila/LibreChat/assets/32828263/58713bdc-24bc-47de-bdca-020dc321e997) -4. Open the app client +4. Open the app client ![image](https://github.com/danny-avila/LibreChat/assets/32828263/271bf7d2-3df2-43a7-87fc-e50294e49b2e) @@ -109,8 +110,14 @@ OPENID_SCOPE=openid profile email OPENID_CALLBACK_URL=/oauth/openid/callback # Optional: redirects the user to the end session endpoint after logging out -OPENID_USE_END_SESSION_ENDPOINT=true +OPENID_USE_END_SESSION_ENDPOINT=true +# Optional: generates the nonce url parameter. +OPENID_GENERATE_NONCE=true ``` + +> [!WARNING] +> If Cognito is configured with an OIDC provider, i.e. federation to Entra, the `OPENID_GENERATE_NONCE=true` is required. Otherwise Cognito will generate it regardless and the claims validation will fail since the client didn't provide one. + 7. Save the .env file > Note: If using docker, run `docker compose up -d` to apply the .env configuration changes diff --git a/pages/docs/configuration/authentication/OAuth2-OIDC/index.mdx b/pages/docs/configuration/authentication/OAuth2-OIDC/index.mdx index 0175e1a39..761459955 100644 --- a/pages/docs/configuration/authentication/OAuth2-OIDC/index.mdx +++ b/pages/docs/configuration/authentication/OAuth2-OIDC/index.mdx @@ -18,17 +18,20 @@ This section will cover how to configure OAuth2 and OpenID Connect with LibreCha ## OAuth2 - - [Apple](/docs/configuration/authentication/OAuth2-OIDC/apple) - - [Discord](/docs/configuration/authentication/OAuth2-OIDC/discord) - - [Facebook](/docs/configuration/authentication/OAuth2-OIDC/facebook) - - [GitHub](/docs/configuration/authentication/OAuth2-OIDC/github) - - [Google](/docs/configuration/authentication/OAuth2-OIDC/google) + +- [Apple](/docs/configuration/authentication/OAuth2-OIDC/apple) +- [Discord](/docs/configuration/authentication/OAuth2-OIDC/discord) +- [Facebook](/docs/configuration/authentication/OAuth2-OIDC/facebook) +- [GitHub](/docs/configuration/authentication/OAuth2-OIDC/github) +- [Google](/docs/configuration/authentication/OAuth2-OIDC/google) + ## OpenID Connect - - [Auth0](/docs/configuration/authentication/OAuth2-OIDC/auth0) - - [AWS Cognito](/docs/configuration/authentication/OAuth2-OIDC/aws) - - [Azure Entra/AD](/docs/configuration/authentication/OAuth2-OIDC/azure) - - [Keycloak](/docs/configuration/authentication/OAuth2-OIDC/keycloak) - - [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse) + +- [Auth0](/docs/configuration/authentication/OAuth2-OIDC/auth0) +- [AWS Cognito](/docs/configuration/authentication/OAuth2-OIDC/aws) +- [Azure Entra/AD](/docs/configuration/authentication/OAuth2-OIDC/azure) +- [Keycloak](/docs/configuration/authentication/OAuth2-OIDC/keycloak) +- [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse) ## Troubleshooting OpenID Connect @@ -38,4 +41,6 @@ If you encounter issues with OpenID Connect authentication: 2. **Check Redirect URIs**: Ensure your callback URL matches exactly between your provider and LibreChat configuration 3. **Verify Scopes**: Make sure all required scopes are properly configured 4. **Review Provider Logs**: Check your identity provider's logs for authentication errors -5. **Validate Tokens**: Ensure your provider is issuing valid tokens with the expected claims \ No newline at end of file +5. **Validate Tokens**: Ensure your provider is issuing valid tokens with the expected claims +6. **Ensure _nonce_ is generated**: Some identity providers generate `nonce` url parameter if it's missing in the request. Set `OPENID_GENERATE_NONCE=true` to force the openid-client to generate it. + diff --git a/pages/docs/configuration/dotenv.mdx b/pages/docs/configuration/dotenv.mdx index 00c252cda..a8a928cd8 100644 --- a/pages/docs/configuration/dotenv.mdx +++ b/pages/docs/configuration/dotenv.mdx @@ -266,6 +266,7 @@ For detailed configuration and customization options, see: [Web Search Configura ['FIRECRAWL_API_URL', 'string', 'Custom Firecrawl API URL (optional). Only needed for custom Firecrawl instances.', '# FIRECRAWL_API_URL='], ['JINA_API_KEY', 'string', 'API key for Jina reranker service. Get your key from https://jina.ai/api-dashboard/', '# JINA_API_KEY='], ['COHERE_API_KEY', 'string', 'API key for Cohere reranker service. Get your key from https://dashboard.cohere.com/welcome/login', '# COHERE_API_KEY='], + ['COHERE_BASE_URL', 'string', 'Custom Cohere API base URL (optional). Only needed for custom Cohere endpoints or proxies.', '# COHERE_BASE_URL='], ]} /> diff --git a/pages/docs/configuration/librechat_yaml/object_structure/web_search.mdx b/pages/docs/configuration/librechat_yaml/object_structure/web_search.mdx index 5ece6555b..9912cba76 100644 --- a/pages/docs/configuration/librechat_yaml/object_structure/web_search.mdx +++ b/pages/docs/configuration/librechat_yaml/object_structure/web_search.mdx @@ -28,6 +28,7 @@ webSearch: # Reranker Configuration jinaApiKey: "${JINA_API_KEY}" cohereApiKey: "${COHERE_API_KEY}" + cohereApiUrl: "${COHERE_BASE_URL}" rerankerType: "jina" # Options: "jina", "cohere" # General Settings @@ -295,6 +296,16 @@ webSearch: **Note:** Get your API key from [Cohere Dashboard](https://dashboard.cohere.com/welcome/login) +### cohereApiUrl + + + +**Note:** This is optional and only needed if you're using a custom Cohere endpoint or proxy. + ### rerankerType