Autenticação OIDC

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:

thirdPartyIdentifiers: [
  {
    externalUserId: "...",
    externalData: null,
    providerId: "..."
  }
]

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:

   curl -s https://authentik.example.com/application/o/overleaf/.well-known/openid-configuration \
     | jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, end_session_endpoint}'
   

   A resposta do Authentik tem esta aparência:

   {
     "issuer": "https://authentik.example.com/application/o/overleaf/",
     "authorization_endpoint": "https://authentik.example.com/application/o/authorize/",
     "token_endpoint": "https://authentik.example.com/application/o/token/",
     "userinfo_endpoint": "https://authentik.example.com/application/o/userinfo/",
     "end_session_endpoint": "https://authentik.example.com/application/o/overleaf/end-session/"
   }
   

   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

   Campo no documento de descoberta	Variável de ambiente
   issuer	OVERLEAF_OIDC_ISSUER
   authorization_endpoint	OVERLEAF_OIDC_AUTHORIZATION_URL
   token_endpoint	OVERLEAF_OIDC_TOKEN_URL
   userinfo_endpoint	OVERLEAF_OIDC_USER_INFO_URL
   end_session_endpoint	OVERLEAF_OIDC_LOGOUT_URL

   OVERLEAF_OIDC_ISSUER=https://authentik.example.com/application/o/overleaf/
   OVERLEAF_OIDC_AUTHORIZATION_URL=https://authentik.example.com/application/o/authorize/
   OVERLEAF_OIDC_TOKEN_URL=https://authentik.example.com/application/o/token/
   OVERLEAF_OIDC_USER_INFO_URL=https://authentik.example.com/application/o/userinfo/
   OVERLEAF_OIDC_LOGOUT_URL=https://authentik.example.com/application/o/overleaf/end-session/
   
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:

   docker exec sharelatex curl -sS -o /dev/null -w "%{http_code}\n" \
     https://authentik.example.com/application/o/overleaf/.well-known/openid-configuration
   

   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 [e-mail] e [e-mail]:
      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.

Exemplo de arquivo variables.env

variables.env

OVERLEAF_APP_NAME="Our Overleaf Instance"

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

# Enables Thumbnail generation using ImageMagick
ENABLE_CONVERSIONS=true

# Disables email confirmation requirement
EMAIL_CONFIRMATION_DISABLED=true

## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768

## Set for TLS via nginx-proxy
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true

OVERLEAF_SITE_URL=http://my-overleaf-instance.com
OVERLEAF_NAV_TITLE=Our Overleaf Instance
# OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
OVERLEAF_ADMIN_EMAIL=[e-mail]

OVERLEAF_LEFT_FOOTER=[{"text": "Contact your support team", "url": "mailto:[e-mail]"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"Hello, I am on the Right", "url":"https://github.com/yu-i-i/overleaf-cep"}]

OVERLEAF_EMAIL_FROM_ADDRESS=[e-mail]
OVERLEAF_EMAIL_SMTP_HOST=smtp.example.com
OVERLEAF_EMAIL_SMTP_PORT=587
OVERLEAF_EMAIL_SMTP_SECURE=false
# OVERLEAF_EMAIL_SMTP_USER=
# OVERLEAF_EMAIL_SMTP_PASS=
# OVERLEAF_EMAIL_SMTP_NAME=
OVERLEAF_EMAIL_SMTP_LOGGER=false
OVERLEAF_EMAIL_SMTP_TLS_REJECT_UNAUTH=true
OVERLEAF_EMAIL_SMTP_IGNORE_TLS=false
OVERLEAF_CUSTOM_EMAIL_FOOTER=This system is run by department x

OVERLEAF_PROXY_LEARN=true
NAV_HIDE_POWERED_BY=true

#################
## OIDC for CE ##
#################

EXTERNAL_AUTH=oidc

OVERLEAF_OIDC_PROVIDER_ID=oidc
OVERLEAF_OIDC_ISSUER=https://keycloak.provider.com/realms/example
OVERLEAF_OIDC_AUTHORIZATION_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/auth
OVERLEAF_OIDC_TOKEN_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/token
OVERLEAF_OIDC_USER_INFO_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/userinfo
OVERLEAF_OIDC_LOGOUT_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/logout
OVERLEAF_OIDC_CLIENT_ID=Overleaf-OIDC
OVERLEAF_OIDC_CLIENT_SECRET=DoNotUseThisATGgaAcTgCcATgGATTACAagGtTCaGcGTAG
OVERLEAF_OIDC_IDENTITY_SERVICE_NAME='Log in with Keycloak OIDC Provider'
OVERLEAF_OIDC_PROVIDER_NAME=OIDC Keycloak Provider
OVERLEAF_OIDC_PROVIDER_INFO_LINK=https://openid.net
OVERLEAF_OIDC_IS_ADMIN_FIELD=email
OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=[e-mail]
OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN=false

​

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:

   OVERLEAF_OIDC_IS_ADMIN_FIELD=groups
   OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=Admins
   

   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 testado para o goauthentik

variables.env

EXTERNAL_AUTH=oidc
OVERLEAF_OIDC_PROVIDER_ID=authentik
OVERLEAF_OIDC_IDENTITY_SERVICE_NAME=Log in with Authentik
OVERLEAF_OIDC_ISSUER=https://authentik.example.com/application/o/overleaf/
OVERLEAF_OIDC_AUTHORIZATION_URL=https://authentik.example.com/application/o/authorize/
OVERLEAF_OIDC_TOKEN_URL=https://authentik.example.com/application/o/token/
OVERLEAF_OIDC_USER_INFO_URL=https://authentik.example.com/application/o/userinfo/
OVERLEAF_OIDC_LOGOUT_URL=https://authentik.example.com/application/o/overleaf/end-session/
OVERLEAF_OIDC_CLIENT_ID=<Client ID>
OVERLEAF_OIDC_CLIENT_SECRET=<Client Secret>
OVERLEAF_OIDC_USER_ID_FIELD=username
OVERLEAF_OIDC_IS_ADMIN_FIELD=groups
OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=Admins
OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN=true