Premium Feature — Available in the Professional, Professional Plus, and Enterprise Editions. Learn more or contact LabKey

LabKey Server supports SAML authentication, acting as a service provider to authenticate against a SAML 2.0 identity provider. You can configure LabKey Server to authenticate against a single SAML identity provider (IdP). LabKey Server supports either plain text or encrypted assertion responses from the SAML identity provider. Note that nameId attribute in the assertion must match the email address in the user's LabKey Server account.

How SAML Authentication Works

From a LabKey sign in page, or next to the Sign In link in the upper right, a user clicks the “SAML” link. As with other authentication providers, this link can be configured with a logo. LabKey generates a SAML request, and redirects the user’s browser to the identity provider's SSO URL with the request attached.

The identity provider (IdP) presents the user with its authentication challenge. This is typically in the form of a login screen, but more sophisticated systems might use biometrics, authentication dongles, or other two-factor authentication mechanisms. If the IdP verifies the user against its user store, a signed SAML response is generated, and redirects the user’s browser back to LabKey Server with the response attached.

LabKey Server then verifies the signature of the response, decrypts the assertion if it was optionally encrypted, and verifies the email address from the nameId attribute. At this point, the user is considered authenticated with LabKey Server and directed to the server home page (or to whatever page the user was originally attempting to reach). LabKey Server will auto-create the user if they don’t exist (provide the server is configured for auto-creation.)

Configure SAML Authentication

• Go to Admin > Site > Admin Console. In the Configuration section, click Authentication.
• You can add logo images that will appear on the standard LabKey sign in page or on the page header "Sign In" link in the upper right. To add logo images, click Pick Logos, and click Choose File for the page header and/or login page links. See the Configure CAS Single Sign On Authentication topic for screenshots of the logo locations.
• Next to SAML, click Configure.
• Note that the configuration settings make use of the encrypted property store, so in order to configure/use SAML, the MasterEncryptionKey must be set in the labkey.xml file. (If it’s not set, attempting to go to the SAML configuration screen displays an error message, directing the administrator to configure the labkey.xml file.)

• Upload Type: For each certificate and key field, select Copy/Paste to paste the content of an X.509 certificate or key pem file. Select File to upload a pem file.
• IdP Signing Certificate: Required field. Either paste an X.509 certificate/pem file directly into the text area or upload a pem file.
• Encryption Certificate and SP Private Key: Optional fields. The encryption certificate and private key for the service provider (SP) Use these fields if you want the assertion in the SAML response to be encrypted. These field work together: they either must both be set, or neither should be set.
• IdP SSO URL: Required field. The target IdP (identity provider) URL for SSO authentication, where the SAML identity provider is found.
• Issuer URL: Optional field. The issuer of the service provider SAML metadata. Some IdP configurations require this, some do not. If required, it’s probably the base URL for the LabKey Server instance.
• NameIdformat: Optional field. This is the NameIdformat specified in the SAML request. Default is emailAddress. Options are emailAddress, transient, and unspecified. If IdP does not support “emailAddress”, one of the other formats may work.
• Force Authorization: Optional field. If checked, sets the “ForceAuthn” attribute in the SAML request, instructing the IdP to ignore any session the user may already have with the IdP and require the user to authenticate again.
• Click Save.
• On the main Authentication configuration page, next to SAML, click Enable and then Done.

Screenshots below show configuration for an environment running against a Shibboleth identity provider.

SAML Terminology

• IdP: Identity Provider. The authenticating SAML server. This may be software (Shibboleth and OpenAM are two open source software IdPs), or hardware (e.g., an F5 BigIp appliance with the APM module). This will be connected to a user store, frequently an LDAP server.
• SP: Service Provider. The application or server requesting authentication.
• SAML Request: The request sent to the IdP to attempt to authenticate the user. Note that the Base Server URL is included in the SAML request as the EntityId. To control the Base Server URL, go to Admin > Site > Admin Console and click Site Settings. On the Customize Site page, change the Base Server URL as necessary. Note that changing this setting will effect links in emails sent by the server, as well as any short URLs you generate. For details see Site Settings.
• SAML Response: The response back from the IdP that the user was authenticated. A request contains an assertion about the user. The assertion contains one or more attributes about the user. At very least the nameId attribute is included, which is what identifies the user.

SAML Functionality Not Currently Supported

• Metadata generation - LabKey Server supports only static service provider metadata xml.
• Metadata discovery - LabKey Server does not query an IdP for its metadata, nor does the server respond to requests for its service provider metadata.
• Federation participation is not supported.
• More complex scenarios for combinations of encrypted or signed requests, responses, assertions, and attributes are not supported. For example, signed assertions with individually encrypted attributes.
• Processing other attributes about the user. For example, sometimes a role or permissions are given in the assertion; LabKey Server ignores these if present.
• Interaction with an independent service provider is not supported.
• Single logout (SLO)