This document is a guide for setting up a SAML 2.0 based single-sign for your on-premises Meliora Testlab installation.
If you are using Meliora Testlab hosted, please consult this documentation.
SAML 2.0 (Security Assertion Markup Language) is a version of the SAML standard for exchanging authentication and authorization data between security domains. Meliora Testlab implements the Web Browser SSO Profile of the SAML standard which makes it possible to federate identity from your own user directory to Testlab in a single sign-on fashion. For example, if your organization has Active Directory hosting all your users set up with SSO federation services (ADFS), you can automatically log on your identified users to Testlab without needing to enter credentials on every login.
If you are using the hosted Meliora Testlab Enterprise from the cloud, please refer to the documentation here. The process itself usually consists of exchanging some metadata XML files and configuration (depending on used IDP vendor) to set up trust between the systems.
Required steps to set up SAML-based SSO to your own local Testlab installation consist of:
Please see detailed steps on how to do this below. As an example, we include instructions on how the trust is set up with Microsoft’s Active Directory and Federation Services 3.0 (ADFS 3.0).
Please note that SAML protocol dictates that all messages must be passed over HTTPS. If you happen to be running your Testlab on HTTP, SAML-based SSO won’t work.
If your JDK on the server is not installed with Unlimited Strength Cryptography Extensions, please install them. Go to Oracle’s download page and download “Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files” that match your JDK version.
If your JDK is not installed with these extensions, SAML login might fail with
java.security.InvalidKeyException: Illegal key size
error found in saml-serviceprovider-plugin.log.
As the messages passed are security signed and encrypted, a private key is needed for your SAML service provider. You can generate a new key pair with Java’s keytool by executing the following commands:
# cd glassfish/domains/domain1/lib/classes
# keytool -genkeypair -alias testlabsamllocal -keyalg RSA -keysize 2048 -validity 7300 -keystore testlabsaml.jks
Enter keystore password: <enter a secure keystore password>
Re-enter new password: <re-enter the password entered above>
What is your first and last name?
[Unknown]: Testlab SAML SP
What is the name of your organizational unit?
What is the name of your organization?
[Unknown]: My Company Ltd
What is the name of your City or Locality?
What is the name of your State or Province?
What is the two-letter country code for this unit?
Is CN=Testlab SAML SP, OU=Unknown, O=My Company Ltd, L=Unknown, ST=Unknown, C=FI correct?
Enter key password for <testlabsamllocal>
(RETURN if same as keystore password): <press enter>
This generates a new keystore file (testlabsaml.jks) to the lib/classes directory of your Glassfish installation which includes the keys used for token signing. The validity for the keys is 20 years and the key and the keystore is protected by the password you entered above. Please note the password – it is needed in the next step.
Testlab application itself needs the information that the SAML-based SSO is enabled. This is set up by creating a saml.properties file to the lib/classes directory of your Glassfish domain. Create a saml.properties file as follows:
### a base configuration file for saml 2.0 authentication
# enable SAML SSO for this installation
# disable saml-serviceprovider-plugin diagnostic and metadata administration
# by setting this as true later
# password to access metadata administration in saml-serviceprovider-plugin
### saml settings for testing
### keystore settings for saml-serviceprovider-plugin
# location of the keystore to store saml keys
# password for the keystore
saml.keystore.password=<secure keystore password entered when creating testlabsaml.jks>
# alias of our service provider signing key
# password for our service provider signing key
saml.key.password=<secure keystore password entered when creating testlabsaml.jks>
### metadata files
Note: If you restart Glassfish now and this saml.properties file is present, the SAML SSO will kick in and you won’t be able to log in to Testlab. You can disable SAML-based SSO by removing or renaming saml.properties file if you need to do so.
Saml-serviceprovider-plugin is an application component which handles all the secure SAML messaging between Testlab and your identity provider. It is packaged as a WAR file and needs to be deployed to the Glassfish application server running Testlab.
# cd glassfish/domains/domain1
# mkdir samlmetadata
# mkdir samlmetadata/local
# mkdir samlmetadata/remote
# cd glassfish/bin
# ./asadmin deploy --force /tmp/saml-serviceprovider-plugin.war
Enter admin user name> admin
Enter admin password for user "admin"> <admin password>
Application deployed with name saml-serviceprovider-plugin.
Command deploy executed successfully.
Note: Do not access the plugin application from /saml-serviceprovider-plugin with your browser yet. This is done when generating the local metadata in next step.
The component must be installed to the same Glassfish where Testlab application itself is deployed to. The plugin depends on the presence of Testlab’s configuration files and the saml.properties file created earlier. It will initialize itself from these files and deploy itself to the /saml-serviceprovider-plugin context.
The plugin writes it’s log output to two different files:
To set up local metadata do the following:
https://<public name of your Testlab server>/saml-serviceprovider-plugin/saml/metadata
This will generate a XML file with default local meta data for you.
<?xml version="1.0" encoding="UTF-8"?>
<md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true"
Make sure the file does not contain the <ds:Signature …> element and the Location addresses in the endpoints declared have the correct URLs to match your server environment.
Note: If you are using the recommended Nginx reverse proxy setup, you must make sure you have the location/proxy_pass rule for the saml-serviceprovider-plugin in place. Refer to the “Create site configuration” section in here.
When you make the first request to …/saml/metadata, the plugin will generate the local metadata for you with the server address (and the port if any) sent with the request. It is imperative that this request is made with a correct hostname as the IDP will use this information when communicating with the plugin (via your browser with redirects).
For any reverse proxy configurations, care must be taken to always generate the local metadata with correct URL addresses. The URL the metadata is generated with must be the external URL the user’s use to access Testlab. The identity provider never communicates directly with the saml-serviceprovider-plugin, but it uses browser redirects to pass information from the system to another. Because of this, the addresses must be accessible from the browsers the end users will use when executing the logon process.
saml-serviceprovider-plugin.log file can be inspected to debug this process:
2016-11-23 05:53:44 INFO MetadataGeneratorFilter No default metadata configured, generating with default values, please pre-configure metadata for production use
If this metadata needs to be regenerated, please restart Glassfish and try again. The generated metadata is stored to server’s memory and will be wiped in the restart. When you place this metadata file to …/samlmetadata/local/company.xml, it fixes the local metadata for production use.
The SSO infrastructure is now set up and you can proceed to integrate the plugin with your IDP. As an example, please read on how to integrate the SSO process to Active Directory Federation Services 3.0.
In this section, we’ll give you an example how to integrate the saml-serviceprovider-plugin based service provider with Microsoft’s Active Directory via Federation Services 3.0. Proceeding with this section, it is assumed that the ADFS 3.0 is installed and the saml-serviceplugin-plugin is set up according to the instructions in this document.
All instructions are against a Microsoft Windows Server 2012 R2 with ADFS 3.0 installed.
To set up claims (= the information that is passed to saml-serviceprovider-plugin about users) in ADFS, do the following:
This will add a rule that sends the name of your account as the identifying user ID to Testlab when authenticating. If this is not what you want and you would, for example, want to send the E-mail address of the user as the user ID, choose “E-Mail-Addresses” as LDAP Attribute instead of “SAM-Account-Name”. In this example, we assume that the account names in AD will be the ones mapped as user IDs in your Testlab.
This will add an additional rule that will send the e-mail address and the full name of the user to Testlab.
For the service provider to trust the ADFS meta data, the token signing key must be copied from ADFS and imported to testlabsaml.jks keystore. To do this,
# cd glassfish/domains/domain1/lib/classes
# keytool -importcert -file /tmp/adfs.cer -keystore ./testlabsaml.jks -alias "hostname.of.your.idp.server"
Enter keystore password: <enter your keystore password>
Owner: CN=ADFS Signing - ...
Issuer: CN=ADFS Signing - ...
Serial number: ...70e8
Valid from: Mon Nov 07 02:39:04 CST 2016 until: Tue Nov 07 02:39:04 CST 2017
Signature algorithm name: SHA256withRSA
Trust this certificate? [no]: yes
Certificate was added to keystore
To set up ADFS as an identity provider to Testlab side, do the following:
https://<your ADFS server>/FederationMetadata/2007-06/FederationMetadata.xml
2016-11-23 06:57:30 DEBUG AliasLoadingCachingMetadataManager refreshAvailableProviders: Initializing company from ../samlmetadata/local/company.xml - ../samlmetadata/remote/company.xml
2016-11-23 06:57:30 DEBUG AliasLoadingCachingMetadataManager refreshAvailableProviders: Initialized alias company with local settings: ...
2016-11-23 06:57:39 INFO LoginSuccessServlet Initialized.
Testlab must be told what IdP to use for SAML SSO via the plugin. The easiest way to find out the entityID of your ADFS server is to peek at FederationMetadata.xml and at the beginning of the file:
<EntityDescriptor ID="...ffdd" entityID="http://<your adfs server>/adfs/services/trust" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
The identifier is found in the “entityID” attribute of the root tag in this file.
company.idp.identifier=http://<your adfs server>/adfs/services/trust
Testlab is now integrated with SAML SSO via the saml-serviceprovider-plugin. Feel free to test your installation by accessing Testlab (/testlab) with your browser.
When the saml-serviceprovider-plugin is not in production mode it allows access to debugging and error information via your browser. In addition, Metadata Administration views are accessible for ‘admin’ user.
To secure the plugin to production use, these features must be disabled by:
The implementation conforms to the Web Browser SSO Profile of SAML 2.0 standard. We advocate the use of SHA-256 as the hashing algorithm.
The following claims should be mapped from the IdP to be sent for the integration to work:
|Claim type||Testlab attribute||Mandatory|
|http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress||E-mail address of the user||No|
|http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name||Full name of the user||No|
The NameID is always used to identify the user in Testlab. It must match the ID of the user in Testlab.
E-mail address and the full name of the user are only used when the user logs on to Testlab for the first time. When this happens the user is presented with an option to register a new user account in your Testlab. The e-mail address and the full name are pre-filled from the federated identity.