Premium Feature — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

LabKey Server supports SAML (Security Assertion Markup Language) 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. If a given SAML identity provider is configured as the default, the user will bypass the sign in page and go directly to the identity provider.

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

Auto Create Authenticated Users

If a user is authenticated by the SAML server but does not already have an account on the LabKey Server, the system can create one automatically. This is enabled by default but can be disabled using a checkbox in the global settings of the authentication page

Create a New SAML Authentication Configuration

  • Go to (Admin) > Site > Admin Console.
  • In the Configuration section, click Authentication.
  • On the Primary tab of the Configurations panel, select Add New Primary Configuration > SAML...
  • In the popup, configure the properties as described below.
  • Click Finish to save.

You can create multiple SAML configurations on the same server.

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 properties for SAML authentication:

  • Configuration Status: Click the slider to toggle between:
    • Enabled
    • Disabled
  • Description: Provide a unique description of this provider.
  • IdP Signing Certificate: Required. Either drag and drop or click to select a pem 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 fields work together: they either must both be set, or neither should be set.
  • 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 fields 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. Options are:
    • Email Address (Default)
    • Transient
    • Unspecified
  • Force Authorization: If checked, require the user to login again via IdP, even if they are already logged in via an SSO provider.
  • 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 a combination of the base server EntityID and "saml-validate.view?configuration=" followed by the configurationId you must locate. See below. If you are using the LabKey login page as the entry point for SAML login, you may omit the configuration parameter.
  • Default to this SAML Identity Provider: Check the box to redirect the login page directly to this SAML identity provider instead of requiring the user to click on a logo first.
  • 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 Finish in the popup to save.

EntityId / entity_id (Base Server URL)

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 "Customize Site page" link in the UI or:

  • Go to (Admin) > Site > Admin Console.
  • 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.

Assertion Consumer Service (ACS) URL Configuration ID

The ACS URL is shown in the configuration settings panel relative to the base server URL shown in the EntityId field. If the LabKey login page is used as the SAML entry point, it can look like:

<base server URL>/<context path>/saml-validate.view?
If the entry point for SAML login is not the LabKey login page, you must also include the configuration parameter in the ACS URL. It will look like the following, where you must provide the actual configuration id:
<base server URL>/<context path>/saml-validate.view?configuration=CONFIGURATIONID

To determine the configuration ID, the easiest way is to access the LabKey login page, hover over the 'SAML configuration' link and observe the URL in the lower left. For example if it reads "https//localhost:8443/labkey/login-ssoRedirect.view?configuration=1" then use 1 as the configuration Id in the ACS URL.

If your ACS URL is missing the configuration parameter, you will see the error "SAML configuration not found."

Edit an Existing SAML Provider

  • Go to (Admin) > Site > Admin Console.
  • In the Configuration section, click Authentication.
  • Click the (pencil) next to the target SAML configuration to edit the configuration.
  • After making changes, click Apply in the popup, then Save and Finish to exit the authentication page.

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