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

# OIDC-todennus

<Info>
  Tämän ominaisuuden on kehittänyt [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Tarjoamme tässä ohjeita sen määrittämiseen.
</Info>

### Määritys

Sisäisesti Overleafin OIDC-moduuli käyttää [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect)-kirjastoa. Jos OpenID Connectin määrittämisessä on ongelmia, kannattaa lukea `passport-openidconnect`-kirjaston README, jotta saat käsityksen sen odottamasta määrityksestä.

OIDC-todennusmoduulin käyttöönotto edellyttää ympäristömuuttujaa `EXTERNAL_AUTH`. Tämä ympäristömuuttuja määrittää, mitkä ulkoiset todennusmenetelmät aktivoidaan. Muuttujan arvo on luettelo. Jos luettelo sisältää arvon `oidc`, OIDC-todennus aktivoidaan.

Esimerkiksi: `EXTERNAL_AUTH=ldap oidc`

OIDC-todennusmenetelmää käytettäessä käyttäjä ohjataan identiteetintarjoajan (IdP) todennussivustolle. Jos IdP todentaa käyttäjän onnistuneesti, Overleafin käyttäjätietokannasta etsitään tietue, joka sisältää seuraavanlaisen `thirdPartyIdentifiers`-kentän:

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

Kentän `externalUserId` on vastattava IdP-palvelimen palauttaman profiilin käyttäjätunnusta (katso ympäristömuuttuja `OVERLEAF_OIDC_USER_ID_FIELD`), ja kentän `providerId` on vastattava OIDC-tarjoajan tunnusta (katso `OVERLEAF_OIDC_PROVIDER_ID`).

Jos vastaavaa tietuetta ei löydy, tietokannasta etsitään käyttäjää, jonka ensisijainen sähköpostiosoite vastaa IdP:n käyttäjäprofiilin sähköpostiosoitetta:

* Jos tällainen käyttäjä löytyy, `thirdPartyIdentifiers`-kenttä päivitetään.
* Jos vastaavaa käyttäjää ei löydy eikä JIT-tilinluontia ole poistettu käytöstä, luodaan uusi käyttäjä IdP-profiilin sähköpostiosoitteella ja `thirdPartyIdentifiers`-tiedoilla.

Molemmissa tapauksissa käyttäjän sanotaan olevan "linkitetty" ulkoiseen OIDC-käyttäjään. Linkityksen OIDC-tarjoajaan voi purkaa sivulla `/user/settings`.

#### Arvojen löytäminen discovery-dokumentin avulla

Jokainen OpenID-tarjoaja (OP) julkaisee discovery-dokumentin osoitteessa `<issuer>/.well-known/openid-configuration`. Kopioi arvot sieltä sen sijaan, että kirjoittaisit ne käsin; yksikin väärä merkki riittää rikkomaan kirjautumisen.

<Steps>
  <Step title="Etsi discovery-URL">
    OP näyttää sen sivulla, jolla on Overleafia varten luomasi asiakas (tarjoaja). Avaa Authentikissa **Applications > Providers**, valitse tarjoaja ja etsi kohdat **OpenID Configuration URL** ja **OpenID Configuration Issuer**:

    <Frame caption="Authentik: tarjoajan discovery-URL ja myöntäjä (testi-instanssi)">
      <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>

    URL näyttää yleensä tältä:

    * 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="Lue arvot">
    Avaa URL selaimessa tai suorita Overleaf-palvelimella:

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

    Authentikin vastaus näyttää tältä:

    ```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 näyttää nämä URL-osoitteet myös alempana tarjoajan sivulla:

    <Frame caption="Authentik: tarjoajan päätepisteet (testi-instanssi)">
      <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="Kopioi ne tiedostoon `variables.env`">
    | Kenttä discovery-dokumentissa | Ympäristömuuttuja |
    | - | - |
    | `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="Tarkista, että Overleaf tavoittaa OP:n">
    Overleaf kutsuu token- ja userinfo-päätepisteitä konttinsa sisältä, joten OP:n on oltava tavoitettavissa sieltä eikä vain selaimestasi:

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

    Sen pitäisi tulostaa `200`.
  </Step>
</Steps>

<Warning>
  Kopioi `issuer` täsmälleen, myös loppukauttaviiva. Overleaf vertaa sitä merkki merkiltä ID-tokenin myöntäjään; mikä tahansa ero saa jokaisen OIDC-kirjautumisen epäonnistumaan virheellä:

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

  Authentikissa myöntäjä kuuluu sovellukselle (`.../application/o/<application-slug>/`). Se ei ole Authentik-palvelimen osoite, vaikka authorize-, token- ja userinfo-URL-osoitteet ovat kaikille sovelluksille yhteiset.
</Warning>

#### Ympäristömuuttujat

Seuraavien viiden pakollisen muuttujan arvot löytyvät OpenID-tarjoajasi (OP) `.well-known/openid-configuration`-päätepisteestä, katso yllä.

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

Seuraavien kahden pakollisen muuttujan arvot saat OP:n ylläpitäjältä

* `OVERLEAF_OIDC_CLIENT_ID` <strong>(pakollinen)</strong>
* `OVERLEAF_OIDC_CLIENT_SECRET` <strong>(pakollinen)</strong>
* `OVERLEAF_OIDC_SCOPE`
  * Oletus: `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * OP:n vapaavalintainen tunnus, oletuksena `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * OP:n nimi, jota käytetään sivun `/user/settings` `Linked Accounts` -osiossa, oletuksena `OIDC Provider`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * Identiteettipalvelun näyttönimi, jota käytetään kirjautumissivulla (oletus: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * OP:n kuvaus, jota käytetään `Linked Accounts` -osiossa (oletus: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * OP:n kuvauksen `Learn more` -URL; oletuksena kuvauksessa ei ole `Learn more` -linkkiä.
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * Älä näytä OP:tä sivulla `/user/settings`, jos käyttäjän tiliä ei ole linkitetty OP:hen, oletuksena `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * Overleaf käyttää tämän attribuutin arvoa ulkoisena käyttäjätunnuksena, oletuksena `id`. Muita mahdollisia järkeviä arvoja ovat `email` ja `username` (vastaa OIDC-väitettä `preferred_username`).
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * Rajoittaa Just-in-Time (JIT) -tilinluontia OIDC:n kautta todentautuville käyttäjille. Jos arvoksi asetetaan pilkuin eroteltu luettelo verkkotunnuksista, uusi tili luodaan vain, jos käyttäjän sähköpostiosoitteen verkkotunnus vastaa jotakin luettelon verkkotunnuksista. Jos verkkotunnus ei vastaa, ylläpitäjän on luotava käyttäjätili manuaalisesti OIDC-käyttäjän sähköpostiosoitteella joko vahvalla satunnaisella salasanalla tai mieluiten kokonaan ilman `hashedPassword`-kenttää. Verkkotunnusten alussa voi olla `*.`-jokerimerkki, joka vastaa aliverkkotunnuksia.
    * Esimerkki: JIT-tilinluonnin salliminen käyttäjille, joiden sähköpostiosoite on muotoa `name@example.com` ja `name@math.example.com`:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * Esimerkki: JIT-tilinluonnin poistaminen kokonaan käytöstä:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * Jos arvoksi asetetaan `true`, käyttäjän kentät `first_name` ja `last_name` päivitetään kirjautumisen yhteydessä, ja sivun `/user/settings` käyttäjätietolomake poistetaan käytöstä.
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` ja `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * Kun molemmat ympäristömuuttujat on asetettu, kirjautumisprosessi asettaa `user.isAdmin = true`, jos OP:n palauttama profiili sisältää muuttujan `OVERLEAF_OIDC_IS_ADMIN_FIELD` määrittämän attribuutin ja sen arvo joko vastaa muuttujaa `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` tai on taulukko, joka sisältää arvon `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` (esimerkiksi `groups`-claim); muussa tapauksessa `user.isAdmin` asetetaan arvoon `false`. Jos `OVERLEAF_OIDC_IS_ADMIN_FIELD` on `email`, vastaavuuden tarkistuksessa käytetään attribuutin `emails[0].value` arvoa.

OpenID-tarjoajasi uudelleenohjaus-URL on `https://my-overleaf-instance.com/oidc/login/callback`.

<Accordion title="Esimerkki variables.env-tiedostosta">
  ```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>

## Vaihe vaiheelta: goauthentik

Tämä ohje käy läpi määrityksen, joka on testattu [goauthentikin](https://goauthentik.io/) kanssa. Korvaa `https://overleaf.example.com` omalla `OVERLEAF_SITE_URL`-arvollasi ja `https://authentik.example.com` Authentikisi osoitteella.

<Steps>
  <Step title="Luo tarjoaja">
    Avaa Authentikissa **Applications > Providers**, napsauta **New Provider**, valitse **OAuth2/OpenID Provider** ja napsauta **Next**.

    * **Client Type**: `Confidential`.
    * **Redirect URIs** (kohdassa **Protocol settings**): lisää `https://overleaf.example.com/oidc/login/callback` vastaavuustilalla `Strict`.
    * Kopioi nyt **Client ID** ja **Client Secret** muuttujiin `OVERLEAF_OIDC_CLIENT_ID` ja `OVERLEAF_OIDC_CLIENT_SECRET`.

    <Frame caption="Authentik: uuden tarjoajan Client ID ja Client Secret">
      <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 näyttää asiakassalaisuuden vain tarjoajaa luotaessa. Myöhemmin muokkauslomake tarjoaa vain **Modify**-toiminnon, joka korvaa salaisuuden uudella.
    </Warning>
  </Step>

  <Step title="Luo sovellus">
    Avaa **Applications > Applications**, luo uusi sovellus, anna sille nimi ja slug, esimerkiksi `overleaf`, ja valitse tarjoaja. Slugista tulee osa myöntäjää: `https://authentik.example.com/application/o/overleaf/`.
  </Step>

  <Step title="Kopioi URL-osoitteet">
    Täytä viisi URL-osoitetta yllä olevan kohdan [Arvojen löytäminen discovery-dokumentin avulla](#arvojen-löytäminen-discovery-dokumentin-avulla) ohjeiden mukaisesti.
  </Step>

  <Step title="Määritä ylläpitäjät (valinnainen)">
    Authentik lähettää käyttäjän ryhmät `groups`-claimissa, joka on taulukko. Jos haluat Authentik-ryhmän `Admins` jäsenistä Overleafin ylläpitäjiä:

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

    <Warning>
      Ylläpitäjän tila päivitetään jokaisella OIDC-kirjautumisella. Jos kenttä tai arvo on väärä, jokainen OIDC:n kautta kirjautuva ylläpitäjä menettää ylläpitäjän oikeutensa, mukaan lukien launchpadissa luotu ylläpitäjä. Testaa määritys ensin toisella ylläpitäjätilillä.
    </Warning>
  </Step>
</Steps>

<Accordion title="Testattu variables.env-tiedosto goauthentikille">
  ```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.