Ctrlk
Plans and pricingTemplatesLaTeX helpGo to Overleaf
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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?