> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/on-premises/fi/maaritys/overleaf-toolkit/authentication/oidc-authentication.md).

# OIDC-todennus

Tämän ominaisuuden on kehittänyt [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Tässä tarjoamme joitakin asiakirjoja konfiguraatiotasi varten.

### Määritys

Sisäisesti Overleafin OIDC-moduuli käyttää [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect) kirjastoa. Jos sinulla on ongelmia OpenID Connectin määrittämisessä, kannattaa lukea README-tiedostoa `passport-openidconnect` README, jotta saat käsityksen siitä, mitä määritystä se odottaa.

Ympäristömuuttuja `EXTERNAL_AUTH` tarvitaan OIDC-tunnistautumismoduulin käyttöönottoa varten. Tämä ympäristömuuttuja määrittää, mitkä ulkoiset tunnistautumismenetelmät ovat käytössä. Tämän muuttujan arvo on lista. Jos lista sisältää `oidc` silloin OIDC-tunnistautuminen otetaan käyttöön.

Esimerkiksi: `EXTERNAL_AUTH=ldap oidc`

Kun käytetään OIDC-tunnistautumismenetelmää, käyttäjä ohjataan Identity Providerin (IdP) tunnistautumissivulle. Jos IdP tunnistaa käyttäjän onnistuneesti, Overleafin käyttäjätietokannasta etsitään tietue, joka sisältää `thirdPartyIdentifiers` kentän, jonka rakenne on seuraava:

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

Kentän `externalUserId` täytyy vastata käyttäjätunnusta IdP-palvelimelta palautetussa profiilissa (katso `OVERLEAF_OIDC_USER_ID_FIELD` ympäristömuuttuja), ja `providerId` täytyy vastata OIDC-palveluntarjoajan 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äprofiilissa olevaa sähköpostiosoitetta:

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

Molemmissa tapauksissa käyttäjän sanotaan olevan 'linkitetty' ulkoiseen OIDC-käyttäjään. Käyttäjä voidaan irrottaa OIDC-palveluntarjoajasta `/user/settings` sivu.

#### Ympäristömuuttujat

Seuraavien viiden vaaditun muuttujan arvot löytyvät käyttämällä `.well-known/openid-configuration` OpenID Providerisi (OP) päätepisteestä.

* `OVERLEAF_OIDC_ISSUER` **(vaaditaan)**
* `OVERLEAF_OIDC_AUTHORIZATION_URL` **(vaaditaan)**
* `OVERLEAF_OIDC_TOKEN_URL` **(vaaditaan)**
* `OVERLEAF_OIDC_USER_INFO_URL` **(vaaditaan)**
* `OVERLEAF_OIDC_LOGOUT_URL` **(vaaditaan)**

Seuraavien kahden vaaditun muuttujan arvot toimittaa OP:si ylläpitäjä

* `OVERLEAF_OIDC_CLIENT_ID` **(vaaditaan)**
* `OVERLEAF_OIDC_CLIENT_SECRET` **(vaaditaan)**
* `OVERLEAF_OIDC_SCOPE`
  * Oletus: `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * OP:n mielivaltainen tunnus, oletusarvoisesti `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * OP:n nimi, jota käytetään `Linkitetyt tilit` osion `/user/settings` sivulla, oletusarvoisesti `OIDC-palveluntarjoaja`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * Tunnistuspalvelun näyttönimi, jota käytetään kirjautumissivulla (oletus: `Kirjaudu sisään käyttäen $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * OP:n kuvaus, jota käytetään `Linkitetyt tilit` osiossa (oletus: `Kirjaudu sisään käyttäen $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * `Lue lisää` URL-osoite OP:n kuvauksessa, oletus: ei `Lue lisää` linkkiä kuvauksessa.
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * Älä näytä OP:ta `/user/settings` sivulla, jos käyttäjän tiliä ei ole linkitetty OP:hen, oletus `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * Tämän attribuutin arvoa käyttää Overleaf ulkoisena käyttäjätunnuksena, oletusarvoisesti `id`. Muita mahdollisia järkeviä arvoja ovat `email` ja `käyttäjätunnuksen` (vastaa `preferred_username` OIDC-väite).
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * Rajoittaa OIDC:n kautta tunnistautuvien käyttäjien Just-in-Time (JIT) -tilinluontia. Jos se on asetettu pilkuilla erotetuksi verkkotunnusluetteloksi, uusi tili luodaan vain, jos käyttäjän sähköpostiosoitteen verkkotunnus vastaa jotakin luettelon verkkotunnuksista. Jos verkkotunnus ei täsmää, ylläpitäjän on luotava käyttäjätili manuaalisesti käyttämällä OIDC-käyttäjän sähköpostiosoitetta joko vahvalla satunnaisella salasanalla tai, mieluiten, ilman `hashedPassword` kenttää lainkaan. Verkkotunnusten nimiin voi sisältyä alussa `*.` jokerimerkki aliverkkotunnusten täsmäämiseksi.
    * Esimerkki: JIT-tilinluonti sallitaan käyttäjille, joiden sähköpostiosoite on esimerkiksi `name@example.com` ja `name@math.example.com`:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * Esimerkki: JIT-tilinluonnin poistamiseksi käytöstä kokonaan:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * Jos arvoksi asetetaan `true`, päivittää käyttäjän `etunimi` ja `sukunimi` kentän kirjautumisen yhteydessä ja poistaa käyttäjätietolomakkeen käytöstä `/user/settings` sivu.
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` ja `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * Kun molemmat ympäristömuuttujat on asetettu, kirjautumisprosessi päivittää `user.isAdmin = true` jos OP:n palauttama profiili sisältää attribuutin, joka on määritetty asetuksella `OVERLEAF_OIDC_IS_ADMIN_FIELD` ja sen arvo vastaa `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`, muuten `user.isAdmin` on asetettu arvoon `false`. Jos `OVERLEAF_OIDC_IS_ADMIN_FIELD` on `email` silloin attribuutin `emails[0].value` käytetään täsmäyksen tarkistamiseen.

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

<details>

<summary>Esimerkkitiedosto variables.env</summary>

{% code title="variables.env" overflow="wrap" %}

```dotenv
OVERLEAF_APP_NAME="Meidän Overleaf-instanssimme"

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

# Ottaa käyttöön pikkukuvien luonnin ImageMagickin avulla
ENABLE_CONVERSIONS=true

# Poistaa sähköpostivahvistusvaatimuksen käytöstä
EMAIL_CONFIRMATION_DISABLED=true

## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768

## Aseta TLS käyttöön nginx-proxyn kautta
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true

OVERLEAF_SITE_URL=http://my-overleaf-instance.com
OVERLEAF_NAV_TITLE=Oma Overleaf-instanssimme
# OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
OVERLEAF_ADMIN_EMAIL=support@example.com

OVERLEAF_LEFT_FOOTER=[{"text": "Ota yhteyttä tukitiimiisi", "url": "mailto:support@example.com"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"Hei, olen oikealla", "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=Tätä järjestelmää ylläpitää osasto x

OVERLEAF_PROXY_LEARN=true
NAV_HIDE_POWERED_BY=true

#################
## OIDC CE:lle ##
#################

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='Kirjaudu sisään käyttäen Keycloak OIDC -palveluntarjoajaa'
OVERLEAF_OIDC_PROVIDER_NAME=OIDC Keycloak -palveluntarjoaja
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
```

{% endcode %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://overleaf-pro.ayaka.space/on-premises/fi/maaritys/overleaf-toolkit/authentication/oidc-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.