Saltar para o conteúdo principal
Este recurso foi desenvolvido por yu-i-i/overleaf-cep. Aqui disponibilizamos alguns documentos para a sua configuração.

Configuração

Internamente, o módulo OIDC do Overleaf usa a biblioteca passport-openidconnect. Se você estiver tendo problemas para configurar o OpenID Connect, vale a pena ler o README do passport-openidconnect para ter uma ideia da configuração que ele espera. A variável de ambiente EXTERNAL_AUTH é necessária para ativar o módulo de autenticação OIDC. Esta variável de ambiente especifica quais métodos de autenticação externa estão ativados. O valor desta variável é uma lista. Se a lista incluir oidc, a autenticação OIDC será ativada. Por exemplo: EXTERNAL_AUTH=ldap oidc Ao usar o método de autenticação OIDC, o usuário é redirecionado para o site de autenticação do provedor de identidade (IdP). Se o IdP autenticar o usuário com sucesso, o banco de dados de usuários do Overleaf é verificado em busca de um registro que contenha um campo thirdPartyIdentifiers estruturado da seguinte forma:
O externalUserId deve corresponder ao ID de usuário no perfil retornado pelo servidor do IdP (consulte a variável de ambiente OVERLEAF_OIDC_USER_ID_FIELD), e o providerId deve corresponder ao ID do provedor OIDC (consulte OVERLEAF_OIDC_PROVIDER_ID). Se nenhum registro correspondente for encontrado, o banco de dados é pesquisado em busca de um usuário cujo endereço de e-mail principal corresponda ao e-mail no perfil de usuário do IdP:
  • Se esse usuário for encontrado, o campo thirdPartyIdentifiers é atualizado.
  • Se nenhum usuário correspondente for encontrado e a criação de contas JIT não estiver desativada, um novo usuário é criado com o endereço de e-mail e os thirdPartyIdentifiers do perfil do IdP.
Em ambos os casos, diz-se que o usuário está “vinculado” ao usuário OIDC externo. O usuário pode ser desvinculado do provedor OIDC na página /user/settings.

Encontrando os valores com o documento de descoberta

Todo provedor OpenID (OP) publica um documento de descoberta em <issuer>/.well-known/openid-configuration. Copie os valores dele em vez de digitá-los manualmente; um único caractere errado basta para quebrar o login.
1

Encontrar a URL de descoberta

O seu OP a mostra na página do cliente (provedor) que você criou para o Overleaf. No Authentik, abra Applications > Providers, selecione o provedor e procure OpenID Configuration URL e OpenID Configuration Issuer:

Authentik: a URL de descoberta e o issuer de um provedor (instância de teste)

A URL geralmente tem esta aparência:
  • Keycloak: https://keycloak.example.com/realms/<realm>/.well-known/openid-configuration
  • Authentik: https://authentik.example.com/application/o/<application-slug>/.well-known/openid-configuration
2

Ler os valores

Abra a URL em um navegador ou execute no servidor do Overleaf:
A resposta do Authentik tem esta aparência:
O Authentik também lista essas URLs mais abaixo na página do provedor:

Authentik: os endpoints de um provedor (instância de teste)

3

Copiá-los para o variables.env

4

Verificar se o Overleaf consegue alcançar o OP

O Overleaf chama os endpoints de token e de userinfo de dentro do seu contêiner, portanto o OP deve estar acessível a partir dali, e não apenas a partir do seu navegador:
Deve imprimir 200.
Copie o issuer exatamente, incluindo a barra final. O Overleaf o compara caractere por caractere com o issuer no ID token; qualquer diferença faz com que todo login OIDC falhe com:{"message":{"message":"ID token not issued by expected OpenID provider."}}No Authentik, o issuer pertence à aplicação (.../application/o/<application-slug>/). Ele não é o endereço do servidor Authentik, embora as URLs de authorize, token e userinfo sejam compartilhadas por todas as aplicações.

Variáveis de ambiente

Os valores das cinco variáveis obrigatórias a seguir podem ser encontrados usando o endpoint .well-known/openid-configuration do seu provedor OpenID (OP), veja acima.
  • OVERLEAF_OIDC_ISSUER (obrigatória)
  • OVERLEAF_OIDC_AUTHORIZATION_URL (obrigatória)
  • OVERLEAF_OIDC_TOKEN_URL (obrigatória)
  • OVERLEAF_OIDC_USER_INFO_URL (obrigatória)
  • OVERLEAF_OIDC_LOGOUT_URL (obrigatória)
Os valores das duas variáveis obrigatórias a seguir serão fornecidos pelo administrador do seu OP
  • OVERLEAF_OIDC_CLIENT_ID (obrigatória)
  • OVERLEAF_OIDC_CLIENT_SECRET (obrigatória)
  • OVERLEAF_OIDC_SCOPE
    • Padrão: openid profile email
  • OVERLEAF_OIDC_PROVIDER_ID
    • ID arbitrário do OP; o padrão é oidc.
  • OVERLEAF_OIDC_PROVIDER_NAME
    • O nome do OP, usado na seção Linked Accounts da página /user/settings; o padrão é OIDC Provider.
  • OVERLEAF_OIDC_IDENTITY_SERVICE_NAME
    • Nome de exibição do serviço de identidade, usado na página de login (padrão: Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
  • OVERLEAF_OIDC_PROVIDER_DESCRIPTION
    • Descrição do OP, usada na seção Linked Accounts (padrão: Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
  • OVERLEAF_OIDC_PROVIDER_INFO_LINK
    • URL de Learn more na descrição do OP; padrão: nenhum link Learn more na descrição.
  • OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED
    • Não mostrar o OP na página /user/settings se a conta do usuário não estiver vinculada ao OP; padrão false.
  • OVERLEAF_OIDC_USER_ID_FIELD
    • O valor deste atributo será usado pelo Overleaf como ID de usuário externo; o padrão é id. Outros valores razoáveis possíveis são email e username (correspondente à claim OIDC preferred_username).
  • OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS
    • Restringe a criação de contas Just-in-Time (JIT) para usuários que se autenticam via OIDC. Se definida como uma lista de nomes de domínio separados por vírgulas, uma nova conta só será criada se o domínio do endereço de e-mail do usuário corresponder a um dos domínios listados. Se o domínio não corresponder, um administrador deverá criar manualmente a conta do usuário usando o endereço de e-mail do usuário OIDC, com uma senha aleatória forte ou, de preferência, sem o campo hashedPassword. Os nomes de domínio podem incluir um curinga *. no início para corresponder a subdomínios.
      • Exemplo: para permitir a criação de contas JIT para usuários com endereços de e-mail como name@example.com e name@math.example.com:
        OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com
      • Exemplo: para desativar completamente a criação de contas JIT:
        OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=
  • OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN
    • Se definida como true, atualiza os campos first_name e last_name do usuário no login e desativa o formulário de dados do usuário na página /user/settings.
  • OVERLEAF_OIDC_IS_ADMIN_FIELD e OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE
    • Quando ambas as variáveis de ambiente estão definidas, o processo de login atualiza user.isAdmin = true se o perfil retornado pelo OP contiver o atributo especificado por OVERLEAF_OIDC_IS_ADMIN_FIELD e o seu valor corresponder a OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE ou for um array que contenha OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE (por exemplo, a claim groups); caso contrário, user.isAdmin é definido como false. Se OVERLEAF_OIDC_IS_ADMIN_FIELD for email, o valor do atributo emails[0].value é usado na verificação de correspondência.
A URL de redirecionamento para o seu provedor OpenID é https://my-overleaf-instance.com/oidc/login/callback.
variables.env

Passo a passo: goauthentik

Este guia percorre uma configuração testada com o goauthentik. Substitua https://overleaf.example.com pela sua OVERLEAF_SITE_URL e https://authentik.example.com pelo endereço do seu Authentik.
1

Criar o provedor

No Authentik, abra Applications > Providers, clique em New Provider, escolha OAuth2/OpenID Provider e clique em Next.
  • Client Type: Confidential.
  • Redirect URIs (em Protocol settings): adicione https://overleaf.example.com/oidc/login/callback com o modo de correspondência Strict.
  • Copie agora o Client ID e o Client Secret para OVERLEAF_OIDC_CLIENT_ID e OVERLEAF_OIDC_CLIENT_SECRET.

Authentik: Client ID e Client Secret de um novo provedor

O Authentik mostra o client secret apenas enquanto você cria o provedor. Depois, o formulário de edição oferece apenas Modify, que substitui o secret por um novo.
2

Criar a aplicação

Abra Applications > Applications, crie uma nova aplicação, dê a ela um nome e um slug, por exemplo overleaf, e selecione o provedor. O slug passa a fazer parte do issuer: https://authentik.example.com/application/o/overleaf/.
3

Copiar as URLs

Siga Encontrando os valores com o documento de descoberta acima para preencher as cinco URLs.
4

Mapear os administradores (opcional)

O Authentik envia os grupos do usuário como a claim groups, um array. Para tornar os membros do grupo Admins do Authentik administradores do Overleaf:
O indicador de administrador é atualizado a cada login OIDC. Com um campo ou valor errado, todo administrador que fizer login via OIDC perde os direitos de administrador, incluindo o administrador criado no launchpad. Teste o mapeamento primeiro com uma segunda conta de administrador.
variables.env

Q&A

Resposta: Verifique o seguinte:
  • Versão. Antes da v6.3.0, o Overleaf não lia claims personalizadas como groups, então só OVERLEAF_OIDC_IS_ADMIN_FIELD=email funcionava. Atualize para a v6.3.0 ou posterior.
  • A claim precisa estar na resposta de UserInfo. O Overleaf lê a claim de OVERLEAF_OIDC_USER_INFO_URL, não do ID token. Se o seu OP adiciona a claim apenas ao ID token, adicione-a também ao UserInfo, por exemplo com Add to userinfo em um mapper do Keycloak.
  • O valor precisa corresponder exatamente, incluindo maiúsculas e minúsculas, por exemplo Admins.
O status de administrador é verificado novamente a cada login: um usuário que foi tornado administrador no painel de administração perde esse status no próximo login se a claim não corresponder.
Resposta: Não. O GitHub suporta OAuth 2.0, mas não OpenID Connect para login de usuários: ele não retorna um ID token, que o Overleaf exige, então o login falha com ID token not present in token response.Para permitir que os usuários façam login com a conta do GitHub, use um provedor de identidade como o goauthentik ou o Keycloak, com o GitHub como origem de login, e conecte o Overleaf a esse provedor com OIDC.
Resposta: Sim. O GitLab, incluindo o GitLab autogerenciado, é um provedor OpenID Connect. No GitLab, crie uma aplicação em Applications (nas configurações do seu usuário, grupo ou da área Admin) com:
  • Redirect URI: https://my-overleaf-instance.com/oidc/login/callback
  • Scopes: openid, profile e email
Em seguida, leia os endpoints em https://gitlab.com/.well-known/openid-configuration, ou no mesmo caminho do seu GitLab, conforme descrito em Encontrando os valores com o documento de descoberta. Para gitlab.com, o issuer é https://gitlab.com, sem barra final.
Resposta: Antes de redirecionar para o OP, o Overleaf armazena um valor state aleatório na sessão do usuário e o verifica quando o OP redireciona de volta. Esses erros significam que a sessão no callback não é a mesma que iniciou o login.Unable to verify authorization request state significa que o navegador não enviou o cookie de sessão de volta no callback. Verifique se:
  • Os usuários abrem o Overleaf no endereço de OVERLEAF_SITE_URL. O callback sempre vai para OVERLEAF_SITE_URL, então um login iniciado a partir de outro endereço, como http://192.168.1.20 enquanto OVERLEAF_SITE_URL é https://overleaf.example.com, perde sua sessão.
  • OVERLEAF_SECURE_COOKIE não está definido quando o Overleaf é servido por HTTP simples. Os navegadores descartam cookies seguros em HTTP. Qualquer valor o habilita, inclusive false, então remova a linha.
Invalid authorization request state significa que um login mais recente substituiu o valor armazenado, por exemplo após fazer login em duas abas ao mesmo tempo ou voltar no navegador durante o login. Feche as outras abas e inicie o login novamente pela página de login do Overleaf.
Última modificação em 2 de novembro de 2026