Server Pro: SAML Config

Overleaf SAML

Available in Overleaf Server Pro is the ability to use a SAML server to manage users.

Configuration

In Overleaf Server Pro, the SAML auth module is configured via environment variables.

Internally, the passport-saml module is used, and these config values are passed along to passport-saml.

• SHARELATEX_SAML_IDENTITY_SERVICE_NAME

  • Display name for the Identity service, used on the login page

• SHARELATEX_SAML_EMAIL_FIELD

  • Name of the Email field in user profile, default to 'nameID'. Alias: SHARELATEX_SAML_EMAIL_FIELD_NAME

• SHARELATEX_SAML_FIRST_NAME_FIELD

  • Name of the firstName field in user profile, default to 'givenName'

• SHARELATEX_SAML_LAST_NAME_FIELD

  • Name of the lastName field in user profile, default to 'lastName'

• SHARELATEX_SAML_UPDATE_USER_DETAILS_ON_LOGIN

  • If set to true, will update the user first_name and last_name field on each login, and turn off the user-details form on /user/settings page.

• SHARELATEX_SAML_ENTRYPOINT

  • Entrypoint url for the SAML Identity Service

• SHARELATEX_SAML_CALLBACK_URL

  • Callback URL for Overleaf service. Should be the full URL of the /saml/callback path. Example: http://sharelatex.example.com/saml/callback

• SHARELATEX_SAML_ISSUER

  • The Issuer name

• SHARELATEX_SAML_CERT

  • (optional) Identity Provider's public signing certificate, used to validate incoming SAML messages, in single-line or PEM format.
    • Example: MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh...W==
    • See more information about passing keys and certificates.
    • See full documentation for more information.

• SHARELATEX_SAML_PRIVATE_CERT

  • (optional) Private key used to sign auth requests sent by passport-saml, in single-line or PEM format.
    • Example: MIIEowIBAAKCAQEAxmJWY0eJcuV2uBtLn...YRk
    • Note: This would be better called PRIVATE_KEY, but PRIVATE_CERT is the current name.
    • See more information about passing keys and certificates.
    • See full documentation for more information.

• SHARELATEX_SAML_DECRYPTION_PVK

  • (optional) Private key that will be used to attempt to decrypt any encrypted assertions that are received, in PEM (multi-line) format.
    • See more information about passing keys and certificates for how to pass the key in PEM format.
    • See full documentation for more information.

• SHARELATEX_SAML_SIGNATURE_ALGORITHM

  • Optionally set the signature algorithm for signing requests, valid values are 'sha1' (default) or 'sha256'

• SHARELATEX_SAML_ADDITIONAL_PARAMS

  • JSON dictionary of additional query params to add to all requests

• SHARELATEX_SAML_ADDITIONAL_AUTHORIZE_PARAMS

  • JSON dictionary of additional query params to add to 'authorize' requests Example: {"some_key": "some_value"}

• SHARELATEX_SAML_IDENTIFIER_FORMAT

  • if present, name identifier format to request from identity provider (default: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)

• SHARELATEX_SAML_ACCEPTED_CLOCK_SKEW_MS

  • Time in milliseconds of skew that is acceptable between client and server when checking OnBefore and NotOnOrAfter assertion condition validity timestamps. Setting to -1 will disable checking these conditions entirely. Default is 0.

• SHARELATEX_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX

  • optional AttributeConsumingServiceIndex attribute to add to AuthnRequest to instruct the IDP which attribute set to attach to the response (link)

• SHARELATEX_SAML_AUTHN_CONTEXT

  • if present, name identifier format to request auth context (default: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport)

• SHARELATEX_SAML_FORCE_AUTHN

  • if true, the initial SAML request from the service provider specifies that the IdP should force re-authentication of the user, even if they possess a valid session.

• SHARELATEX_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT

  • if true, do not request a specific auth context

• SHARELATEX_SAML_SKIP_REQUEST_COMPRESSION

  • if set to true, the SAML request from the service provider won't be compressed.

• SHARELATEX_SAML_AUTHN_REQUEST_BINDING

  • if set to HTTP-POST, will request authentication from IDP via HTTP POST binding, otherwise defaults to HTTP Redirect

• SHARELATEX_SAML_VALIDATE_IN_RESPONSE_TO

  • if truthy, then InResponseTo will be validated from incoming SAML responses

• SHARELATEX_SAML_REQUEST_ID_EXPIRATION_PERIOD_MS

  • Defines the expiration time when a Request ID generated for a SAML request will not be valid if seen in a SAML response in the InResponseTo field. Default is 8 hours.

• SHARELATEX_SAML_CACHE_PROVIDER

  • Defines the implementation for a cache provider used to store request Ids generated in SAML requests as part of InResponseTo validation. Default is a built-in in-memory cache provider. See link

• SHARELATEX_SAML_LOGOUT_URL

  • base address to call with logout requests (default: entryPoint)

• SHARELATEX_SAML_LOGOUT_CALLBACK_URL

  • The value with which to populate the Location attribute in the SingleLogoutService elements in the generated service provider metadata.

• SHARELATEX_SAML_ADDITIONAL_LOGOUT_PARAMS

  • JSON dictionary of additional query params to add to 'logout' requests

Using Http Post

Note, if SHARELATEX_SAML_AUTHN_REQUEST_BINDING is set to HTTP-POST, then SHARELATEX_SAML_SKIP_REQUEST_COMPRESSION must also be set to true.

Configuration Example

SHARELATEX_SAML_ENTRYPOINT=https://your-saml-server.net/simplesaml/saml2/idp/SSOService.php
SHARELATEX_SAML_CALLBACK_URL=http://your-sharelatex-server.net/saml/callback
SHARELATEX_SAML_ISSUER=sharelatex-saml
SHARELATEX_SAML_IDENTITY_SERVICE_NAME=SAML
SHARELATEX_SAML_EMAIL_FIELD=email
SHARELATEX_SAML_FIRST_NAME_FIELD=f_name
SHARELATEX_SAML_LAST_NAME_FIELD=l_name

Passing Keys and Certificates

The values of the SHARELATEX_SAML_CERT and SHARELATEX_SAML_PRIVATE_CERT environment variables can be either PEM formatted (multi-line) or single-line (as of Server Pro 2.5.0).

The value of the SHARELATEX_SAML_DECRYPTION_PVK environment variable must be PEM formatted (multi-line). (But single-line may be supported soon.)

In docker-compose (YAML) Files

To pass a key or certificate in single-line format, you can just specify it as a string (don't include the begin or end lines, any internal whitespace, or any newline escapes, e.g. \n):

  SHARELATEX_SAML_PRIVATE_CERT: MIIEowIBAAKCAQEAxmJWY0eJcuV2uBtLnQ4004fuknbODo5xIyRhkYNkls5n9OrBq4Lok6cjv7G2Q8mxAdlIUmzhTSyuNkrMMKZrPaMsAkNKE/aNpeWuSLXqcMs8T/8gYCDcEmC5KYEJakNtKb3ZX2FKwT4yHHpsNomLDzJD5DyJKbRpNBm2no7ggIy7TQRJ2H00mogQIQu8/fUANXVeGPshvLJU8MXEy/eiXkHJIT3DDA4VSr/C/tfP0tGJSNTM874urc4zej+4INuTuMPtesZS47J0AsPxQuxengS4M76cVt5cH+Iqd1nKe5UqiSKvLCXacPYg/T/Kdx0tBnwHIjKo/cbzZ+r+XynsCwIDAQABAoIBAFPWWwu5v6x+rJ1Ba8MDre93Eqty6cHdEJL5XQJRtMDGmcg3LYF94SwFBmaMg6pCIjvVx2qN+OjUaQsosQIeUlPKEV8jcLrfBx2E4xJ3Tow8V1C3UMdPG7Hojler4H633/oz8RkN1Lm1vxep5PFnTw0tAOQDcTPeulb6RuLbHqU0FEnf/jVOMhtPLcMAwJ3fkAJQ+ljFW2VKCQ83d+ci1p+NHY/dbGLSR4lK58mVghcRMO3zhe5scrbECHJMfT6fCb2TXdjaueFUGC6+fqUXvDj8HRfUilzTegNq8ZhwgMSw1HeX/PuiczSKc3aHYSsohMBugTErnkW+qF4ZkE+kxgECgYEA/sm7umcyFuZME+RWYL8Gsp8agH1OGEgsmIiMi1z6RTlTmdR8fN18ItzXyW+363VZln/1b5wCaPdLIxgASxybLAaxnKAXfmL7QvyVAaMwxj7N0ogvMQoNx2VuSGZSam2+LFVIMWHq1C+3fvVnCDLm6oHvIMK/zvEsPBBtz+L6rlECgYEAx1PrKogaGHCi1XgsrNv9aFaayRvmhzZbmiigF0iWKAd3KKww94BdyyGSVfMfyL23LAbMQDCrDNGpYAnpNZo/cL+OcGPYzlPsWDBrJub1HOA/H3WQlP4oEcfdbmJZhIkEwTGFHaCHynEu4ekiCrWz9+XVNCquTyqnmaVDEzAfEZsCgYA8jQbfUt0Vkh+sboyUq3FVC/jJZn4jyStICNOV3z/fKbOTkGsRZbW1t1RVHAbSn23uFXTn1GTCO1sQ+QhA0YiTGvgk5+sNb0qVbd+fpv/VbWGO0iyc8+24YIOoEyEtB+21LYNdsQ6U5M4wDvQwf6BfRQfmekIJVUmU8LaYPDIlMQKBgDSRiT/aTSeM7STnYMDl89sEnCXV2eJnD5mEhVQerJs5/M8ZOoDLtfDQlctdJ1DF1/0gfdWgADyNPuI5OuwMFhciLequKoufzoEjo97KonJPIdamJs9kiCTIVTm7bmhpyns5GCZMJAPb/cVOus+gRCpozuXHK9ltIm5/C0WQN2FpAoGBAOss6RN2krieqbn1mG8e2v5mMUd0CJkiJu2y5MnF3dYHXSQ3/ePAh/YgJOthpgYgBh+mV0DLqJhx/1DLS/xiqcoHDlndQDmYbtvvY7RlMo00+nGzkRVOfrqyhC+1KsYHGPbSQixNQXtvFbAAVMSo+RRBkVGINYGDFnlQUpkppYRk

To pass a key or certificate in multi-line format, use the YAML "block literal style with chomping indicator", |-:

  SHARELATEX_SAML_PRIVATE_CERT: |-
    -----BEGIN RSA PRIVATE KEY-----
    MIIEowIBAAKCAQEAxmJWY0eJcuV2uBtLnQ4004fuknbODo5xIyRhkYNkls5n9OrB
    q4Lok6cjv7G2Q8mxAdlIUmzhTSyuNkrMMKZrPaMsAkNKE/aNpeWuSLXqcMs8T/8g
    YCDcEmC5KYEJakNtKb3ZX2FKwT4yHHpsNomLDzJD5DyJKbRpNBm2no7ggIy7TQRJ
    2H00mogQIQu8/fUANXVeGPshvLJU8MXEy/eiXkHJIT3DDA4VSr/C/tfP0tGJSNTM
    874urc4zej+4INuTuMPtesZS47J0AsPxQuxengS4M76cVt5cH+Iqd1nKe5UqiSKv
    LCXacPYg/T/Kdx0tBnwHIjKo/cbzZ+r+XynsCwIDAQABAoIBAFPWWwu5v6x+rJ1B
    a8MDre93Eqty6cHdEJL5XQJRtMDGmcg3LYF94SwFBmaMg6pCIjvVx2qN+OjUaQso
    sQIeUlPKEV8jcLrfBx2E4xJ3Tow8V1C3UMdPG7Hojler4H633/oz8RkN1Lm1vxep
    5PFnTw0tAOQDcTPeulb6RuLbHqU0FEnf/jVOMhtPLcMAwJ3fkAJQ+ljFW2VKCQ83
    d+ci1p+NHY/dbGLSR4lK58mVghcRMO3zhe5scrbECHJMfT6fCb2TXdjaueFUGC6+
    fqUXvDj8HRfUilzTegNq8ZhwgMSw1HeX/PuiczSKc3aHYSsohMBugTErnkW+qF4Z
    kE+kxgECgYEA/sm7umcyFuZME+RWYL8Gsp8agH1OGEgsmIiMi1z6RTlTmdR8fN18
    ItzXyW+363VZln/1b5wCaPdLIxgASxybLAaxnKAXfmL7QvyVAaMwxj7N0ogvMQoN
    x2VuSGZSam2+LFVIMWHq1C+3fvVnCDLm6oHvIMK/zvEsPBBtz+L6rlECgYEAx1Pr
    KogaGHCi1XgsrNv9aFaayRvmhzZbmiigF0iWKAd3KKww94BdyyGSVfMfyL23LAbM
    QDCrDNGpYAnpNZo/cL+OcGPYzlPsWDBrJub1HOA/H3WQlP4oEcfdbmJZhIkEwTGF
    HaCHynEu4ekiCrWz9+XVNCquTyqnmaVDEzAfEZsCgYA8jQbfUt0Vkh+sboyUq3FV
    C/jJZn4jyStICNOV3z/fKbOTkGsRZbW1t1RVHAbSn23uFXTn1GTCO1sQ+QhA0YiT
    Gvgk5+sNb0qVbd+fpv/VbWGO0iyc8+24YIOoEyEtB+21LYNdsQ6U5M4wDvQwf6Bf
    RQfmekIJVUmU8LaYPDIlMQKBgDSRiT/aTSeM7STnYMDl89sEnCXV2eJnD5mEhVQe
    rJs5/M8ZOoDLtfDQlctdJ1DF1/0gfdWgADyNPuI5OuwMFhciLequKoufzoEjo97K
    onJPIdamJs9kiCTIVTm7bmhpyns5GCZMJAPb/cVOus+gRCpozuXHK9ltIm5/C0WQ
    N2FpAoGBAOss6RN2krieqbn1mG8e2v5mMUd0CJkiJu2y5MnF3dYHXSQ3/ePAh/Yg
    JOthpgYgBh+mV0DLqJhx/1DLS/xiqcoHDlndQDmYbtvvY7RlMo00+nGzkRVOfrqy
    hC+1KsYHGPbSQixNQXtvFbAAVMSo+RRBkVGINYGDFnlQUpkppYRk
    -----END RSA PRIVATE KEY-----

(The above private key is an example key from the xml-encryption library's test suite. Do not use this key.)

Metadata for the Identity Provider

The Identity Provider will need to be configured to recognize the Overleaf server as a "Service Provider". Consult the documentation for your SAML server for instructions on how to do this.

Here is an example of appropriate Service Provider metadata, note the AssertionConsumerService.Location, EntityDescriptor.entityID and EntityDescriptor.ID properties, and set as appropriate.

<?xml version="1.0"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
                  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
                  entityID="sharelatex-saml"
                  ID="sharelatex_saml">
  <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <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="http://sharelatex-host/saml/callback" />
  </SPSSODescriptor>
</EntityDescriptor>