> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação OIDC

<Info>
  Este recurso foi desenvolvido por [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Aqui disponibilizamos alguns documentos para a sua configuração.
</Info>

### Configuração

Internamente, o módulo OIDC do Overleaf usa a biblioteca [passport-openidconnect](https://github.com/jaredhanson/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:

```text theme={null}
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.

<Steps>
  <Step title="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**:

    <Frame caption="Authentik: a URL de descoberta e o issuer de um provedor (instância de teste)">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-provider.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=e3cb5603d959665472b53e39b58b2775" alt="" width="1280" height="633" data-path="images/on-premises/oidc-authentik-provider.png" />
    </Frame>

    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`
  </Step>

  <Step title="Ler os valores">
    Abra a URL em um navegador ou execute no servidor do Overleaf:

    ```shell theme={null}
    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:

    ```json theme={null}
    {
      "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:

    <Frame caption="Authentik: os endpoints de um provedor (instância de teste)">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-endpoints.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=55d130cbbbf27fd11aebafa1ab3f090c" alt="" width="1280" height="633" data-path="images/on-premises/oidc-authentik-endpoints.png" />
    </Frame>
  </Step>

  <Step title="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` |

    ```dotenv theme={null}
    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/
    ```
  </Step>

  <Step title="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:

    ```shell theme={null}
    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`.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

#### 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` <strong>(obrigatória)</strong>
* `OVERLEAF_OIDC_AUTHORIZATION_URL` <strong>(obrigatória)</strong>
* `OVERLEAF_OIDC_TOKEN_URL` <strong>(obrigatória)</strong>
* `OVERLEAF_OIDC_USER_INFO_URL` <strong>(obrigatória)</strong>
* `OVERLEAF_OIDC_LOGOUT_URL` <strong>(obrigatória)</strong>

Os valores das duas variáveis obrigatórias a seguir serão fornecidos pelo administrador do seu OP

* `OVERLEAF_OIDC_CLIENT_ID` <strong>(obrigatória)</strong>
* `OVERLEAF_OIDC_CLIENT_SECRET` <strong>(obrigatória)</strong>
* `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`.

<Accordion title="Exemplo de arquivo variables.env">
  ```dotenv title="variables.env" wrap theme={null}
  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=support@example.com

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

  OVERLEAF_EMAIL_FROM_ADDRESS=team@example.com
  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=overleaf.admin@example.com
  OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN=false
  ```
</Accordion>

## Passo a passo: goauthentik

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

<Steps>
  <Step title="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`.

    <Frame caption="Authentik: Client ID e Client Secret de um novo provedor">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-create.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=f127a92eaf3063714e9af515fe97c263" alt="" width="1120" height="808" data-path="images/on-premises/oidc-authentik-create.png" />
    </Frame>

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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/`.
  </Step>

  <Step title="Copiar as URLs">
    Siga [Encontrando os valores com o documento de descoberta](#encontrando-os-valores-com-o-documento-de-descoberta) acima para preencher as cinco URLs.
  </Step>

  <Step title="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:

    ```dotenv theme={null}
    OVERLEAF_OIDC_IS_ADMIN_FIELD=groups
    OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=Admins
    ```

    <Warning>
      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.
    </Warning>
  </Step>
</Steps>

<Accordion title="variables.env testado para o goauthentik">
  ```dotenv title="variables.env" wrap theme={null}
  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
  ```
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.