Reutilização de Token OpenID Connect

O LibreChat oferece suporte à reutilização de tokens de acesso e de atualização emitidos pelo seu provedor OpenID Connect (como Azure Entra ID ou Auth0) para gerenciar o estado de autenticação do usuário. Quando este recurso está ativo, o token de atualização passado ao usuário como um cookie é emitido pelo seu provedor OpenID em vez do LibreChat, permitindo que os servidores do LibreChat o atualizem e solicitem tokens de acesso ao seu provedor.

Pré-requisitos

• Um provedor OpenID Connect configurado (como Azure Entra ID, Auth0, etc.)
• Configuração básica do OpenID Connect concluída

Etapas de Configuração

1. Defina OPENID_REUSE_TOKENS=true em suas variáveis de ambiente.

Configuração Específica do Provedor

Configuração do Auth0

Para o Auth0, você precisa:

1. Crie uma API no Auth0 (necessário para tokens de acesso JWT):

   • Vá para Auth0 Dashboard → Applications → APIs
   • Clique em "Create API"
   • Defina um Identifier (por exemplo, https://api.librechat.com)
   • Ative "Allow Offline Access" nas configurações da API

2. Defina as variáveis de ambiente necessárias:

   # Required for Auth0
   OPENID_AUDIENCE=https://api.librechat.com  # Your API identifier from Auth0
   OPENID_SCOPE=openid profile email offline_access

Para uma configuração detalhada do Auth0, veja: Configuração do Auth0 OpenID Connect

Configuração do Azure Entra ID

2. Configure seu provedor OpenID (usando o Azure Entra ID como exemplo):
   • Vá para o Azure Portal e navegue até o seu registro de aplicativo
   • Clique em "Expose API" no menu à esquerda
   • Clique em "Add" ao lado de "Application ID URI"
   • Insira seu URI de API (por exemplo, "api://librechat") e salve

3. Crie um escopo de API:
   • Na seção "Expose API", clique em "Add a scope"
   • Configure o escopo com as permissões apropriadas
   • Salvar a configuração de escopo

4. Configure as permissões da API:
   • Vá para "API permissions" no menu à esquerda
   • Clique em "Add a permission"
   • Em "APIs my organization uses", procure pelo seu aplicativo
   • Selecione "Delegated permissions" e escolha o escopo apropriado (por exemplo, "access_user")

5. Defina o escopo necessário no seu ambiente:

   OPENID_SCOPE=api://librechat/.default openid profile email offline_access

   Nota: O escopo offline_access é necessário para obter um token de atualização para reutilização.

6. Conceder consentimento de administrador:

   • Vá para Enterprise Applications no Azure Portal
   • Encontre sua aplicação LibreChat
   • Navegue até Security > Permissions
   • Clique em "Grant admin consent"

7. Aceite as permissões solicitadas no pop-up

8. Limpe o cache do LibreChat e reinicie o serviço.

Variáveis de Ambiente

# OpenID Token Reuse Configuration
OPENID_REUSE_TOKENS=true
OPENID_SCOPE=api://librechat/.default openid profile email offline_access
OPENID_REUSE_MAX_SESSION_AGE_MS=900000  # 15 minutes in milliseconds

# Required for Auth0 (use your API identifier)
# OPENID_AUDIENCE=https://api.librechat.com

# Caching Configuration
OPENID_JWKS_URL_CACHE_ENABLED=true
OPENID_JWKS_URL_CACHE_TIME=600000  # 10 minutes in milliseconds

# Azure-specific Configuration
OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true
OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE=user.read

# Logout Configuration
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

Opções de Configuração Adicionais

• OPENID_AUDIENCE: Valor de audience para validação de JWT e solicitações de autorização. Obrigatório para Auth0 para receber tokens de acesso JWT em vez de tokens opacos. Valores separados por vírgula são aceitos para validação de JWT; as solicitações de autorização usam o primeiro valor não vazio.
• OPENID_REUSE_MAX_SESSION_AGE_MS: Idade máxima que um token de sessão OpenID reutilizado é servido antes que o LibreChat force uma atualização do IdP (padrão: 900000 ms / 15 minutos). Aceita expressões aritméticas como 60 * 60 * 24 * 1000. Aumente esse valor em direção ao tempo de vida do access-token do seu IdP caso seu provedor revogue o access-token anterior sempre que ele for atualizado.
• OPENID_JWKS_URL_CACHE_ENABLED: Habilita o cache dos resultados de verificação da chave de assinatura para evitar solicitações HTTP excessivas ao endpoint JWKS
• OPENID_JWKS_URL_CACHE_TIME: Duração do cache em milissegundos (padrão: 600000 ms / 10 minutos)
• OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED: Habilita o fluxo on-behalf-of para informações do usuário (específico para Azure)
• OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE: Escopo para informações do usuário no fluxo on-behalf-of (específico para Azure)
• OPENID_USE_END_SESSION_ENDPOINT: Habilita o uso do endpoint de encerramento de sessão para logout
• OPENID_MAX_LOGOUT_URL_LENGTH: Comprimento máximo da URL antes de usar logout_hint em vez de id_token_hint para evitar erros de URI muito longa (padrão: 2000)

Considerações de Segurança

• Garanta o armazenamento e manuseio adequados de tokens
• Implemente mecanismos apropriados de atualização de token
• Monitore o uso de tokens e implemente limites de taxa (rate limiting), se necessário
• Rotacione regularmente os client secrets
• Use configurações de cookie seguras para o armazenamento de tokens

Solução de problemas

Se você encontrar problemas com a reutilização de tokens:

1. Verifique se todos os escopos necessários estão configurados corretamente
2. Verifique se o consentimento do administrador foi concedido
3. Certifique-se de que as permissões da API estejam configuradas corretamente
4. Verifique se o cache de tokens está funcionando conforme o esperado
5. Verifique os logs da aplicação para quaisquer erros de autenticação
6. Ative o registro detalhado de cabeçalhos de solicitação OpenID definindo DEBUG_OPENID_REQUESTS=true em suas variáveis de ambiente para visualizar os cabeçalhos de solicitação além das URLs (com dados confidenciais mascarados).