Page tree
Skip to end of metadata
Go to start of metadata

This article describes how to enable two-factor authentication to the 3.9 - Nexus PRIME clients 3.9 - PRIME Explorer and 3.9 - PRIME User Self-Service Portal.

This is solved by setting up a SAML 2.0 federation to Nexus Hybrid Access Gateway, where Hybrid Access Gateway acts as an identity provider and PRIME as a service provider. 


Expand/Collapse All

Prerequisites

 Prerequisites

The following systems must be set up:

The following certificates must be created. See Create certificates for more information:
  • SSL server certificate for Hybrid Access Gateway

  • SSL server certificate for PRIME 

  • SAML certificate for Hybrid Access Gateway. The following file names are used in the examples below:

    • Keystorehag.saml.p12 

    • Certificate: hag.saml.pem 

    • Private Key: hag.saml.key.pem 

  • SAML certificate for PRIME. The following file names are used in the examples below: 

    • KeystoresamlKeystore.jks 

    • Certificate: prime.saml.pem 

Create certificates

To have a secure communication between Hybrid Access Gateway and PRIME server certificates needs to be provided by each server. 

 Only for demo use cases: Create SSL server certificate for Hybrid Access Gateway

To be able to use authentication with SAML, Hybrid Access Gateway needs an SSL server certificate. For demo use cases it’s sufficient to create a self-signed certificate including private keys. Skip these steps if a real server certificate exists.

  1. Use the java keytool command to create a self-signed certificate including private keys:

    Example: java keytool command
    keytool -genkey -keyalg RSA -alias selfsigned -keystore hag.local.jks -storepass <password> -validity 1080 -keysize 2048
  2. To use the server certificate with Hybrid Access Gateway, a key and certificate are required. Use the created jks container to transform to p12:

    Example: Transform to P12
    keytool -importkeystore -srckeystore hag.local.jks -destkeystore hag.local.p12 -deststoretype PKCS12 -srcalias selfsigned -deststorepass <password> -destkeypass <password>
  3. Use the p12 to extract the certificate:

    Example: Extract certificate
    openssl pkcs12 -in hag.local.p12 -nokeys -out hag.local.pem


  4. Use the p12 to extract the key:

    Example: Extract key
    openssl pkcs12 -in hag.local.p12 -nodes -nocerts -out key.pem


 Only for demo use cases: Create SSL server certificate for PRIME

Since SAML communicates in two directions, a server certificate of PRIME is also required. Skip these steps if a real server certificate exists. 

  1. Use the java keytool command to create a java keystore  (prime.local.jks) containing a key-pair with a corresponding self-signed certificate:

    Example: Create self-signed certificate for PRIME
    keytool -genkey -keyalg RSA -alias selfsigned -keystore prime.local.jks -storepass <password> -validity 1080 -keysize 2048 
 Create SAML certificate for Hybrid Access Gateway

Hybrid Access Gateway requires a key-pair as well as a certificate for the SAML communication.

  1. Use the java keytool command to create a self-signed certificate including private keys:

    Example: java keytool command
    keytool -genkey -keyalg RSA -alias selfsigned -keystore hag.saml.jks -storepass <password> -validity 1080 -keysize 2048 
  2. To use the SAML certificate with Hybrid Access Gateway, a key and certificate are required. Use the created jks container to transform to p12:

    Example: Transform to P12
    keytool -importkeystore -srckeystore hag.saml.jks -destkeystore hag.saml.p12 -deststoretype PKCS12 -srcalias selfsigned -deststorepass <password> -destkeypass <password> 
  3. Use the p12 to extract the certificate:

    Example: Extract certificate
    openssl pkcs12 -in hag.saml.p12 -nokeys -out hag.saml.pem 


  4. Use the p12 to extract the key:

    Example: Extract key
    openssl pkcs12 -in hag.saml.p12 -nodes -nocerts -out hag.saml.key.pem 
 Create SAML certificate for PRIME

Nexus PRIME needs to have its own private key. The private key of PRIME must be imported into the following file: /prime_explorer/WEB-INF/classes/samlKeystore.jks.

To create a SAML certificate for PRIME:

  1. For testing purposes, if no official certificate exists, you can generate a keystore with a new key within:

    1. Use the java keytool command to create a keystore:

      Example: java keytool command
      keytool -genkeypair -alias sp -keypass <password> -keystore samlKeystore.jks 

      In this example, sp is used as alias for keys and certificate of the PRIME SAML certificate.

    2. Transform the proprietary jks keystore to a .p12 file:

      Example: Extract certificate
      keytool -importkeystore -srckeystore samlKeystore.jks -destkeystore samlKeystore.p12 -deststoretype PKCS12 -srcalias sp 
      -deststorepass <password> -destkeypass <password> 
  2. If the private key and certificate were received over a public key infrastructure, in this example samlKeystore.p12, import the container into the file samlKeystore.jks: 

    Example: Transform to P12
    keytool -importkeystore -srckeystore samlKeystore.p12 -srcstoretype PKCS12 -srcstorepass <p12_password> -alias <alias> -destkeystore samlKeystore.jks -destalias <alias> -destkeypass <jks_password> 
  3. Extract the public key of PRIME SAML from the .p12 file, so that the key can be imported into Hybrid Access Gateway: 

    Example: Extract key
    openssl pkcs12 -in samlKeystore.p12 -nokeys -out prime.saml.pem 

Set up PRIME as service provider

 Set up SAML single sign-on in PRIME Explorer

Set up authentication profile

  1. To integrate PRIME with SAML SSO, the SAML authentication profile must be used. This is configured in PRIME Designer under the Authentication Profiles section, see 3.9 - Set up authentication profile. As profile type select SAML SSO Core Object
  2. Select the Core Template that is used for mapping after a successful authentication. For example Employee.
  3. Define the User name field: The information received from the identity provider (IDP) will be mapped to this field from the Core Object. So if the identity provider is set to send the user email address as SAML token, then the User name field must be selected as Email.

Create meta-data file

Since Nexus PRIME will act as service provider, you need to create the corresponding meta-data file for it. You find templates for this within the folder (located in the application's classpath \prime_explorer\WEB-INF\classes\saml_config\). Once the meta-data file for PRIME Explorer is created, it must be shared with the identity provider, Nexus Hybrid Access Gateway in this case.

The meta-data template contains the following values that needs to be adapted:

Meta-data template
<md:EntityDescriptor ID="dummySP" entityID="dummySP" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
…
<md:KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>dummy certificate</ds:X509Certificate>
…
<md:KeyDescriptor use="encryption"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>dummy certificate</ds:X509Certificate>
…
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://0.0.0.0/prime_explorer/saml/SingleLogout"/>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://0.0.0.0/prime_explorer/saml/SingleLogout"/>
…
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://0.0.0.0/prime_explorer/saml/SSO" index="0" isDefault="true"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="http://0.0.0.0/prime_explorer/saml/SSO" index="1"/></md:SPSSODescriptor>
  1. Duplicate the file dummy_sp.xml  for Nexus PRIME Explorer. Choose the file name accordingly. 
  2. Do the following changes to the PRIME Explorer meta-data:
    1. Change the placeholder dummySP of attribute ID and entityID to a more meaningful name, such as https://prime.local/sp.
    2. Replace the placeholder dummy certificate with the base64 encoded SAML certificate (prime.saml.pem in this case).
    3. Replace the IP address placeholders 0.0.0.0 with the actual DNS name. Choose https instead of http for the URLs.
    4. Change the placeholder prime_explorer to the productive application name. In our example it doesn't need to be changed.

Upload meta-data file to Authentication profile

After the meta-data file has been created it must be uploaded to the Authentication Profile in PRIME Designer. 

  1. Open the SAML SSO Authentication Profile that was created earlier.
  2. Open tab SAML Configuration.
  3. In section SAML Configuration Files upload the meta-data file for PRIME Explorer and assign Type METADATA.

    The metadata file for the SAML identity provider will be uploaded in a later step.

Configure meta-data file

The uploaded meta-data file must be configured with File Properties.

  1. Click on the SAML Configuration Files entry.
  2. Click + in the File Properties section for each of the below mentioned properties.
  3. For PRIME Explorer, set up the following properties:

    KeyValueDescription
    localtrueTrue for metadata of a local service provider. False for remote identity providers.
    securityProfilemetaiopSecurity profile for verification of message signatures.
    sslSecurityProfilepkixSecurity profile for verification of SSL/TLS endpoint trust.
    sslHostnameVerificationdefaultVerification of hostnames for HTTPS calls (e.g. in Artifact resolution). Allowed values are default, defaultAndLocalhost, strict and allowAll. Value allowAll effectively disables hostname verification. All values are case-insensitive.
    signMetadatafalseWhen true generated metadata will be signed using XML Signature using certificate with alias of signingKey.
    requireArtifactResolveSignedfalseEnables signing of artifact resolution requests sent to the remote identity providers.
    requireLogoutRequestSignedfalseFor local entities enables requirement of signed logout requests. For remote entities enables signing of requests sent to the IDP.
    requireLogoutResponseSignedfalseFor local entities enables requirement of signed logout responses. For remote entities enables signing of responses sent to the IDP.
    signingKeyis the key that should be used for signing and it must be available in the keystore, e.g sp as in our exampleFor local entities alias of private key used to create signatures. The default private key is used when no value is provided.
    encryptionKeyis the key that should be used for SP-IDP communication and it must be available in the keystore, e.g sp as in our exampleFor local entities alias of private key used to encrypt data. The default private key is used when no value is provided.

Upload keystore file

  1. Upload the keystore file (a jks file, samlKeystore.jks in our example) that contains the keys that will be used in the communication process between the service provider and the identity provider.
    1. Select Type as KEYSTORE. This file contains the private keys while the public keys are written in the service provider metadata file.
  2. The alias(es) of the key(s) must be configured as signingKey and encryptionKey, mentioned in the table above.

  3. Add the following File Properties to the keystore:

    KeyValueDescription
    defaultKeyspThe default key that is contained in the keystore
    storePass<password>The password for the keystore. Use Type PASSWORD.
    passwords{sp,<password>}A pair of key/passwords. It must look like: {certKey,password} or multiple values like {{certKey1, passwd1}, {certKey2, passwd2}}
  4. Set up a start command to PRIME Explorer including the tenant id. For more information, see 3.9 - Install PRIME.

Set up Hybrid Access Gateway as identity provider

 Install Hybrid Access Gateway server certificate

To have a secure communication between Hybrid Access Gateway and PRIME, server certificates must be provided by each server. 

  1. Log in to Hybrid Access Gateway administration interface.
  2. Go to Manage System > Certificates.
  3. In Server Certificates, click Add Server Certificate… 
  4. Enter a Display Name and browse for the files, to define Certificate and Key:

    Example: Add server certificate

    Display Name: hag.local

    Certificate: hag.local.pem

    Key: key.pem

  5. Click Next > to finish the wizard.
 Import Hybrid Access Gateway SAML certificate

Private keys are used to digitally sign SAML messages and encrypt their content. Both parties need their own key-pair that could be created in self-signed mode (for testing purpose) or received from a public key infrastructure (for productive systems). 

To enable Hybrid Access Gateway to use the SAML certificate for signing:

  1. Log in to Hybrid Access Gateway administration interface.
  2. Go to Manage System > Certificates.
  3. In Server Certificates, click Add Server Certificate… 
  4. Enter a Display Name and browse for the files, to define Certificate and Key:

    Example: Add SAML certificate

    Display Name: SAML IdP Signing

    Certificate: hag.saml.pem

    Key: hag.saml.key.pem

    The Hybrid Access Gateway SAML certificate must be trusted by the Java installation that runs PRIME to have a secure communication between them.

    To allow SSL communication between PRIME Explorer and PRIME USSP, the SSL certificate needs to be trusted as well by the Java installation. The SSL certificate can be exported from the Java Key Store with the following command:

    Example: java keytool command
    keytool -export -keystore prime.local.jks -alias selfsigned -file prime.local.cer


  5. Click Next > to finish the wizard.
 Optional: Create DNS name for Hybrid Access Gateway access point

If you want to create a DNS name for the Hybrid Access Gateway access point, do the following:

  1. Log in to Hybrid Access Gateway administration interface.
  2. Go to Manage Resource Access > Global Resource Settings.
  3. Click on the tab DNS Name Pool.
  4. Add a new DNS name for the access point. Give the DNS name, for example idp.hag.local, and select the corresponding Hybrid Access Gateway server certificate, for example hag.local.pem.
  5. Click Add and then Save 
 Create SAML Federation

To add service provider:

  1. Go to Manage Resource Access > SAML Federation.
  2. Click Add SAML Federation....
  3. Enter a Display Name, for example PRIME.
  4. Check Acting as Identity Provider.
  5. Uncheck Import metadata automatically.
  6. Go to the Export tab.
  7. Give a unique Entity ID: for example https://hag.local/idp.
  8. Select the Signing Certificate, for example SAML IdP Signing.
  9. Go to the Role Identity Provider tab and click Add service provider...
  10. Verify that SAML 2.0 is checked.
  11. Upload SAML 2.0 metadata, click Choose file and select the file (for example prime_explorer_saml_metadata.xml) provided by PRIME. Click Next.
  12. Confirm the message about the signer certificate by clicking Yes.
  13. Click Finish Wizard.
  14. Click on the created service provider, to open it.
    The Display Name and Entity ID is now updated according to the metadata file.

    Entity ID must be unique within the federation, for example prime.saml.sso. 

    Service Provider URL is where the IdP will redirect the user after successful authentication, so this must be an exact match with the SP domain, in this case https://<prime_url>/prime_explorer/saml/SSO 

    Example: https://prime.local/prime_explorer/saml/SSO  

    <prime_url> must be the same as the url that was called initially. To be sure that the SAML request and response belong together, the communication must go to the same url and protocol (http or https), and both IdP and SP must be synchronized in terms of time.

    To set up NTP in HAG, see Deploy Hybrid Access Gateway and do initial setup.

     

  15. Disable Require signed authentication request 

  16. Go to the Assertion Settings tab.

  17. In Subject > Select source of subject: select E-mail. This is the unique identifier PRIME uses in standard cases, and will be used when Hybrid Access Gateway sends a SAML ticket to PRIME.

  18. Go to the tab Manage Access Rules.

  19. Select any suitable access rule or leave it as Any Authentication 

  20. Click Finish Wizard and then Add. 

  21. Repeat the same steps to add the PRIME USSP as an additional service provider.  

 Download SAML metadata

After the service provider was configured successfully in Hybrid Access Gateway, download the SAML metadata:

  1. Go to Manage Resource Access > SAML Federation.
  2. Click on the created service provider, to open it.
  3. Go to the tab Export.
  4. Click Download metadata.
  5. Rename the downloaded file to saml_idp_metadata.xml to match PRIME’s name convention, and store it in \prime_explorer\WEB-INF\classes\saml_config\ (replace the preconfigured file).