Skip to main content
Hitachi Vantara Lumada and Pentaho Documentation

Single sign-on with SAML

Parent article

Security Assertion Markup Language (SAML) is an open standard for browser based Single-Sign-On (SSO). It offers passwordless logins using tokens.

Lumada Data Catalog implements its SAML integration using the open source OneLogin SAML Toolkit. As such, you may also refer to the OneLogin SAML Toolkit documentation for detailed descriptions of the settings.

While a full description of the SAML protocol is outside the scope of this document, here is the basic flow:

The protocol involves three parties:

  • Service Provider (SP)

    The Service Provider is the application that provides the service that the user is trying to access, in this case, it is the Data Catalog Application Server.

  • Identity Provider (IdP)

    The Identity Provider is the application which is responsible for verifying the user's identity via one or more factors (logging them in) and validating their access to the service provider application. Examples of Identity Providers are Microsoft Active Directory Federation Services (ADFS), Optimal IDM, PingFederate, One Login IdP, etc.

  • User

    This is the user's browser client. It is the intermediary through which messages are passed between the Service Provider and the Identity Provider via browser redirects.

The flow is as follows:

  1. https://wld-hostname:port/saml/login initiates the login process. The same can be started from the main login page by clicking the Sign In Using SAML button.
  2. This creates a SAML request and redirects the browser to the IdP login page. If the user is not already logged in at IdP, they are asked to login (username/password, MFA, etc.) and then upon successful login are redirected back to the SP at https://wld-hostname:port/saml/assert with a SamlResponse.
  3. The SAML response from IdP is validated by the SP and attributes are extracted - the NameID attribute becomes the username of the logged in user - and a session is created for the user and they are let in to the Data Catalog application.

Enabling SAML in Data Catalog

Enabling SAML in Data Catalog involves two steps:

  1. Configuring SAML settings in onelogin.saml.properties under $WLD_HOME/app-server/conf/.
  2. Updating authentication methods in configuration.JSON under $WLD_HOME/app-server/conf/.

Configuring SAML settings

All the SAML related settings are configured in a properties file located under $WLD_HOME/app-server/conf/ called onelogin.saml.properties. The most common settings that need to be configured therein are as follows:

SP-side properties
  • onelogin.saml2.sp.entityid = https://wld-hostname:port/saml/metadata
  • onelogin.saml2.sp.assertion_consumer_service.url = https://wld-hostname:port/saml/assert
  • onelogin.saml2.sp.single_logout_service.url = https://wld-hostname:port/saml/logout
IdP-side properties:

These should be available from the IdP configuration when you provision a new service provider.

  • onelogin.saml2.idp.entityid
  • onelogin.saml2.idp.single_sign_on_service.url
  • onelogin.saml2.idp.single_logout_service.url
  • onelogin.saml2.idp.x509cert

For a complete listing of settings and detailed descriptions, refer to the sample onelogin.saml.properties file below. You may also refer to the OneLogin SAML Toolkit documentation for detailed descriptions of the settings at https://github.com/onelogin/java-saml

Once all properties are configured, the Service Provider Metadata can be obtained at the URL: https://wld-hostname:port/saml/metadata .

Enabling SAML login in Data Catalog configuration

Perform the following steps to enable SAML login:

Procedure

  1. Enable the SAML login button on the login page, by setting the waterlinedata.web.enabled.auth.methods property in configuration.json under $WLD_HOME/app-server/conf as follows:

    ...
    "waterlinedata.web.enabled.auth.methods" : {
        "value" : [ "PASSWORD", "SAML" ],
        "type" : "STRING",
        "restartRequired" : true,
        "readOnly" : false,
        "description" : "User authentication methods that have been enabled",
        "label" : "User authentication methods that have been enabled",
        "category" : "SECURITY",
        "defaultValue" : [ "PASSWORD" ],
        "visible" : true
      }
  2. Restart the application server.

    Your login screen should get a SAML login option as follows:SAML login screen

Sample SAML properties configuration

The following code sample shows SAML properties configuration with documentation.
Sample onelogin.saml.properties:

#  If 'strict' is True, then the Java Toolkit will reject unsigned
#  or unencrypted messages if it expects them signed or encrypted
#  Also will reject the messages if not strictly follow the SAML
onelogin.saml2.strict =  true

# Enable debug mode (to print errors)
onelogin.saml2.debug =  true


#  Service Provider Data that we are deploying
#
#  Identifier of the SP entity  (must be a URI)
onelogin.saml2.sp.entityid = https://cdh:8082/saml/metadata

# Specifies info about where and how the <AuthnResponse> message MUST be
#  returned to the requester, in this case our SP.
# URL Location where the <Response> from the IdP will be returned
onelogin.saml2.sp.assertion_consumer_service.url = https://cdh:8082/saml/assert

# SAML protocol binding to be used when returning the <Response>
# message.  Onelogin Toolkit supports for this endpoint the
# HTTP-POST binding only
onelogin.saml2.sp.assertion_consumer_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

# Specifies info about where and how the <Logout Response> message MUST be
# returned to the requester, in this case our SP.
onelogin.saml2.sp.single_logout_service.url = https://cdh:8082/saml/logout

# SAML protocol binding to be used when returning the <LogoutResponse> or sending the <LogoutRequest>
# message.  Onelogin Toolkit supports for this endpoint the
# HTTP-Redirect binding only
onelogin.saml2.sp.single_logout_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

# Specifies constraints on the name identifier to be used to
# represent the requested subject.
# Take a look on lib/Saml2/Constants.php to see the NameIdFormat supported
onelogin.saml2.sp.nameidformat = urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

# Usually x509cert and privateKey of the SP are provided by files placed at
# the certs folder. But we can also provide them with the following parameters

onelogin.saml2.sp.x509cert =

# Requires Format PKCS#8   BEGIN PRIVATE KEY      
# If you have     PKCS#1   BEGIN RSA PRIVATE KEY convert it by openssl pkcs8 -topk8 -inform pem -nocrypt -in sp.rsa_key -outform pem -out sp.pem
# onelogin.saml2.sp.privatekey =

# Identity Provider Data that we want connect with our SP
#

# Identifier of the IdP entity  (must be a URI)
# onelogin.saml2.idp.entityid = https://app.onelogin.com/saml/metadata/710535

# SSO endpoint info of the IdP. (Authentication Request protocol)
# URL Target of the IdP where the SP will send the Authentication Request Message
# onelogin.saml2.idp.single_sign_on_service.url = https://wld-dev.onelogin.com/trust/saml2/http-post/sso/710535

# SAML protocol binding to be used when returning the <Response>
# message.  Onelogin Toolkit supports for this endpoint the
# HTTP-Redirect binding only
# onelogin.saml2.idp.single_sign_on_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect


# SLO endpoint info of the IdP.
# URL Location of the IdP where the SP will send the SLO Request
onelogin.saml2.idp.single_logout_service.url = https://wld-dev.onelogin.com/trust/saml2/http-redirect/slo/710535

# Optional SLO Response endpoint info of the IdP.
# URL Location of the IdP where the SP will send the SLO Response. If left blank, same URL as onelogin.saml2.idp.single_logout_service.url will be used.
# Some IdPs use a separate URL for sending a logout request and response, use this property to set the separate response URL
onelogin.saml2.idp.single_logout_service.response.url =

# SAML protocol binding to be used when returning the <Response>
# message.  Onelogin Toolkit supports for this endpoint the
# HTTP-Redirect binding only
onelogin.saml2.idp.single_logout_service.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

# Public x509 certificate of the IdP
onelogin.saml2.idp.x509cert = -----BEGIN CERTIFICATE-----nMIIELDCCAxSgAwIBAgIUHn9h8/bfGas4w5heKtbUwVOSC/0wDQYJKoZIhvcNAQEFBQAwXzELMAkGA1UEBhMCVVMxFzAVBgNVBAoMDldhdGVybGluZSBEYXRhMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAxIDAeBgNVBAMMF09uZUxvZ2luIEFjY291bnQgMTE1NDMzMB4XDTE3MTAwNDIxNTc1MloXDTIyMTAwNTIxNTc1MlowXzELMAkGA1UEBhMCVVMxFzAVBgNVBAoMDldhdGVybGluZSBEYXRhMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAxIDAeBgNVBAMMF09uZUxvZ2luIEFjY291bnQgMTE1NDMzMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyzPo71i48o1gSytRQMf6pxsyJxlXP580BLlX2BJSFKKGpv9UGQBeAUIOKbBC20uD7aK5DC0HNJ8WmghoLzoQpL0PC92Y+pvJPCXgCZos2sns0kgJGFcTRkXzXgcIgpdakKUL6HJfAfk6OvOZUkpC/7WDIze9F3PXXuWcKfE1u0/hQNnG8Z6YLmUEHjRPqNt8AgBm3mMJixKx/i4Llwy9mZ9MhJwQefb+bGMIryAtVggsXejNIAhFek6EuBcNXflfq5oTU7jmE6/Ocxq3vktNJO8OwP8Bu8MPbVd803sIzajfC1Xtgni9Ja0C+fJQcYDH3nqDsMlnEZ2NSyyg69t16wIDAQABo4HfMIHcMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLO5Z/yUeX2NM8t4iTT7kLvwvIPkMIGcBgNVHSMEgZQwgZGAFLO5Z/yUeX2NM8t4iTT7kLvwvIPkoWOkYTBfMQswCQYDVQQGEwJVUzEXMBUGA1UECgwOV2F0ZXJsaW5lIERhdGExFTATBgNVBAsMDE9uZUxvZ2luIElkUDEgMB4GA1UEAwwXT25lTG9naW4gQWNjb3VudCAxMTU0MzOCFB5/YfP23xmrOMOYXirW1MFTkgv9MA4GA1UdDwEB/wQEAwIHgDANBgkqhkiG9w0BAQUFAAOCAQEAHfzYAwvk+30uup3IhrjYzutnNjPkoqyRIa73Wr8i24mX/P9dWy30aU7A9KVSrae4L8GQBbfW+SLisiz/ecwKEUx11n047cHlyg1hHeyaptRsW78GDFwgaafBAbe4mNPHgUboWeQ1TjW5FiY9HjvM8AdeVhThOgoFQk3EpCiwDiNHtTJtUN2iU3vw0zmd0Iw4uxKiYN5Eyxz+9j/cUGXCO8MPTEG/6cpi/eqPmJLDpO2csgZeimXTwgmETcpNr95bJezYxXQjHxVSj013JkN0gT9pUwfYz4uurkuoJbpOKHOCacC+pDjx+wDMArSIkmsaa1gUn60Heq8c0cFKffJlxQ==n-----END CERTIFICATE-----

# Instead of use the whole x509cert you can use a fingerprint
# (openssl x509 -noout -fingerprint -in "idp.crt" to generate it,
# or add for example the -sha256 , -sha384 or -sha512 parameter)
#
# If a fingerprint is provided, then the certFingerprintAlgorithm is required in order to
# let the toolkit know which Algorithm was used. Possible values: sha1, sha256, sha384 or sha512
# 'sha1' is the default value.
# onelogin.saml2.idp.certfingerprint = 
# onelogin.saml2.idp.certfingerprint_algorithm = sha1


# Security settings
#

# Indicates that the nameID of the <samlp:logoutRequest> sent by this SP
# will be encrypted.
onelogin.saml2.security.nameid_encrypted = false

# Indicates whether the <samlp:AuthnRequest> messages sent by this SP
# will be signed.              [The Metadata of the SP will offer this info]
onelogin.saml2.security.authnrequest_signed = false

# Indicates whether the <samlp:logoutRequest> messages sent by this SP
# will be signed.
onelogin.saml2.security.logoutrequest_signed = false

# Indicates whether the <samlp:logoutResponse> messages sent by this SP
# will be signed.
onelogin.saml2.security.logoutresponse_signed = false

# Sign the Metadata
# Empty means no signature, or comma separate the keyFileName and the certFileName
onelogin.saml2.security.want_messages_signed = 

# Indicates a requirement for the <samlp:Response>, <samlp:LogoutRequest> and
# <samlp:LogoutResponse> elements received by this SP to be signed.
onelogin.saml2.security.want_assertions_signed = false

# Indicates a requirement for the Metadata of this SP to be signed.
# Right now supported null (in order to not sign) or true (sign using SP private key) 
onelogin.saml2.security.sign_metadata = 

# Indicates a requirement for the Assertions received by this SP to be encrypted
onelogin.saml2.security.want_assertions_encrypted = false

# Indicates a requirement for the NameID received by this SP to be encrypted
onelogin.saml2.security.want_nameid_encrypted = false

# Authentication context.
# Set Empty and no AuthContext will be sent in the AuthNRequest,
# Set comma separated values urn:oasis:names:tc:SAML:2.0:ac:classes:urn:oasis:names:tc:SAML:2.0:ac:classes:Password
onelogin.saml2.security.requested_authncontext = urn:oasis:names:tc:SAML:2.0:ac:classes:urn:oasis:names:tc:SAML:2.0:ac:classes:Password

# Allows the authn comparison parameter to be set, defaults to 'exact'
onelogin.saml2.security.onelogin.saml2.security.requested_authncontextcomparison = exact


# Indicates if the SP will validate all received xmls.
# (In order to validate the xml, 'strict' and 'wantXMLValidation' must be true).
onelogin.saml2.security.want_xml_validation = true

# Algorithm that the toolkit will use on signing process. Options:
#  'http://www.w3.org/2000/09/xmldsig#rsa-sha1'
#  'http://www.w3.org/2000/09/xmldsig#dsa-sha1'
#  'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
#  'http://www.w3.org/2001/04/xmldsig-more#rsa-sha384'
#  'http://www.w3.org/2001/04/xmldsig-more#rsa-sha512'
onelogin.saml2.security.signature_algorithm = http://www.w3.org/2000/09/xmldsig#rsa-sha1

# Organization
onelogin.saml2.organization.name = Lumada Data Catalog
onelogin.saml2.organization.displayname = LumadaData Catalog
onelogin.saml2.organization.url = https://www.waterlinedata.com
onelogin.saml2.organization.lang = 

# Contacts
onelogin.saml2.contacts.technical.given_name = Lumada Data Catalog Support
onelogin.saml2.contacts.technical.email_address = support@waterlinedata.com
onelogin.saml2.contacts.support.given_name = Data Catalog Support
onelogin.saml2.contacts.support.email_address = support@waterlinedata.com