OIDC-todennus

Tämän ominaisuuden on kehittänyt yu-i-i/overleaf-cep. Tarjoamme tässä ohjeita sen määrittämiseen.

​

Määritys

Sisäisesti Overleafin OIDC-moduuli käyttää 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:

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.

1. 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:

   

   Authentik: tarjoajan discovery-URL ja myöntäjä (testi-instanssi)

   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
2. Lue arvot

   Avaa URL selaimessa tai suorita Overleaf-palvelimella:

   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ä:

   {
     "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:

   

   Authentik: tarjoajan päätepisteet (testi-instanssi)

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

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

   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.

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.

​

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 (pakollinen)
• OVERLEAF_OIDC_AUTHORIZATION_URL (pakollinen)
• OVERLEAF_OIDC_TOKEN_URL (pakollinen)
• OVERLEAF_OIDC_USER_INFO_URL (pakollinen)
• OVERLEAF_OIDC_LOGOUT_URL (pakollinen)

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

• OVERLEAF_OIDC_CLIENT_ID (pakollinen)
• OVERLEAF_OIDC_CLIENT_SECRET (pakollinen)
• 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 [e-mail] ja [e-mail]:
      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.

Esimerkki variables.env-tiedostosta

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

​

Vaihe vaiheelta: goauthentik

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

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

   

   Authentik: uuden tarjoajan Client ID ja Client Secret

   Authentik näyttää asiakassalaisuuden vain tarjoajaa luotaessa. Myöhemmin muokkauslomake tarjoaa vain Modify-toiminnon, joka korvaa salaisuuden uudella.

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

3. Kopioi URL-osoitteet

   Täytä viisi URL-osoitetta yllä olevan kohdan Arvojen löytäminen discovery-dokumentin avulla ohjeiden mukaisesti.

4. 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ä:

   OVERLEAF_OIDC_IS_ADMIN_FIELD=groups
   OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=Admins
   

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

Testattu variables.env-tiedosto goauthentikille

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