From 5d6a460d9aa898cf256ae630ca709749a8684790 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B3n=20Levy?= Date: Fri, 4 Sep 2026 15:42:13 +0000 Subject: [PATCH 1/2] docs(auth): add OpenID Connect token placeholders and OPENID_EXPOSE_SUB_COOKIE documentation - Add OPENID_EXPOSE_SUB_COOKIE environment variable documentation in token-reuse.mdx - Add table of seven available OpenID token placeholders in custom_endpoint.mdx - Document placeholders: access token, ID token, user ID, email, name, and expiration - Add practical usage example showing OpenID tokens in custom endpoint headers - Explain cross-origin OAuth callback flow support for advanced authentication scenarios --- .../OAuth2-OIDC/token-reuse.mdx | 4 +++ .../object_structure/custom_endpoint.mdx | 27 +++++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/content/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx b/content/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx index c39f34505..4afa67e59 100644 --- a/content/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx +++ b/content/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx @@ -127,6 +127,9 @@ OPENID_USE_END_SESSION_ENDPOINT=true # Maximum logout URL length before using logout_hint instead of id_token_hint (default: 2000) # OPENID_MAX_LOGOUT_URL_LENGTH=2000 + +# Cross-origin OAuth Callback Support (optional, independent of OPENID_REUSE_TOKENS) +# OPENID_EXPOSE_SUB_COOKIE=true ``` ## Additional Configuration Options @@ -141,6 +144,7 @@ OPENID_USE_END_SESSION_ENDPOINT=true - `GRAPH_API_SCOPES`: Space-separated Microsoft Graph scopes requested when resolving `{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}` in a YAML-defined MCP server. Defaults to `https://graph.microsoft.com/.default`; this is separate from the `OPENID_GRAPH_SCOPES` used for people and group search. - `OPENID_USE_END_SESSION_ENDPOINT`: Enables use of the end session endpoint for logout - `OPENID_MAX_LOGOUT_URL_LENGTH`: Maximum URL length before using `logout_hint` instead of `id_token_hint` to prevent URI too long errors (default: 2000) +- `OPENID_EXPOSE_SUB_COOKIE`: Exposes a JWT-signed cookie containing the OpenID `sub` claim with `sameSite=lax`. This enables cross-origin OAuth callback flows (e.g., AWS Bedrock AgentCore 3LO). Can be used independently of `OPENID_REUSE_TOKENS`. ## Security Considerations diff --git a/content/docs/configuration/librechat_yaml/object_structure/custom_endpoint.mdx b/content/docs/configuration/librechat_yaml/object_structure/custom_endpoint.mdx index 177e88b2f..378ec2dc8 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/custom_endpoint.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/custom_endpoint.mdx @@ -827,6 +827,33 @@ headers: X-Message-ID: '{{LIBRECHAT_BODY_MESSAGEID}}' ``` +**Available OpenID Token Placeholders:** + +These placeholders are available when using OpenID Connect authentication. They extract values from the OpenID tokens stored in the user's session. + +| Placeholder | Description | +| --- | --- | +| `{{LIBRECHAT_OPENID_TOKEN}}` | OpenID access token (generic alias for ACCESS_TOKEN) | +| `{{LIBRECHAT_OPENID_ACCESS_TOKEN}}` | OpenID access token | +| `{{LIBRECHAT_OPENID_ID_TOKEN}}` | OpenID ID token | +| `{{LIBRECHAT_OPENID_USER_ID}}` | User ID from OpenID claims (sub claim or openidId) | +| `{{LIBRECHAT_OPENID_USER_EMAIL}}` | User email from OpenID claims | +| `{{LIBRECHAT_OPENID_USER_NAME}}` | User name from OpenID claims | +| `{{LIBRECHAT_OPENID_EXPIRES_AT}}` | Token expiration timestamp (Unix epoch seconds) | + + +These placeholders require OpenID Connect authentication to be configured. The token values are extracted from the `federatedTokens` or `openidTokens` properties on the user object, which are populated during the OpenID authentication flow. + + +**Example using OpenID token placeholders:** + +```yaml filename="endpoints / custom / headers with OpenID tokens" +headers: + Authorization: "Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}" + X-ID-Token: "{{LIBRECHAT_OPENID_ID_TOKEN}}" + X-User-Sub: "{{LIBRECHAT_OPENID_USER_ID}}" +``` + ## directEndpoint **Key:** From 2b0e79010da599a5735943617242f7d137ae18e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B3n=20Levy?= Date: Mon, 7 Sep 2026 10:58:23 +0000 Subject: [PATCH 2/2] docs: document OPENID_SUB_SECRET and session-bound openid_sub cookie --- .../configuration/authentication/OAuth2-OIDC/token-reuse.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/content/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx b/content/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx index 4afa67e59..fac985a79 100644 --- a/content/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx +++ b/content/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx @@ -130,6 +130,8 @@ OPENID_USE_END_SESSION_ENDPOINT=true # Cross-origin OAuth Callback Support (optional, independent of OPENID_REUSE_TOKENS) # OPENID_EXPOSE_SUB_COOKIE=true +# Optional dedicated signing key for openid_sub cookie (defaults to JWT_REFRESH_SECRET) +# OPENID_SUB_SECRET= ``` ## Additional Configuration Options @@ -144,7 +146,8 @@ OPENID_USE_END_SESSION_ENDPOINT=true - `GRAPH_API_SCOPES`: Space-separated Microsoft Graph scopes requested when resolving `{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}` in a YAML-defined MCP server. Defaults to `https://graph.microsoft.com/.default`; this is separate from the `OPENID_GRAPH_SCOPES` used for people and group search. - `OPENID_USE_END_SESSION_ENDPOINT`: Enables use of the end session endpoint for logout - `OPENID_MAX_LOGOUT_URL_LENGTH`: Maximum URL length before using `logout_hint` instead of `id_token_hint` to prevent URI too long errors (default: 2000) -- `OPENID_EXPOSE_SUB_COOKIE`: Exposes a JWT-signed cookie containing the OpenID `sub` claim with `sameSite=lax`. This enables cross-origin OAuth callback flows (e.g., AWS Bedrock AgentCore 3LO). Can be used independently of `OPENID_REUSE_TOKENS`. +- `OPENID_EXPOSE_SUB_COOKIE`: Exposes a JWT-signed cookie (`openid_sub`) containing the OpenID `sub` claim with `sameSite=lax`. This enables cross-origin OAuth callback flows (e.g., AWS Bedrock AgentCore 3LO). Can be used independently of `OPENID_REUSE_TOKENS`. The token payload includes `typ: "openid_sub"` and is session-bound via `refreshTokenHash`. +- `OPENID_SUB_SECRET`: Optional dedicated signing key for the `openid_sub` cookie. If unset, defaults to `JWT_REFRESH_SECRET`. Recommended when external callback consumers (e.g., AWS Lambda) need to verify the token without access to `JWT_REFRESH_SECRET`. ## Security Considerations