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.

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.

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

Create a New SAML Authentication Provider

  • Go to (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • In the Configuration section, click Authentication.
  • Select Add > SAML ...

Configure an Existing SAML Provider

  • Go to (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • In the Configuration section, click Authentication.
  • Click Edit next to the target SAML configuration.

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:

  • Description: Provide a unique description of this provider.
  • IdP Signing Cert Upload Type: 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. Either paste an X.509 certificate/pem file directly into the text area or upload a pem file.
  • Encryption Cert Upload Type: Select Copy/Paste or File.
  • Encryption Certificate (Optional): The encryption certificate for the service provider (SP). Use this field and the SP Private Key field (below) if you want the assertion in the SAML response to be encrypted. These two field work together: they either must both be set, or neither should be set.
  • SP Private Key Upload Type: Select Copy/Paste or File.
  • SP Private Key (Optional): The private key for the service provider (SP). Use this field and the Encryption Certificate field (above) if you want the assertion in the SAML response to be encrypted. These two 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: 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.
  • EntityId: The base server entity id is shown here and can be reconfigured if necessary. See note below.
  • 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".
  • Enabled: Turn on the provider. (This value is displayed on the main Authentication dashboard.)
  • Page header logo / **Login page logo**: Upload logo images to brand the login UI. See similar logo fields in the CAS documentation: Configure CAS Single Sign On Authentication (SSO).
  • Click Save.

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 Settings 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 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.
If your IdP requires Service Provider XML Metadata, you can generate the XML using a tool such as:
  • 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)

Related Topics


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all