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 header menu, a user clicks the admin-configured "SAML" 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 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.
Step 1: Configure your SAML Identity Provider
Before you begin, ensure that you can log in using standard database configuration (i.e. that you have
not disabled this default login mechanism). You may need it to recover if you make a configuration error.
Step 1: First, you will set up your SAML Identity Provider to both obtain an IdP signing certificate, and provide other details including the full
ACS URL.
Use values in the
Configuration Details for IdP section of the
configuration panel from the LabKey UI:
- EntityId: Often, but not necessarily the base server URL, sometimes also referred to on the IdP as the "Entity" or "Identifier".
- ACS URL: Shown in the UI, the Assertion Consumer Service (ACS) URL will be the EntityId, a context path if necessary, and the controller-action: "saml-validate.view". You'll provide this value on your IdP indicating where the login will redirect for authentication.
Different IdPs vary in how they are configured and how you will obtain the signing certificate. Depending on your IdP, you may have various requirements or terms for the same URLs, such as "Reply URL", "Sign-on URL", "Destination URL", and/or "Recipient URL".
The
IdP signing certificate must be in PEM format. A PEM format certificate will start/end with:
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
Once you have the certificate and other details, you will
create the SAML Authentication Configuration as described below.
Upgrade Note for Switching to a Root Deployment
Upgrade note: When upgrading to use embedded Tomcat, we strongly recommend that you deploy LabKey at the root.
If you were previously using a configuration file named "labkey.xml", you will have been using a "/labkey" context path. This was previously part of the ACS URL but will now be removed. You'll need to update the configuration of your SAML Identity Provider to remove the "/labkey" context path so that the ACS URL matches the one now shown in the upgraded LabKey Server's configuration panel.
Step 2: Add a New SAML Configuration to LabKey
- 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.
- Note that you can save an incomplete configuration, provided it is disabled.
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, an
Encryption Key must be set in the application.properties file. If a key is not set, attempting to go to the SAML configuration screen displays an error message, directing the administrator to fix the configuration.
Configure the Properties for SAML authentication
- Configuration Status: Click the Enabled slider to toggle whether this configuration is active.
- Configuration Details for IdP: See above.
- Required Settings:
- Name/Description: Provide a unique description of this provider.
- IdP Signing Certificate: Either drag and drop or click to upload a PEM format certificate from the Identity Provider (IdP) to verify the authenticity of the SAML response.
- IdP SSO URL: The Single Sign-On (SSO) URL provided by the Identity Provider (IdP) for user authentication to typically validate user credentials, authentication token, and session information.
- NameID Format: This is the NameIdformat specified in the SAML request. Options are Email Address (Default), Transient, Unspecified
- Optional Settings:
- User Access Settings: At least one option is required to enable users to access SAML authentication:
- Set as Default for Login: 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.
- Login Page Logo: Provide a logo image for the login page for users to click to log in with SAML. Learn more about logo fields here: Single Sign-On Logos.
- Page Header Logo: Provide a logo image for the header for users to click to log in with SAML. Learn more about logo fields here: Single Sign-On Logos.
- Click Finish in the popup to save. You can save a partial configuration if it is disabled. Any provided values must be valid, but not all values need to be provided until the configuration is enabled.
Optional Settings
Checking the box will expand to show additional fields:
- Encryption Certificate (Optional): Upload a PEM format Encryption Certificate for Encrypted Assertion. 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 PEM format 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.
- Issuer URL: URL issued by the Identity Provider (IdP) to uniquely identify the IdP during SAML assertions. Some IdP configurations require this, some do not. If required, it's probably the base URL for the LabKey Server instance.
- Validate XML Responses: We strongly recommend validating XML responses from the IdP. Uncheck this only if your network infrastructure blocks the server's access to http://w3.org.
- Force Authorization: If checked, require the user to login again via IdP, even if they are already logged in via an SSO provider.
- Associated Email Domain: Email domain that indicates which users are expected to authenticate using this configuration. For example, if set to 'labkey.org', all users who enter xxxxxx@labkey.org are presumed to authenticate using this configuration. This is often left blank, but if provided, LabKey will suggest this authentication method to users with the specified domain if they fail an authentication attempt using a different configuration. LabKey will also not create database logins when administrators add user accounts with this email domain.
Edit an Existing SAML Configuration
- 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.
Troubleshooting
Validation of XML Responses
To validate XML responses, the server needs to be able to access
http://w3.org. If your network blocks this access, or is significant latency, you may see errors. While we strongly recommend validating XML responses from the IdP, you will need to uncheck that option if your network infrastructure blocks the server's access.
Using SAML with Load Balancers
If you are using a Load Balancer (e.g. AWS Application Load Balancer, Nginx, Apache, etc), you may need to edit your server.xml file to configure the expected ports.
For instance, if the load balancer is configured to work on port 443, but in application.properties your server.port is set to use 8080, you'd need to update that setting to 443 so it matches your load balancer.
Using SAML with NGINX
If you are using NGINX and seeing an error similar to:
ERROR SamlManager 2024-09-17T10:59:39,407 http-nio-8080-exec-4 : Invalid response: The response was received at http://FULLURL instead of https://FULLURL
Check that your IdP is correctly configured to use https in URLs, also try setting your server to "Require SSL connections".
You will also need to make sure that your NGINX configuration is correctly using the scheme "https". As an example, you may already be setting redirectPort to 8443 to handle connections over HTTPS, and can see LabKey server logs showing $scheme as 'https', however there are actually two schemes involved. NGINX sets $scheme to 'https' because it's receiving the request over an HTTPS connection, but the LabKey side doesn't automatically inherit this scheme. Since NGINX terminates the SSL connection and forwards the request to Tomcat over HTTP, you need to explicitly configure Tomcat to treat the forwarded request as HTTPS.
Embedded Tomcat uses Spring Boot's properties to interpret forwarded headers, treating requests based on what the reverse proxy (NGINX in this case) provides. To ensure the correct scheme is passed through, add this to your application.properties file:
# Configure how Spring Boot handles forwarded headers
server.forward-headers-strategy=native
Service Provider Metadata
If your IdP requires Service Provider XML Metadata, you can generate it using a tool such as:
https://www.samltool.com/sp_metadata.phpLabKey Server supports only static Service Provider Metadata XML.
Neither metadata generation nor discovery are supported.
Configuration ID
Previous versions of LabKey used an configurationId parameter as part of the ACS URL. This prior configuration method will still work but is not covered in this documentation. You can either reconfigure authentication as described above or
see the previous documentation in the archives.
SAML Functionality Not Currently Supported
- Metadata generation - LabKey Server supports only static 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)
Related Topics
