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:
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
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
OVERLEAF_SAML_PRIVATE_CERT
OVERLEAF_SAML_DECRYPTION_CERT
OVERLEAF_SAML_SIGNING_CERT
OVERLEAF_SAML_DECRYPTION_PVK
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
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
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_CERTenvironment variable cannot be empty if SAML 2.0 is enabled (withEXTERNAL_AUTH=saml, or ifOVERLEAF_SAML_ENTRYPOINTis set).
As of Server Pro 2.5.0:
The value of the
OVERLEAF_SAML_CERTenvironment 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_CERTenvironment variable should be a full path to a file which contains the private key in PEM format.The value of the
OVERLEAF_SAML_DECRYPTION_PVKenvironment 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.
Example configuration
At Overleaf, we test the SAML 2.0 integration against a SAML 2.0 test server. The following is an example of a working configuration:
The sharelatex/saml-test image needs to run in the same network as the sharelatex container (which by default would be overleaf_default), so we'll proceed with the following steps:
Run
docker network create overleaf_default(will possibly fail due to anetwork with name overleaf_default already existserror, that's ok).Start
saml-testcontainer with some environment parameters:
Edit
variables.envto add the SAML 2.0 Environment Variables as listed above.Restart Server Pro.
You should be able to login using sally as username and sally123 as password.
Last updated
Was this helpful?