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, which may appear as 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 (provided the server is configured for auto-creation.)

Configure SAML Authentication

  • Go to (Admin) > Site > Admin Console.
  • Click the Admin Console Links tab.
  • In the Configuration section, click Authentication.
  • If desired, you can Pick Logos for the page header and login page.
  • 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.)

Configure the following properties:

  • Upload Types: For each certificate and key field, select the type of upload:
    • Copy/Paste to paste the content of an X.509 certificate or key pem file.
    • File and click the button to upload.
  • Certificates and Keys:
    • IdP Signing Certificate: Required. 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. The target IdP (identity provider) URL for SSO authentication, where the SAML identity provider is found.
  • Issuer URL: Optional. 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. 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. 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.
  • Assertion Customer Service (ACS) URL: The ACS URL for this server is show in the UI. It is a combination of the base server EntityID and "saml-validate.view"
  • EntityId: The base server entity id is shown here and can be reconfigured if necessary. See note below.
  • Click Save.
  • On the main Authentication configuration page, next to SAML, click Enable and then Done.
EntityId / entity_id

Note that the Base Server URL is included in the SAML request as the EntityId / entity_id. To control the Base Server URL, use the page link in the UI or:

  • Go to (Admin) > Site > Admin Console.
  • Click the Admin Console Links tab.
  • Under Configuration, 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 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.
  • 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)


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all