> ## 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.

# Autenticazione OIDC

<Info>
  Questa funzionalità è sviluppata da [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Qui ti offriamo della documentazione per la configurazione.
</Info>

### Configurazione

Internamente, il modulo OIDC di Overleaf utilizza la libreria [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect). Se riscontri problemi nella configurazione di OpenID Connect, vale la pena leggere il README di `passport-openidconnect` per farti un'idea della configurazione che si aspetta.

La variabile d'ambiente `EXTERNAL_AUTH` è necessaria per abilitare il modulo di autenticazione OIDC. Questa variabile d'ambiente specifica quali metodi di autenticazione esterna sono attivati. Il valore di questa variabile è un elenco. Se l'elenco include `oidc`, l'autenticazione OIDC verrà attivata.

Ad esempio: `EXTERNAL_AUTH=ldap oidc`

Quando si utilizza il metodo di autenticazione OIDC, l'utente viene reindirizzato al sito di autenticazione dell'Identity Provider (IdP). Se l'IdP autentica correttamente l'utente, nel database degli utenti di Overleaf viene cercato un record contenente un campo `thirdPartyIdentifiers` strutturato come segue:

```text theme={null}
thirdPartyIdentifiers: [
  {
    externalUserId: "...",
    externalData: null,
    providerId: "..."
  }
]
```

`externalUserId` deve corrispondere all'ID utente nel profilo restituito dal server IdP (vedi la variabile d'ambiente `OVERLEAF_OIDC_USER_ID_FIELD`) e `providerId` deve corrispondere all'ID del provider OIDC (vedi `OVERLEAF_OIDC_PROVIDER_ID`).

Se non viene trovato alcun record corrispondente, nel database viene cercato un utente il cui indirizzo email principale corrisponda all'email presente nel profilo utente dell'IdP:

* Se viene trovato un utente di questo tipo, il campo `thirdPartyIdentifiers` viene aggiornato.
* Se non viene trovato alcun utente corrispondente e la creazione degli account JIT non è disabilitata, viene creato un nuovo utente con l'indirizzo email e i `thirdPartyIdentifiers` del profilo IdP.

In entrambi i casi, si dice che l'utente è 'collegato' all'utente OIDC esterno. L'utente può essere scollegato dal provider OIDC nella pagina `/user/settings`.

#### Trovare i valori con il documento di discovery

Ogni OpenID Provider (OP) pubblica un documento di discovery all'indirizzo `<issuer>/.well-known/openid-configuration`. Copia i valori da lì invece di digitarli a mano; basta un carattere sbagliato per compromettere l'accesso.

<Steps>
  <Step title="Trova l'URL di discovery">
    Il tuo OP lo mostra nella pagina del client (provider) che hai creato per Overleaf. In Authentik, apri **Applications > Providers**, seleziona il provider e cerca **OpenID Configuration URL** e **OpenID Configuration Issuer**:

    <Frame caption="Authentik: l'URL di discovery e l'issuer di un provider (istanza di test)">
      <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>

    Di solito l'URL ha questo aspetto:

    * 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="Leggi i valori">
    Apri l'URL in un browser oppure esegui sul server 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}'
    ```

    La risposta di Authentik ha questo aspetto:

    ```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/"
    }
    ```

    Authentik elenca questi URL anche più in basso nella pagina del provider:

    <Frame caption="Authentik: gli endpoint di un provider (istanza di test)">
      <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="Copiali in `variables.env`">
    | Campo nel documento di discovery | Variabile d'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="Verifica che Overleaf possa raggiungere l'OP">
    Overleaf chiama gli endpoint token e userinfo dall'interno del proprio container, quindi l'OP deve essere raggiungibile da lì, non solo dal tuo browser:

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

    Dovrebbe restituire `200`.
  </Step>
</Steps>

<Warning>
  Copia `issuer` esattamente, inclusa la barra finale. Overleaf lo confronta carattere per carattere con l'issuer presente nell'ID token; qualsiasi differenza fa fallire ogni accesso OIDC con:

  `{"message":{"message":"ID token not issued by expected OpenID provider."}}`

  In Authentik l'issuer appartiene all'applicazione (`.../application/o/<application-slug>/`). Non è l'indirizzo del server Authentik, anche se gli URL authorize, token e userinfo sono condivisi da tutte le applicazioni.
</Warning>

#### Variabili d'ambiente

I valori delle seguenti cinque variabili obbligatorie si possono trovare tramite l'endpoint `.well-known/openid-configuration` del tuo OpenID Provider (OP), come descritto sopra.

* `OVERLEAF_OIDC_ISSUER` <strong>(obbligatoria)</strong>
* `OVERLEAF_OIDC_AUTHORIZATION_URL` <strong>(obbligatoria)</strong>
* `OVERLEAF_OIDC_TOKEN_URL` <strong>(obbligatoria)</strong>
* `OVERLEAF_OIDC_USER_INFO_URL` <strong>(obbligatoria)</strong>
* `OVERLEAF_OIDC_LOGOUT_URL` <strong>(obbligatoria)</strong>

I valori delle seguenti due variabili obbligatorie verranno forniti dall'amministratore del tuo OP

* `OVERLEAF_OIDC_CLIENT_ID` <strong>(obbligatoria)</strong>
* `OVERLEAF_OIDC_CLIENT_SECRET` <strong>(obbligatoria)</strong>
* `OVERLEAF_OIDC_SCOPE`
  * Predefinito: `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * ID arbitrario dell'OP, predefinito `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * Il nome dell'OP, utilizzato nella sezione `Linked Accounts` della pagina `/user/settings`, predefinito `OIDC Provider`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * Nome visualizzato del servizio di identità, utilizzato nella pagina di accesso (predefinito: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * Descrizione dell'OP, utilizzata nella sezione `Linked Accounts` (predefinito: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * URL `Learn more` nella descrizione dell'OP; predefinito: nessun link `Learn more` nella descrizione.
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * Non mostra l'OP nella pagina `/user/settings` se l'account dell'utente non è collegato all'OP; predefinito `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * Il valore di questo attributo verrà utilizzato da Overleaf come ID utente esterno; predefinito `id`. Altri valori ragionevoli possibili sono `email` e `username` (corrispondente al claim OIDC `preferred_username`).
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * Limita la creazione degli account Just-in-Time (JIT) per gli utenti che si autenticano tramite OIDC. Se impostata su un elenco di nomi di dominio separati da virgole, un nuovo account verrà creato solo se il dominio dell'indirizzo email dell'utente corrisponde a uno dei domini elencati. Se il dominio non corrisponde, un amministratore deve creare manualmente l'account utente utilizzando l'indirizzo email dell'utente OIDC, con una password casuale robusta oppure, preferibilmente, senza alcun campo `hashedPassword`. I nomi di dominio possono includere un carattere jolly iniziale `*.` per corrispondere ai sottodomini.
    * Esempio: per consentire la creazione di account JIT per utenti con indirizzi email come `name@example.com` e `name@math.example.com`:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * Esempio: per disabilitare completamente la creazione di account JIT:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * Se impostata su `true`, aggiorna i campi `first_name` e `last_name` dell'utente all'accesso e disabilita il modulo dei dati utente nella pagina `/user/settings`.
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` e `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * Quando entrambe le variabili d'ambiente sono impostate, il processo di accesso imposta `user.isAdmin = true` se il profilo restituito dall'OP contiene l'attributo specificato da `OVERLEAF_OIDC_IS_ADMIN_FIELD` e il suo valore corrisponde a `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` oppure è un array che contiene `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` (ad esempio il claim `groups`); altrimenti `user.isAdmin` viene impostato su `false`. Se `OVERLEAF_OIDC_IS_ADMIN_FIELD` è `email`, per la verifica della corrispondenza viene utilizzato il valore dell'attributo `emails[0].value`.

L'URL di reindirizzamento per il tuo OpenID Provider è `https://my-overleaf-instance.com/oidc/login/callback`.

<Accordion title="File variables.env di esempio">
  ```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 dopo passo: goauthentik

Questa guida illustra una configurazione testata con [goauthentik](https://goauthentik.io/). Sostituisci `https://overleaf.example.com` con il tuo `OVERLEAF_SITE_URL` e `https://authentik.example.com` con l'indirizzo della tua istanza Authentik.

<Steps>
  <Step title="Crea il provider">
    In Authentik, apri **Applications > Providers**, fai clic su **New Provider**, scegli **OAuth2/OpenID Provider** e fai clic su **Next**.

    * **Client Type**: `Confidential`.
    * **Redirect URIs** (sotto **Protocol settings**): aggiungi `https://overleaf.example.com/oidc/login/callback` con la modalità di corrispondenza `Strict`.
    * Copia subito **Client ID** e **Client Secret** in `OVERLEAF_OIDC_CLIENT_ID` e `OVERLEAF_OIDC_CLIENT_SECRET`.

    <Frame caption="Authentik: Client ID e Client Secret di un nuovo provider">
      <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>
      Authentik mostra il client secret solo durante la creazione del provider. In seguito il modulo di modifica offre solo **Modify**, che sostituisce il secret con uno nuovo.
    </Warning>
  </Step>

  <Step title="Crea l'applicazione">
    Apri **Applications > Applications**, crea una nuova applicazione, assegnale un nome e uno slug, ad esempio `overleaf`, e seleziona il provider. Lo slug diventa parte dell'issuer: `https://authentik.example.com/application/o/overleaf/`.
  </Step>

  <Step title="Copia gli URL">
    Segui la sezione [Trovare i valori con il documento di discovery](#trovare-i-valori-con-il-documento-di-discovery) più sopra per compilare i cinque URL.
  </Step>

  <Step title="Mappa gli amministratori (facoltativo)">
    Authentik invia i gruppi dell'utente nel claim `groups`, un array. Per rendere amministratori di Overleaf i membri del gruppo Authentik `Admins`:

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

    <Warning>
      Il flag di amministratore viene aggiornato a ogni accesso OIDC. Con un campo o un valore errato, ogni amministratore che accede tramite OIDC perde i diritti di amministratore, compreso l'amministratore creato nel launchpad. Prova prima la mappatura con un secondo account amministratore.
    </Warning>
  </Step>
</Steps>

<Accordion title="variables.env testato per 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.