OIDC-authenticatie

Deze functie is ontwikkeld door yu-i-i/overleaf-cep. Hier bieden we wat documentatie voor je configuratie.

​

Configuratie

Intern gebruikt de OIDC-module van Overleaf de bibliotheek passport-openidconnect. Als je problemen hebt met het configureren van OpenID Connect, is het de moeite waard om de README van passport-openidconnect te lezen om een idee te krijgen van de configuratie die deze verwacht.

De omgevingsvariabele EXTERNAL_AUTH is vereist om de OIDC-authenticatiemodule in te schakelen. Deze omgevingsvariabele geeft aan welke externe authenticatiemethoden worden geactiveerd. De waarde van deze variabele is een lijst. Als de lijst oidc bevat, wordt OIDC-authenticatie geactiveerd.

Bijvoorbeeld: EXTERNAL_AUTH=ldap oidc

Bij gebruik van de OIDC-authenticatiemethode wordt een gebruiker doorgestuurd naar de authenticatiesite van de Identity Provider (IdP). Als de IdP de gebruiker succesvol authenticeert, wordt in de gebruikersdatabase van Overleaf gezocht naar een record met een veld thirdPartyIdentifiers met de volgende structuur:

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

De externalUserId moet overeenkomen met het gebruikers-ID in het profiel dat door de IdP-server wordt geretourneerd (zie de omgevingsvariabele OVERLEAF_OIDC_USER_ID_FIELD), en providerId moet overeenkomen met het ID van de OIDC-provider (zie OVERLEAF_OIDC_PROVIDER_ID).

Als er geen overeenkomend record wordt gevonden, wordt in de database gezocht naar een gebruiker van wie het primaire e-mailadres overeenkomt met het e-mailadres in het gebruikersprofiel van de IdP:

• Als zo’n gebruiker wordt gevonden, wordt het veld thirdPartyIdentifiers bijgewerkt.
• Als er geen overeenkomende gebruiker wordt gevonden en het JIT-aanmaken van accounts niet is uitgeschakeld, wordt een nieuwe gebruiker aangemaakt met het e-mailadres en de thirdPartyIdentifiers uit het IdP-profiel.

In beide gevallen wordt gezegd dat de gebruiker ‘gekoppeld’ is aan de externe OIDC-gebruiker. De gebruiker kan op de pagina /user/settings worden ontkoppeld van de OIDC-provider.

​

De waarden vinden met het discovery-document

Elke OpenID Provider (OP) publiceert een discovery-document op <issuer>/.well-known/openid-configuration. Kopieer de waarden daaruit in plaats van ze met de hand over te typen; één verkeerd teken is genoeg om het inloggen te laten mislukken.

1. Zoek de discovery-URL

   Je OP toont deze op de pagina van de client (provider) die je voor Overleaf hebt aangemaakt. Open in Authentik Applications > Providers, selecteer de provider en zoek naar OpenID Configuration URL en OpenID Configuration Issuer:

   

   Authentik: de discovery-URL en de issuer van een provider (testinstantie)

   De URL ziet er meestal zo uit:

   • 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. Lees de waarden uit

   Open de URL in een browser, of voer op de Overleaf-server uit:

   curl -s https://authentik.example.com/application/o/overleaf/.well-known/openid-configuration \
     | jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, end_session_endpoint}'
   

   Het antwoord van Authentik ziet er zo uit:

   {
     "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 vermeldt deze URL’s ook verderop op de providerpagina:

   

   Authentik: de endpoints van een provider (testinstantie)

3. Kopieer ze naar variables.env

   Veld in het discovery-document	Omgevingsvariabele
   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. Controleer of Overleaf de OP kan bereiken

   Overleaf roept de token- en userinfo-endpoints aan vanuit zijn container, dus de OP moet vanaf daar bereikbaar zijn, niet alleen vanuit je browser:

   docker exec sharelatex curl -sS -o /dev/null -w "%{http_code}\n" \
     https://authentik.example.com/application/o/overleaf/.well-known/openid-configuration
   

   Dit zou 200 moeten tonen.

Kopieer issuer exact, inclusief de afsluitende slash. Overleaf vergelijkt deze teken voor teken met de issuer in het ID-token; elk verschil laat elke OIDC-aanmelding mislukken met:

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

In Authentik hoort de issuer bij de applicatie (.../application/o/<application-slug>/). Het is niet het adres van de Authentik-server, hoewel de authorize-, token- en userinfo-URL’s door alle applicaties worden gedeeld.

​

Omgevingsvariabelen

De waarden van de volgende vijf verplichte variabelen kun je vinden via het endpoint .well-known/openid-configuration van je OpenID Provider (OP), zie hierboven.

• OVERLEAF_OIDC_ISSUER (verplicht)
• OVERLEAF_OIDC_AUTHORIZATION_URL (verplicht)
• OVERLEAF_OIDC_TOKEN_URL (verplicht)
• OVERLEAF_OIDC_USER_INFO_URL (verplicht)
• OVERLEAF_OIDC_LOGOUT_URL (verplicht)

De waarden van de volgende twee verplichte variabelen worden verstrekt door de beheerder van je OP

• OVERLEAF_OIDC_CLIENT_ID (verplicht)
• OVERLEAF_OIDC_CLIENT_SECRET (verplicht)
• OVERLEAF_OIDC_SCOPE
  • Standaard: openid profile email
• OVERLEAF_OIDC_PROVIDER_ID
  • Willekeurig ID van de OP, standaard oidc.
• OVERLEAF_OIDC_PROVIDER_NAME
  • De naam van de OP, gebruikt in de sectie Linked Accounts van de pagina /user/settings, standaard OIDC Provider.
• OVERLEAF_OIDC_IDENTITY_SERVICE_NAME
  • Weergavenaam voor de identiteitsdienst, gebruikt op de inlogpagina (standaard: Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
• OVERLEAF_OIDC_PROVIDER_DESCRIPTION
  • Beschrijving van de OP, gebruikt in de sectie Linked Accounts (standaard: Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
• OVERLEAF_OIDC_PROVIDER_INFO_LINK
  • URL voor Learn more in de beschrijving van de OP; standaard: geen Learn more-link in de beschrijving.
• OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED
  • Toon de OP niet op de pagina /user/settings als het account van de gebruiker niet aan de OP is gekoppeld; standaard false.
• OVERLEAF_OIDC_USER_ID_FIELD
  • De waarde van dit attribuut wordt door Overleaf gebruikt als het externe gebruikers-ID, standaard id. Andere mogelijke redelijke waarden zijn email en username (overeenkomend met de OIDC-claim preferred_username).
• OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS
  • Beperkt het Just-in-Time (JIT) aanmaken van accounts voor gebruikers die zich via OIDC authenticeren. Als deze is ingesteld op een door komma’s gescheiden lijst met domeinnamen, wordt alleen een nieuw account aangemaakt als het domein van het e-mailadres van de gebruiker overeenkomt met een van de vermelde domeinen. Als het domein niet overeenkomt, moet een beheerder het gebruikersaccount handmatig aanmaken met het e-mailadres van de OIDC-gebruiker, met een sterk willekeurig wachtwoord of bij voorkeur helemaal zonder het veld hashedPassword. Domeinnamen mogen beginnen met een *.-jokerteken om subdomeinen te matchen.
    • Voorbeeld: om JIT-accountaanmaak toe te staan voor gebruikers met e-mailadressen zoals [e-mail] en [e-mail]:
      OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com
    • Voorbeeld: om JIT-accountaanmaak volledig uit te schakelen:
      OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=
• OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN
  • Als deze is ingesteld op true, worden de velden first_name en last_name van de gebruiker bij het inloggen bijgewerkt en wordt het formulier met gebruikersgegevens op de pagina /user/settings uitgeschakeld.
• OVERLEAF_OIDC_IS_ADMIN_FIELD en OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE
  • Wanneer beide omgevingsvariabelen zijn ingesteld, stelt het inlogproces user.isAdmin = true in als het door de OP geretourneerde profiel het attribuut bevat dat is opgegeven door OVERLEAF_OIDC_IS_ADMIN_FIELD en de waarde ervan overeenkomt met OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE of een array is die OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE bevat (bijvoorbeeld de claim groups); anders wordt user.isAdmin ingesteld op false. Als OVERLEAF_OIDC_IS_ADMIN_FIELD gelijk is aan email, wordt de waarde van het attribuut emails[0].value gebruikt voor de controle.

De redirect-URL voor je OpenID Provider is https://my-overleaf-instance.com/oidc/login/callback.

Voorbeeld van een variables.env-bestand

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

​

Stap voor stap: goauthentik

Hieronder doorlopen we een setup die is getest met goauthentik. Vervang https://overleaf.example.com door je OVERLEAF_SITE_URL en https://authentik.example.com door het adres van je Authentik.

1. Maak de provider aan

   Open in Authentik Applications > Providers, klik op New Provider, kies OAuth2/OpenID Provider en klik op Next.

   • Client Type: Confidential.
   • Redirect URIs (onder Protocol settings): voeg https://overleaf.example.com/oidc/login/callback toe met de matching-modus Strict.
   • Kopieer nu Client ID en Client Secret naar OVERLEAF_OIDC_CLIENT_ID en OVERLEAF_OIDC_CLIENT_SECRET.

   

   Authentik: Client ID en Client Secret van een nieuwe provider

   Authentik toont het client secret alleen tijdens het aanmaken van de provider. Later biedt het bewerkingsformulier alleen Modify, waarmee het secret wordt vervangen door een nieuw secret.

2. Maak de applicatie aan

   Open Applications > Applications, maak een nieuwe applicatie aan, geef deze een naam en een slug, bijvoorbeeld overleaf, en selecteer de provider. De slug wordt onderdeel van de issuer: https://authentik.example.com/application/o/overleaf/.

3. Kopieer de URL's

   Volg De waarden vinden met het discovery-document hierboven om de vijf URL’s in te vullen.

4. Koppel de beheerders (optioneel)

   Authentik stuurt de groepen van de gebruiker als de claim groups, een array. Om de leden van de Authentik-groep Admins beheerder van Overleaf te maken:

   OVERLEAF_OIDC_IS_ADMIN_FIELD=groups
   OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=Admins
   

   De beheerdersvlag wordt bij elke OIDC-aanmelding bijgewerkt. Met een verkeerd veld of een verkeerde waarde verliest elke beheerder die via OIDC inlogt de beheerdersrechten, inclusief de beheerder die in de launchpad is aangemaakt. Test de koppeling eerst met een tweede beheerdersaccount.

Geteste variables.env voor goauthentik

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