Technical description

Meliora Testlab SAML 2.0 SSO guide

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.

  • Introduction

    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.

  • SAML SSO with hosted Testlab

    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.

  • Set up SAML SSO with on-premise Testlab

    Required steps to set up SAML-based SSO to your own local Testlab installation consist of:

    • Generating a key pair and creating a keystore to hold SAML cryptography keys
    • Setting up SAML properties to Testlab side (saml.properties)
    • Installing Testlab’s saml-serviceprovider-plugin (war) to your local application server
    • Setting up local metadata to saml-serviceprofider-plugin
    • Integrating Testlab’s saml-serviceprovider-plugin to your identity provider by
      • configuring trust to your IDP (importing local metadata to your IDP),
      • setting up claims in your IDP (what information about users is passed back to Testlab) and
      • configuring IDP (remote) metadata to saml-serviceprovider-plugin

    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.

    Install JCE extensions

    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.

    Please note: As a recommendation, Oracle’s JVM has been superseded with Azul Systems’ JDK. If you are using Azul’s JVM, you will find the Cryptography Extension Kit for it here.

    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.

    Generate a key pair and keystore for SAML

    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?
 [Unknown]: 
What is the name of your organization?
 [Unknown]: My Company Ltd
What is the name of your City or Locality?
 [Unknown]: 
What is the name of your State or Province?
 [Unknown]: 
What is the two-letter country code for this unit?
 [Unknown]: FI
Is CN=Testlab SAML SP, OU=Unknown, O=My Company Ltd, L=Unknown, ST=Unknown, C=FI correct?
 [no]: yes

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.

    Setting up SAML properties to Testlab

    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 
enabled.for=company

# disable saml-serviceprovider-plugin diagnostic and metadata administration
#  by setting this as true later
production=false
# password to access metadata administration in saml-serviceprovider-plugin
saml.admin.password=samladmin

### saml settings for testing
company.idp.identifier=

### keystore settings for saml-serviceprovider-plugin
# location of the keystore to store saml keys
saml.keystore=classpath:testlabsaml.jks
# password for the keystore
saml.keystore.password=<secure keystore password entered when creating testlabsaml.jks>
# alias of our service provider signing key
saml.key=testlabsamllocal
# password for our service provider signing key
saml.key.password=<secure keystore password entered when creating testlabsaml.jks>

### metadata files
saml.metadata.local=../samlmetadata/local
saml.metadata.remote=../samlmetadata/remote
    • enabled.for=company
      • Leave as it is
    • company.idp.identifier
      • Identifier for the identity provider used for authentication. Leave this blank for the time being – this is set up later to hold the identifier.
    • production
      • When set as false (or unset), saml-serviceprovider-plugin application provides verbose error logging to the browser and in addition, provides access to Metadata Administration views, if needed. This setting must be set as true when the plugin is set up correctly and taken in production.
    • saml.admin.password
      • Password for ‘admin’ user in saml-serviceprovider-plugin’s Metadata Administration view. Defaults to ‘samladmin’.
    •  saml.keystore
      • Points to the keystore used for SAML cryptography. Leave as it is if you created the keystore to Glassfish domain’s lib/classes directory.
    • saml.keystore.password
      • Set the same password here you entered when creating the keystore
    • saml.key
      • Leave as it is if you created the keystore as instructed. This can be changed if the alias of the key in the keystore is different for some reason.
    • saml.key.password
      • The password for the key in the keystore. If you created the keystore as instructed, this is the same password as with the keystore itself. If you entered a different password for the key, enter it here.
    • saml.metadata.local
      • A path to a directory which should hold the local metadata file. Leave as it is and it will point to Glassfish domain root (glassfish/domains/domain1/samlmetadata/local).
    • saml.metadata.remote
      • A path to a directory which should hold the remote metadata file (metadata of your IDP). Leave as it is and it will point to Glassfish domain root (glassfish/domains/domain1/samlmetadata/remote).

    Note: If you restart Payara 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.

    Install saml-serviceprovider-plugin

    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.

    1. Create metadata directories to hold SAML metadata descriptors 
      # cd glassfish/domains/domain1
# mkdir samlmetadata
# mkdir samlmetadata/local
# mkdir samlmetadata/remote
    2. Download the plugin
    3. Deploy it to Glassfish by running 
      # 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:

    • …/domain1/logs/saml-serviceprovider-plugin.log
      • Default logging output of the plugin component. Refer to this log file to inspect any possible errors or problems during installation.
    • …/domain1/logs/saml-audit.log
      •  Audit log of SSO events. This file will contain a log of messages passed between this service provider and your identity provider.
    Set up local metadata to saml-serviceprovider-plugin

    To set up local metadata do the following:

    1. With a browser, make a request to 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.
    2. Inspect and edit the generated metadata file as follows:
      – Remove element <ds:Signature xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”>…</ds:Signature> from the file if it exists.
      – The resulting file should look like

      <?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     ID="https___testlab_example_com_saml-serviceprovider-plugin_saml_metadata"
                     entityID="https://testlab.example.com/saml-serviceprovider-plugin/saml/metadata">
    <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true"
                        protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>...</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:KeyDescriptor use="encryption">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>...</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                Location="https://testlab.example.com/saml-serviceprovider-plugin/saml/SingleLogout"/>
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                                Location="https://testlab.example.com/saml-serviceprovider-plugin/saml/SingleLogout"/>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName</md:NameIDFormat>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                     Location="https://testlab.example.com/saml-serviceprovider-plugin/saml/SSO" 
                                     index="0" isDefault="true"/>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
                                     Location="https://testlab.example.com/saml-serviceprovider-plugin/saml/SSO" 
                                     index="1"/>
    </md:SPSSODescriptor>
</md:EntityDescriptor>

      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.

    3. Copy this XML file to your server as glassfish/domains/domain1/samlmetadata/local/company.xml

    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 login 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 in the 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.

  • Integrate with ADFS 3.0 IdP

    In this section, we’ll give you an example of 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.

     

    Configure trust to ADFS 3.0
    1. Transfer the XML file containing the local metadata (company.xml) to your ADFS server
    2. From Server Manager, choose Tools > AD FS Management
    3. From the left-hand side tree, select AD FS > Trust Relationships > Relaying Party Trusts and with right mouse click choose “Add Relaying Party Trust…”. A wizard to add a new trust opens up.
      • Click Start
      • Choose “Import data about the relaying party from a file” and choose the company.xml file as “Federation metadata file location”. Click Next >
      • Enter “Meliora Testlab” as a display name and click Next >
      • Choose “I do not want to configure multi-factor authentication settings for this relaying party trust at this time.” and click Next >
      • Choose “Permit all users to access this relaying party” and click Next >
      • Inspect the relaying party trust parsed from the meta data file and check that
        • Identifiers tab contains the identifier of your local service provider,
        • Encryption tab contains details about the key created earlier for SAML token signing,
        • The signature tab contains details about the signature of the key created,
        • Endpoints tab contains URLs pointing to your saml-serviceprovider-plugin and
        • The advanced tab has SHA-256 set as Secure hash algorithm.
      • Click Next > and click Close.

     

    Set up claims in ADFS 3.0

    To set up claims (= the information that is passed to saml-serviceprovider-plugin about users) in ADFS, do the following:

    1. From Server Manager, choose Tools > AD FS Management
    2. From the left-hand side tree, select AD FS > Trust Relationships > Relaying Party Trusts
    3. Right-click “Meliora Testlab” and choose “Edit Claim Rules…”. An Edit Claim Rules dialog opens up.
    4. On Issuance Transform Rules tab, click “Add Rule…” and
      • Select “Send LDAP Attributes as Claims” and click Next >
      • Enter
        • Claim rule name: Name ID
        • Attribute store: Active Directory
        • LDAP Attribute: SAM-Account-Name
        • Outgoing Claim Type: Name ID
      • Click FinishThis 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.
    5. On Issuance Transform Rules tab, click “Add Rule…” and
      • Select “Send LDAP Attributes as Claims” and click Next >
      • Enter
        • Claim rule name: Other attributes
        • Attribute store: Active Directory
        • Add two rows of mappings as
          • LDAP Attribute: E-Mail-Addresses
          • Outgoing Claim Type: E-Mail Address
        • and
          • LDAP Attribute: Display-Name
          • Outgoing Claim Type: Name
      • Click FinishThis will add an additional rule that will send the e-mail address and the full name of the user to Testlab.
    6. Click Apply and OK.

     

    Import key from ADFS to saml-serviceprovider-plugin

    For the service provider to trust the ADFS metadata, the token signing key must be copied from ADFS and imported to testlabsaml.jks keystore. To do this,

    1. From Server Manager, choose Tools > AD FS Management
    2. From the left-hand side tree, select AD FS > Certificates
    3. Right mouse click “Token-signing” certificate and choose View Certificate… A Certificate dialog opens up.
    4. On Details tab, click “Copy to File…”. A Certificate Export Wizard opens up.
      • Click Next
      • Select “DER encoded binary X.509 (.CER)” and click Next
      • Enter “adfs.cer” as the name for the export file and click Next
      • Click Finish
    5. Copy “adfs.cer” file to Testlab server
    6. Run the following to import the key to testlabsaml.jks keystore 
      # 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
Certificate fingerprints:
 MD5: ...:5A:8F
 SHA1: ...:53:FF
 SHA256: ...:E9:24
 Signature algorithm name: SHA256withRSA
 Version: 3
Trust this certificate? [no]: yes
Certificate was added to keystore
    Configure ADFS metadata and key to saml-serviceprovider-plugin

    To set up ADFS as an identity provider to Testlab side, do the following:

    1. With your browser, download the metadata from ADFS fromhttps://<your ADFS server>/FederationMetadata/2007-06/FederationMetadata.xml
    2. Copy this XML file to your Testlab server as glassfish/domains/domain1/samlmetadata/remote/company.xml
    3. Restart Glassfish and inspect saml-serviceprovider-plugin.log file for 
      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.

     

    Configure saml.properties in Testlab

    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.

    1. Edit the saml.properties file found in domain1/lib/classes directory and set 
      ...
company.idp.identifier=http://<your adfs server>/adfs/services/trust
...
    2. After the modification, restart your Glassfish server.

     

    Test the SSO login

    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.

    • If everything is set up correctly, you should get redirected to your ADFS server for authentication.
    • If credentials are entered correctly, ADFS redirects you back to /saml-serviceprovider-plugin which signs a token that can be used to access Testlab.
    • Your browser should be redirected back to /testlab and the normal login process of Testlab commences.
    • saml-audit.log file should be written with an audit trail for SAML messages exchanged between saml-serviceprovider-plugin and your ADFS server.
    • If any problems occur, please consult the saml-serviceprovider-plugin.log and Testlab’s testlab.log for any errors.
    • Please contact Meliora’s support if you encounter any errors or problems you cannot get around with.

     

    Secure the plugin for production use

    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:

    1. Edit the saml.properties file found in domain1/lib/classes directory and set 
      ...
production=true
...
    2. After the modification, restart your Glassfish server.

  • Upgrading the plugin

    The plugin may require updating from time to time. Meliora will deliver updated versions of the plugin to Customers when required.

    To update the provided plugin, please deploy it to your server by running

    # 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.
# ./asadmin restart-domain domain1
Successfully restarted the domain
Command restart-domain executed successfully.

  • Technical details and supported claims

    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/nameidentifier User ID Yes
    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.

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