Plans and pricingTemplatesLaTeX helpGo to Overleaf

SAML 2.0

Server Pro provides SAML 2.0 server integration for user authentication. For Toolkit deployments, the SAML 2.0 integration is configured via the config/variables.env file.

Overview

Internally, the Overleaf SAML 2.0 integration uses the passport-SAML library. Most of these configuration options are passed through to the server configuration object which is used to configure passport-SAML.

If you are having issues configuring SAML 2.0, it is worth reading the README for passport-SAML to get a feel for the configuration it expects.

To enable the SAML 2.0 module, the EXTERNAL_AUTH variable must be set to saml:

EXTERNAL_AUTH=saml

To preserve backward compatibility with older configuration files, if EXTERNAL_AUTH is not set, but OVERLEAF_SAML_ENTRYPOINT is set, then the SAML 2.0 module will be activated. We still recommend setting EXTERNAL_AUTH explicitly

Configuration

Name
Description

OVERLEAF_SAML_IDENTITY_SERVICE_NAME

Display name for the Identity Provider, used on the login page.

OVERLEAF_SAML_EMAIL_FIELD

Name of the Email field in user profile, defaults to nameID. Alias: OVERLEAF_SAML_EMAIL_FIELD_NAME

OVERLEAF_SAML_FIRST_NAME_FIELD

Name of the firstName field in user profile, defaults to givenName

OVERLEAF_SAML_LAST_NAME_FIELD

Name of the lastName field in user profile, defaults to lastName

OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN

If set to true, will update the users firstName and lastName fields on each login, and turn off the user-details form on /user/settings page.

OVERLEAF_SAML_ENTRYPOINT

Entrypoint URL for the SAML Identity Service Example: https://idp.example.com/simplesaml/saml2/idp/SSOService.php Azure: https://login.microsoftonline.com/8b26b46a-6dd3-45c7-a104-f883f4db1f6b/saml2

OVERLEAF_SAML_CALLBACK_URL

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

OVERLEAF_SAML_ISSUER

The issuer name

OVERLEAF_SAML_CERT

(required since 2.7.0) Identity Provider's public signing certificate, used to validate incoming SAML messages, in single-line format. Example: MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh...W== - See more information about passing keys and certificates. - See full documentation for more information. - An array of certificates can be provided to support certificate rotation as of 5.1.0.

OVERLEAF_SAML_PRIVATE_CERT

Optional, path to a file containing a PEM-formatted private key used to sign auth requests sent by passport-saml. Note: This would be better called PRIVATE_KEY_FILE, but PRIVATE_CERT is the current name. See more information about passing keys and certificates - See full documentation for more information.

OVERLEAF_SAML_DECRYPTION_CERT

Optional, public certificate matching the OVERLEAF_SAML_DECRYPTION_PVK, used for the metadata endpoint. - See more information about passing keys and certificates for how to pass the certificate. - See full documentation for more information.

OVERLEAF_SAML_SIGNING_CERT

Optional, public certificate matching OVERLEAF_SAML_PRIVATE_CERT. It's required when setting up the metadata endpoint if the strategy is configured with a OVERLEAF_SAML_PRIVATE_CERT. - An array of certificates can be provided to support certificate rotation. When supplying an array of certificates, the first entry in the array should match the current OVERLEAF_SAML_PRIVATE_CERT. - See more information about passing keys and certificates for how to pass the certificate. - See full documentation for more information.

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

OVERLEAF_SAML_SIGNATURE_ALGORITHM

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

OVERLEAF_SAML_ADDITIONAL_PARAMS

JSON dictionary of additional query params to add to all requests

OVERLEAF_SAML_ADDITIONAL_AUTHORIZE_PARAMS

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

OVERLEAF_SAML_IDENTIFIER_FORMAT

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

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

OVERLEAF_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)

OVERLEAF_SAML_AUTHN_CONTEXT

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

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

OVERLEAF_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT

If true, do not request a specific auth context. For example, you can this this to true to allow additional contexts such as password-less logins (urn:oasis:names:tc:SAML:2.0:ac:classes:X509). Support for additional contexts is dependant on your IdP.

OVERLEAF_SAML_SKIP_REQUEST_COMPRESSION

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

OVERLEAF_SAML_AUTHN_REQUEST_BINDING

If set to HTTP-POST, will request authentication from IDP via HTTP POST binding, otherwise defaults to HTTP Redirect Note: If OVERLEAF_SAML_AUTHN_REQUEST_BINDING is set to HTTP-POST, then OVERLEAF_SAML_SKIP_REQUEST_COMPRESSION must also be set to true.

OVERLEAF_SAML_VALIDATE_IN_RESPONSE_TO

If truthy, then InResponseTo will be validated from incoming SAML responses

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

OVERLEAF_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 for more information.

OVERLEAF_SAML_LOGOUT_URL

Base address to call with logout requests - Default: entryPoint

OVERLEAF_SAML_LOGOUT_CALLBACK_URL

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

OVERLEAF_SAML_ADDITIONAL_LOGOUT_PARAMS

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

OVERLEAF_SAML_IS_ADMIN_FIELD and OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE

When both environment variables are set, the login process updates user.isAdmin = true when the profile returned by the SAML IdP contains OVERLEAF_SAML_IS_ADMIN_FIELD, and its value is either equals to OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE, or an array containing OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE. - Introduced: 5.2.0

OVERLEAF_SAML_AUDIENCE

Used to set the value for the Audience used in the Server Pro metadata (/saml/meta). - Default: When not set defaults to using OVERLEAF_SAML_ISSUER

Passing keys and certificates

As of Server Pro 2.7.0:

  • The value of the OVERLEAF_SAML_CERT environment variable cannot be empty if SAML 2.0 is enabled (with EXTERNAL_AUTH=saml, or if OVERLEAF_SAML_ENTRYPOINT is set).

As of Server Pro 2.5.0:

  • The value of the OVERLEAF_SAML_CERT environment variable must be passed in single-line format (without the begin and end lines from the PEM format; see below for more information).

  • The value of the OVERLEAF_SAML_PRIVATE_CERT environment variable should be a full path to a file which contains the private key in PEM format.

  • The value of the OVERLEAF_SAML_DECRYPTION_PVK environment variable must be passed in PEM format (multi-line). (But single-line may be supported soon.)

To pass a key or certificate in multi-line format, wrap the entire value in double quotes and use new line characters (\n) as usual:

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

Your Identity Provider (IdP) will need to be configured to recognize your Server Pro instance as a Service Provider (SP). How this is done will vary between different IdP's - we therefore recommend that you consult the documentation for your SAML 2.0 server for instructions on how to do this.

As of version 2.6.0, Server Pro includes a metadata endpoint which can be used to retrieve Service Provider Metadata from, for example https://my-overleaf-instance.com/saml/meta

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

PreviousLDAPNextSandboxed Compiles

Last updated

Was this helpful?