SAML-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 SAML-moduuli käyttää passport-saml-kirjastoa, ja useimmat seuraavista määritysasetuksista välitetään suoraan passport-saml-kirjastolle. Jos SAML:n määrittämisessä on ongelmia, kannattaa lukea passport-saml-kirjaston README, jotta saat käsityksen sen odottamasta määrityksestä. SAML-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 saml, SAML-todennus aktivoidaan. Esimerkiksi: EXTERNAL_AUTH=ldap saml SAML-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 samlIdentifiers-kentän:

samlIdentifiers: [
  {
    externalUserId: "...",
    providerId: "1",
    userIdAttribute: "..."
  }
]

Kentän externalUserId on vastattava IdP-palvelimen palauttaman käyttäjäprofiilin sitä ominaisuutta, jonka userIdAttribute määrittää. 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, hashedPassword-kenttä poistetaan paikallisen todennuksen estämiseksi ja samlIdentifiers-kenttä lisätään.
Jos vastaavaa käyttäjää ei löydy, luodaan uusi käyttäjä IdP-profiilin sähköpostiosoitteella ja samlIdentifiers-tiedoilla.

Huomaa: Tällä hetkellä tuetaan vain yhtä SAML-identiteetintarjoajaa. samlIdentifiers-kentän providerId on kiinteästi '1'.

Ympäristömuuttujat

OVERLEAF_SAML_IDENTITY_SERVICE_NAME
- Identiteettipalvelun näyttönimi, jota käytetään kirjautumissivulla (oletus: Log in with SAML IdP).
OVERLEAF_SAML_USER_ID_FIELD
- Overleaf käyttää tämän attribuutin arvoa ulkoisena käyttäjätunnuksena, oletuksena nameID.
OVERLEAF_SAML_EMAIL_FIELD
- Käyttäjäprofiilin sähköpostikentän nimi, oletuksena nameID.
OVERLEAF_SAML_FIRST_NAME_FIELD
- Käyttäjäprofiilin etunimikentän (firstName) nimi, oletuksena givenName.
OVERLEAF_SAML_LAST_NAME_FIELD
- Käyttäjäprofiilin sukunimikentän (lastName) nimi, oletuksena lastName
OVERLEAF_SAML_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_SAML_ENTRYPOINT (pakollinen)
- SAML-identiteettipalvelun sisääntulo-URL.
  - Esimerkki: https://idp.example.com/simplesaml/saml2/idp/SSOService.php
  - Azure-esimerkki: https://login.microsoftonline.com/8b26b46a-6dd3-45c7-a104-f883f4db1f6b/saml2
OVERLEAF_SAML_ISSUER (pakollinen)
- Myöntäjän (Issuer) nimi.
OVERLEAF_SAML_AUDIENCE
- SAML-vastauksen odotettu Audience-arvo, oletuksena muuttujan OVERLEAF_SAML_ISSUER arvo.
OVERLEAF_SAML_IDP_CERT (pakollinen)
- Polku tiedostoon, joka sisältää identiteetintarjoajan julkisen varmenteen, jolla saapuvien SAML-vastausten allekirjoitukset tarkistetaan. Jos identiteetintarjoajalla on useita kelvollisia allekirjoitusvarmenteita, arvo voi olla JSON-taulukko varmenteiden poluista.
  - Esimerkki (yksi varmenne): /var/lib/overleaf/certs/idp_cert.pem
  - Esimerkki (useita varmenteita): ["var/lib/overleaf/certs/idp_cert.pem", "/var/lib/overleaf/certs/idp_cert_old.pem"]
OVERLEAF_SAML_PUBLIC_CERT
- Polku tiedostoon, joka sisältää julkisen allekirjoitusvarmenteen. Varmenne upotetaan todennuspyyntöihin, jotta IdP voi tarkistaa saapuvan SAML-pyynnön allekirjoitukset. Se on pakollinen, kun metadatapäätepiste otetaan käyttöön ja strategia on määritetty muuttujalla OVERLEAF_SAML_PRIVATE_KEY. Varmenteiden kierron tukemiseksi voidaan antaa JSON-taulukko varmenteiden poluista. Kun annetaan varmennetaulukko, taulukon ensimmäisen alkion on vastattava nykyistä OVERLEAF_SAML_PRIVATE_KEY-avainta. Taulukon muita alkioita voidaan käyttää tulevien varmenteiden julkaisemiseen identiteetintarjoajille ennen OVERLEAF_SAML_PRIVATE_KEY-avaimen vaihtamista.
OVERLEAF_SAML_PRIVATE_KEY
- Polku tiedostoon, joka sisältää PEM-muotoisen yksityisen avaimen, joka vastaa varmennetta OVERLEAF_SAML_PUBLIC_CERT ja jolla passport-saml allekirjoittaa lähettämänsä todennuspyynnöt.
OVERLEAF_SAML_DECRYPTION_CERT
- Polku tiedostoon, joka sisältää julkisen varmenteen, jota käytetään metadatapäätepisteessä.
OVERLEAF_SAML_DECRYPTION_PVK
- Polku tiedostoon, joka sisältää varmennetta OVERLEAF_SAML_DECRYPTION_CERT vastaavan yksityisen avaimen, jolla yritetään purkaa vastaanotettujen salattujen väittämien (assertion) salaus.
OVERLEAF_SAML_SIGNATURE_ALGORITHM
- Valinnaisesti pyyntöjen allekirjoittamiseen käytettävä allekirjoitusalgoritmi; kelvolliset arvot ovat ‘sha1’ (oletus), ‘sha256’ (suositeltu) ja ‘sha512’ (turvallisin, tarkista, tukeeko IdP:si sitä).
OVERLEAF_SAML_ADDITIONAL_PARAMS
- JSON-sanakirja lisäkyselyparametreista, jotka lisätään kaikkiin pyyntöihin.
OVERLEAF_SAML_ADDITIONAL_AUTHORIZE_PARAMS
- JSON-sanakirja lisäkyselyparametreista, jotka lisätään ‘authorize’-pyyntöihin.
  - Esimerkki: {"some_key": "some_value"}
OVERLEAF_SAML_IDENTIFIER_FORMAT
- Identiteetintarjoajalta pyydettävä nimitunnisteen muoto (oletus: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress). Jos käytät muotoa urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, varmista, että ympäristömuuttuja OVERLEAF_SAML_EMAIL_FIELD on määritetty. Jos tarvitaan muotoa urn:oasis:names:tc:SAML:2.0:nameid-format:transient, sinun on määritettävä myös ympäristömuuttuja OVERLEAF_SAML_USER_ID_FIELD, jonka arvoksi voidaan asettaa esimerkiksi käyttäjän sähköpostiosoite.
OVERLEAF_SAML_ACCEPTED_CLOCK_SKEW_MS
- Asiakkaan ja palvelimen välinen hyväksyttävä kellojen ero millisekunteina, kun tarkistetaan väittämäehtojen OnBefore ja NotOnOrAfter voimassaoloaikaleimoja. Arvo -1 poistaa näiden ehtojen tarkistuksen kokonaan käytöstä. Oletus on 0.
OVERLEAF_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX
- AuthnRequest-pyyntöön lisättävä AttributeConsumingServiceIndex-attribuutti, joka kertoo IdP:lle, mikä attribuuttijoukko vastaukseen liitetään (linkki).
OVERLEAF_SAML_AUTHN_CONTEXT
- JSON-taulukko nimitunnisteen muotoarvoista, joilla pyydetään todennuskontekstia. Oletus: ["urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"].
OVERLEAF_SAML_FORCE_AUTHN
- Jos true, palveluntarjoajan ensimmäinen SAML-pyyntö määrittää, että IdP:n on pakotettava käyttäjä todentautumaan uudelleen, vaikka tällä olisi voimassa oleva istunto.
OVERLEAF_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT
- Jos true, tiettyä todennuskontekstia ei pyydetä. Voit esimerkiksi asettaa arvoksi true salliaksesi muita konteksteja, kuten salasanattomat kirjautumiset (urn:oasis:names:tc:SAML:2.0:ac:classes:X509). Muiden kontekstien tuki riippuu IdP:stäsi.
OVERLEAF_SAML_AUTHN_REQUEST_BINDING
- Jos arvoksi asetetaan HTTP-POST, todennusta pyydetään IdP:ltä HTTP POST -sidonnalla; muussa tapauksessa oletuksena on HTTP-Redirect.
OVERLEAF_SAML_VALIDATE_IN_RESPONSE_TO
- Jos always, saapuvien SAML-vastausten InResponseTo tarkistetaan.
- Jos never, InResponseTo-arvoa ei tarkisteta (oletus).
- Jos ifPresent, InResponseTo tarkistetaan vain, jos se on mukana saapuvassa SAML-vastauksessa.
OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED ja OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED
- Kun arvo on true (oletus), Overleaf odottaa IdP:n allekirjoittavan SAML-väittämät tai vastaavasti koko SAML-todennusvastauksen. Kun molemmat asetukset ovat false, vähintään joko väittämien tai vastauksen on oltava allekirjoitettu.
OVERLEAF_SAML_REQUEST_ID_EXPIRATION_PERIOD_MS
- Määrittää vanhenemisajan, jonka jälkeen SAML-pyynnölle luotu pyyntötunniste (Request ID) ei ole enää kelvollinen, jos se nähdään SAML-vastauksen InResponseTo-kentässä. Oletus: 28800000 (8 tuntia).
OVERLEAF_SAML_LOGOUT_URL
- perusosoite, jota kutsutaan uloskirjautumispyynnöillä (oletus: entryPoint).
  - Esimerkki: https://idp.example.com/simplesaml/saml2/idp/SingleLogoutService.php
OVERLEAF_SAML_ADDITIONAL_LOGOUT_PARAMS
- JSON-sanakirja lisäkyselyparametreista, jotka lisätään ‘logout’-pyyntöihin.
OVERLEAF_SAML_IS_ADMIN_FIELD ja OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE
- Kun molemmat ympäristömuuttujat on asetettu, kirjautumisprosessi asettaa user.isAdmin = true, jos SAML-identiteetintarjoajan palauttama profiili sisältää muuttujan OVERLEAF_SAML_IS_ADMIN_FIELD määrittämän attribuutin ja sen arvo joko vastaa muuttujaa OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE tai on taulukko, joka sisältää arvon OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE; muussa tapauksessa user.isAdmin asetetaan arvoon false. Jos jompaakumpaa näistä muuttujista ei ole asetettu, ylläpitäjän tila asetetaan arvoon true vain luotaessa ylläpitäjäkäyttäjää Launchpadissa.

Identiteetintarjoajan metadata Overleaf CE:n nykyinen versio sisältää päätepisteen palveluntarjoajan metadatan hakemiseen: http://my-overleaf-instance.com/saml/meta Identiteetintarjoaja on määritettävä tunnistamaan Overleaf-palvelin “palveluntarjoajaksi” (Service Provider). Katso ohjeet tähän SAML-palvelimesi dokumentaatiosta. Alla on esimerkki asianmukaisesta palveluntarjoajan metadatasta:

ol-meta.xml

<?xml version="1.0"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
                  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
                  entityID="MyOverleaf"
                  ID="_b508c83b7dda452f5b269383fb391107116f8f57">
  <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" AuthnRequestsSigned="true" WantAssertionsSigned="true">
    <KeyDescriptor use="signing">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>MII...
[skipped]
</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </KeyDescriptor>
    <KeyDescriptor use="encryption">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>MII...
[skipped]
</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
      <EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#aes256-gcm"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#aes128-gcm"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
    </KeyDescriptor>
    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                         Location="https://my-overleaf-instance.com/saml/logout/callback"/>
    <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
    <AssertionConsumerService index="1"
                              isDefault="true"
                              Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                              Location="https://my-overleaf-instance.com/saml/login/callback"/>
  </SPSSODescriptor>
</EntityDescriptor>

Pane merkille varmenteet sekä arvot AssertionConsumerService.Location, SingleLogoutService.Location ja EntityDescriptor.entityID, ja aseta ne asianmukaisesti IdP:si määrityksiin tai lähetä metadatatiedosto IdP:n ylläpitäjälle.

Esimerkki variables.env-tiedostosta (vähimmäismääritys)

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

#################
##     SAML    ##
#################

EXTERNAL_AUTH=saml
OVERLEAF_SAML_ISSUER=MyOverleaf
OVERLEAF_SAML_IDENTITY_SERVICE_NAME='Log in with SAML Provider'
OVERLEAF_SAML_EMAIL_FIELD=Email
OVERLEAF_SAML_FIRST_NAME_FIELD=DisplayName
OVERLEAF_SAML_LAST_NAME_FIELD=DisplayName
OVERLEAF_SAML_ENTRYPOINT=http://localhost:18000/login/saml/authorize/admin/SAML_Overleaf
OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem
OVERLEAF_SAML_SIGNATURE_ALGORITHM=

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.

Luo tarjoaja ja sovellus

Avaa Authentikissa Applications > Applications ja napsauta New Application. Ohjattu toiminto luo sovelluksen ja sen tarjoajan samalla kertaa.1. Anna sovellukselle nimi ja slug, esimerkiksi overleaf, ja napsauta Next:

2. Valitse SAML Provider ja napsauta Next:

3. Täytä tarjoajan tiedot:

Authorization Flow: default-provider-authorization-implicit-consent
ACS URL: https://overleaf.example.com/saml/login/callback
Audience: nimi Overleafille, esimerkiksi overleaf. Overleaf lähettää sen arvona OVERLEAF_SAML_ISSUER.

4. Avaa Advanced protocol settings ja aseta:

Signing Certificate: varmenne, esimerkiksi authentik Self-signed Certificate
Sign assertions ja Sign responses: molemmat käytössä
Service Provider Binding: Post

Authentik: testatun tarjoajan allekirjoitus ja sidonta (testi-instanssi)

5. Napsauta Next, kunnes olet viimeisellä sivulla, ja tallenna sovellus.

Kopioi arvot tarjoajan sivulta

Avaa tarjoaja uudelleen. Kaikki, mitä Overleaf tarvitsee, löytyy sen yleiskatsauksesta:

Authentik: SAML-tarjoajan yleiskatsaus (testi-instanssi)

Tarjoajan sivulla	Ympäristömuuttuja
SAML Endpoint	`OVERLEAF_SAML_ENTRYPOINT` ja `OVERLEAF_SAML_LOGOUT_URL`
Audience	`OVERLEAF_SAML_ISSUER`
Download signing certificate (tiedosto)	`OVERLEAF_SAML_IDP_CERT`, katso seuraava vaihe

EntityID/Issuer kohdassa SAML Configuration on Authentikin itsensä nimi. Älä aseta sitä muuttujaan OVERLEAF_SAML_ISSUER, vaan käytä Audience-arvoa.

Asenna allekirjoitusvarmenne

Napsauta Download kohdassa Download signing certificate ja tallenna tiedosto nimellä data/overleaf/certs/idp_cert.pem Toolkit-hakemistoosi. Kontti näkee sen polussa /var/lib/overleaf/certs/idp_cert.pem:

OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem

Määritä attribuutit

Authentik lähettää attribuuttinsa seuraavilla nimillä:

OVERLEAF_SAML_USER_ID_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_EMAIL_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
OVERLEAF_SAML_FIRST_NAME_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
OVERLEAF_SAML_LAST_NAME_FIELD=http://schemas.goauthentik.io/2021/02/saml/username

Ryhmät tulevat attribuutissa http://schemas.xmlsoap.org/claims/Group luettelona. Jos haluat Authentik-ryhmän Admins jäsenistä Overleafin ylläpitäjiä:

OVERLEAF_SAML_IS_ADMIN_FIELD=http://schemas.xmlsoap.org/claims/Group
OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE=Admins

Ylläpitäjän tila päivitetään jokaisella SAML-kirjautumisella. Jos kenttä tai arvo on väärä, jokainen SAML:n kautta kirjautuva ylläpitäjä menettää ylläpitäjän oikeutensa. Testaa määritys ensin toisella ylläpitäjätilillä.

Testattu variables.env-tiedosto goauthentikille

variables.env

EXTERNAL_AUTH=saml
OVERLEAF_SAML_IDENTITY_SERVICE_NAME=Log in with Authentik
OVERLEAF_SAML_ENTRYPOINT=https://authentik.example.com/application/saml/overleaf/
OVERLEAF_SAML_LOGOUT_URL=https://authentik.example.com/application/saml/overleaf/
OVERLEAF_SAML_ISSUER=overleaf
OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem
OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED=true
OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED=true
OVERLEAF_SAML_USER_ID_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_EMAIL_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
OVERLEAF_SAML_FIRST_NAME_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
OVERLEAF_SAML_LAST_NAME_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_IS_ADMIN_FIELD=http://schemas.xmlsoap.org/claims/Group
OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE=Admins
OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN=true

Yleiskatsaus

Asennus

Määritys

Ylläpito

Käyttäjien ja projektien hallinta

Tuki

Määritys

Ympäristömuuttujat

Vaihe vaiheelta: goauthentik

​Määritys

​Ympäristömuuttujat

​Vaihe vaiheelta: goauthentik

Määritys

Ympäristömuuttujat

Vaihe vaiheelta: goauthentik