> For the complete documentation index, see [llms.txt](https://docs.overleaf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/server-pro-only-configuration/saml-2.0.md).

# 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](https://github.com/vesse/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](https://github.com/node-saml/passport-saml/blob/master/README.md) 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
```

{% hint style="info" %}
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
{% endhint %}

## Configuration

<table data-full-width="false"><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code>OVERLEAF_SAML_IDENTITY_SERVICE_NAME</code></td><td>Display name for the Identity Provider, used on the login page.</td></tr><tr><td><code>OVERLEAF_SAML_EMAIL_FIELD</code></td><td>Name of the <strong>Email</strong> field in user profile, defaults to <code>nameID</code>. <strong>Alias</strong>: <code>OVERLEAF_SAML_EMAIL_FIELD_NAME</code></td></tr><tr><td><code>OVERLEAF_SAML_FIRST_NAME_FIELD</code></td><td>Name of the <strong>firstName</strong> field in user profile, defaults to <code>givenName</code></td></tr><tr><td><code>OVERLEAF_SAML_LAST_NAME_FIELD</code></td><td>Name of the <strong>lastName</strong> field in user profile, defaults to <code>lastName</code></td></tr><tr><td><code>OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN</code></td><td>If set to <code>true</code>, will update the users <strong>firstName</strong> and <strong>lastName</strong> fields on each login, and turn off the user-details form on <code>/user/settings</code> page.</td></tr><tr><td><code>OVERLEAF_SAML_ENTRYPOINT</code></td><td>Entrypoint URL for the SAML Identity Service<br><strong>Example</strong>: <code>https://idp.example.com/simplesaml/saml2/idp/SSOService.php</code><br><strong>Azure</strong>: <code>https://login.microsoftonline.com/8b26b46a-6dd3-45c7-a104-f883f4db1f6b/saml2</code></td></tr><tr><td><code>OVERLEAF_SAML_CALLBACK_URL</code></td><td>Callback URL for Overleaf service. Should be the full URL of the <code>/saml/callback</code> path.<br><strong>Example</strong>: <code>https://sharelatex.example.com/saml/callback</code></td></tr><tr><td><code>OVERLEAF_SAML_ISSUER</code></td><td>The issuer name</td></tr><tr><td><code>OVERLEAF_SAML_CERT</code></td><td>(required since <code>2.7.0</code>) Identity Provider's public signing certificate, used to validate incoming SAML messages, in single-line format.<br><strong>Example</strong>: <code>MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh...W==</code><br><br>- See <a href="/on-premises/configuration/overleaf-toolkit/environment-variables.md">more information about passing keys and certificates</a>.<br>- See <a href="https://github.com/node-saml/passport-saml/blob/master/README.md#security-and-signatures">full documentation</a> for more information.<br>- An array of certificates can be provided to support certificate rotation as of 5.1.0.</td></tr><tr><td><code>OVERLEAF_SAML_PRIVATE_CERT</code></td><td><strong>Optional</strong>, path to a file containing a PEM-formatted private key used to sign auth requests sent by passport-saml.<br><strong>Note</strong>: This would be better called <code>PRIVATE_KEY_FILE</code>, but <code>PRIVATE_CERT</code> is the current name.<br><br>See <a href="/on-premises/configuration/overleaf-toolkit/environment-variables.md">more information about passing keys and certificates</a><br>- See <a href="https://github.com/node-saml/passport-saml/blob/master/README.md#security-and-signatures">full documentation</a> for more information.</td></tr><tr><td><code>OVERLEAF_SAML_DECRYPTION_CERT</code></td><td><strong>Optional</strong>, public certificate matching the <code>OVERLEAF_SAML_DECRYPTION_PVK</code>, used for the <a href="/on-premises/configuration/overleaf-toolkit/environment-variables.md">metadata endpoint</a>.<br><br>- See <a href="/on-premises/configuration/overleaf-toolkit/environment-variables.md">more information about passing keys and certificates</a> for how to pass the certificate.<br>- See <a href="https://github.com/node-saml/passport-saml/blob/master/README.md#security-and-signatures">full documentation</a> for more information.</td></tr><tr><td><code>OVERLEAF_SAML_SIGNING_CERT</code></td><td><strong>Optional</strong>, public certificate matching <code>OVERLEAF_SAML_PRIVATE_CERT</code>. It's required when setting up the <a href="/on-premises/configuration/overleaf-toolkit/environment-variables.md">metadata endpoint</a> if the strategy is configured with a <code>OVERLEAF_SAML_PRIVATE_CERT</code>.<br><br>- 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 <code>OVERLEAF_SAML_PRIVATE_CERT</code>.<br>- See <a href="/on-premises/configuration/overleaf-toolkit/environment-variables.md">more information about passing keys and certificates</a> for how to pass the certificate.<br>- See <a href="https://github.com/node-saml/passport-saml/blob/master/README.md#security-and-signatures">full documentation</a> for more information.</td></tr><tr><td><code>OVERLEAF_SAML_DECRYPTION_PVK</code></td><td><strong>Optional</strong>, private key that will be used to attempt to decrypt any encrypted assertions that are received, in PEM (multi-line) format.<br><br>- See <a href="/on-premises/configuration/overleaf-toolkit/environment-variables.md">more information about passing keys and certificates</a> for how to pass the key in PEM format.<br>- See <a href="https://github.com/node-saml/passport-saml/blob/master/README.md#security-and-signatures">full documentation</a> for more information.</td></tr><tr><td><code>OVERLEAF_SAML_SIGNATURE_ALGORITHM</code></td><td>Optionally set the signature algorithm for signing requests, valid values are <code>sha1</code> (default) or <code>sha256</code></td></tr><tr><td><code>OVERLEAF_SAML_ADDITIONAL_PARAMS</code></td><td>JSON dictionary of additional query params to add to all requests</td></tr><tr><td><code>OVERLEAF_SAML_ADDITIONAL_AUTHORIZE_PARAMS</code></td><td>JSON dictionary of additional query params to add to 'authorize' requests.<br><br><strong>Example</strong>: <code>{"some_key": "some_value"}</code></td></tr><tr><td><code>OVERLEAF_SAML_IDENTIFIER_FORMAT</code></td><td>If present, name identifier format to request from identity provider (<strong>Default</strong>: <code>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</code>)</td></tr><tr><td><code>OVERLEAF_SAML_ACCEPTED_CLOCK_SKEW_MS</code></td><td>Time in milliseconds of skew that is acceptable between client and server when checking OnBefore and NotOnOrAfter assertion condition validity timestamps. Setting to <code>-1</code> will disable checking these conditions entirely. <strong>Default</strong> is <code>0</code>.</td></tr><tr><td><code>OVERLEAF_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX</code></td><td><strong>Optional</strong>, <code>AttributeConsumingServiceIndex</code> attribute to add to AuthnRequest to instruct the IdP which attribute set to attach to the response (<a href="http://blog.aniljohn.com/2014/01/data-minimization-front-channel-saml-attribute-requests.html">link</a>)</td></tr><tr><td><code>OVERLEAF_SAML_AUTHN_CONTEXT</code></td><td>If present, name identifier format to request auth context (<strong>Default</strong>: <code>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</code>)</td></tr><tr><td><code>OVERLEAF_SAML_FORCE_AUTHN</code></td><td>If <code>true</code>, 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.</td></tr><tr><td><code>OVERLEAF_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT</code></td><td>If <code>true</code>, do not request a specific auth context. For example, you can this this to <code>true</code> to allow additional contexts such as password-less logins (<code>urn:oasis:names:tc:SAML:2.0:ac:classes:X509</code>). Support for additional contexts is dependant on your IdP.</td></tr><tr><td><code>OVERLEAF_SAML_SKIP_REQUEST_COMPRESSION</code></td><td>If set to <code>true</code>, the SAML request from the service provider won't be compressed.</td></tr><tr><td><code>OVERLEAF_SAML_AUTHN_REQUEST_BINDING</code></td><td>If set to <code>HTTP-POST</code>, will request authentication from IDP via HTTP POST binding, otherwise defaults to HTTP Redirect<br><br><strong>Note:</strong> If <code>OVERLEAF_SAML_AUTHN_REQUEST_BINDING</code> is set to <code>HTTP-POST</code>, then <code>OVERLEAF_SAML_SKIP_REQUEST_COMPRESSION</code> must also be set to <code>true</code>.</td></tr><tr><td><code>OVERLEAF_SAML_VALIDATE_IN_RESPONSE_TO</code></td><td>If truthy, then <code>InResponseTo</code> will be validated from incoming SAML responses</td></tr><tr><td><code>OVERLEAF_SAML_REQUEST_ID_EXPIRATION_PERIOD_MS</code></td><td>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 <code>InResponseTo</code> field. <strong>Default</strong> is <code>8</code> hours.</td></tr><tr><td><code>OVERLEAF_SAML_CACHE_PROVIDER</code></td><td>Defines the implementation for a cache provider used to store request Ids generated in SAML requests as part of <code>InResponseTo</code> validation. <strong>Default</strong> is a built-in in-memory cache provider.<br><br>See <a href="https://github.com/node-saml/passport-saml/blob/master/README.md">link</a> for more information.</td></tr><tr><td><code>OVERLEAF_SAML_LOGOUT_URL</code></td><td>Base address to call with logout requests <br><br>- <strong>Default</strong>: <code>entryPoint</code></td></tr><tr><td><code>OVERLEAF_SAML_LOGOUT_CALLBACK_URL</code></td><td>The value with which to populate the <code>Location</code> attribute in the <code>SingleLogoutService</code> elements in the generated service provider metadata.</td></tr><tr><td><code>OVERLEAF_SAML_ADDITIONAL_LOGOUT_PARAMS</code></td><td>JSON dictionary of additional query params to add to 'logout' requests</td></tr><tr><td><p></p><p><code>OVERLEAF_SAML_IS_ADMIN_FIELD</code> and <code>OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE</code></p></td><td><p></p><p>When <strong>both</strong> environment variables are set, the login process updates <code>user.isAdmin = true</code> when the profile returned by the SAML IdP contains <code>OVERLEAF_SAML_IS_ADMIN_FIELD</code>, and its value is either equals to <code>OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE</code>, or an array containing <code>OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE</code>.<br><br>- <strong>Introduced</strong>: <code>5.2.0</code></p></td></tr><tr><td><code>OVERLEAF_SAML_AUDIENCE</code></td><td>Used to set the value for the Audience used in the Server Pro metadata (/saml/meta).<br><br>- <strong>Default</strong>: When <strong>not</strong> set defaults to using <code>OVERLEAF_SAML_ISSUER</code></td></tr></tbody></table>

### 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](https://github.com/node-saml/passport-saml/issues/524).)

{% code overflow="wrap" %}

```env
OVERLEAF_SAML_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
```

{% endcode %}

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:

```env
OVERLEAF_SAML_DECRYPTION_PVK="-----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-----"
```

{% hint style="danger" %}
The above private key is an example key from the [`xml-encryption`](https://github.com/auth0/node-xml-encryption/blob/435b1d0f01b1f218c51f07b01fb90df4a4e108de/test/test-auth0.key) library's test suite. **Do not use this key.**
{% endhint %}

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

{% code overflow="wrap" %}

```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="sharelatex-saml"
                  ID="OVERLEAF_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="https://sharelatex.example.com/saml/callback" />
  </SPSSODescriptor>
</EntityDescriptor>
```

{% endcode %}