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

This article describes how to enable two-factor authentication to the 3.8 - Nexus PRIME clients 3.8 - PRIME Explorer and 3.8 - 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

To set up PRIME Explorer with SAML single sign-on:

  1. Since the login page is bypassed by the SAML SSO login, there will be no place to choose tenant or language. Therefore, add the parameters tenantId and language in the application URL:

    Example: tenantId and language
    http://localhost:8080/prime_explorer/jsp.mainframe.risc?ccstyle=act3_risc&ccconfirmexit=true&tenantId=tenantId>&language=<language>

    where <tenantId> is replaced by for example 1, 2, or 3 and <language> is replaced by en, de, sv, fr, and so on.

  2. This step is optional. Since PRIME 3.7, the principal information can be extracted from the SAML Attribute Statements section by setting up a bean in custom-beans.xml as following: 

    Example: Set up samlUserDetailsService
    <bean id="samlUserDetailsService" class="de.vps.act.frontend.workplace.login.SimpleSAMLUserDetailsService"> 
        <property name="principalAttributeName" value="Certificate.Subject.SerialNumber"/> 
    </bean> 


    where the Certificate.Subject.SerialNumber is defined as follows in the SAML assertion response file:

    Example: Certificate.Subject.SerialNumber
    <saml:Assertion ...> 
        ... 
        <saml:AttributeStatement> 
            ... 
            <saml:Attribute 
                Name="Certificate.Subject.SerialNumber" 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> 
                <saml:AttributeValue 
                    xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:type="xs:string">information to be extracted
                </saml:AttributeValue> 
            </saml:Attribute>     
            ... 
        </saml:AttributeStatement> 
        ... 
    </saml:Assertion> 
 Set up SAML single sign-on in PRIME User Self-Service Portal

To set up PRIME USSP with SAML single sign-on:

  1. Set pre-authentication (pre-auth-login) in the file /ussp/WEB-INF/config.xml:

    Example: pre-auth-login
    <service name="pre-auth-login"> 
        <option name="callback-context" value="webseal" /> 
        <option name="rest-server-pre-auth-login-context" value="login/saml" /> 
        <option name="callback-protocol" value="http" /> 
        <option name="callback-port" value="8080" /> 
        <header-parameter-transforms> 
            <transform from="SAMLToken" to="SAMLToken" /> 
        </header-parameter-transforms> 
    </service> 

    where value="login/saml". callback-protocol and callback-port must be set if SSL is used. If not set, the current protocol and port, that were used to access the USSP, will be used. 

    For PRIME User Self-Service Portal to work with SAML SSO, PRIME Explorer must also be enabled for SAML SSO. 

  2. Internally, PRIME USSP talks to PRIME Explorer over the web as well. To secure this connection, the rest-service in the file /ussp/WEB-INF/config.xml needs to be changed from localhost to the actual DNS name:

    Example: rest-service
    <service name="rest-service">
     <option name="explorer-url" value="https://prime.local/prime_explorer" />
     <option name="alive-relative-url" value="alive" />
     <option name="log-field-values" value="off"/>
     <option name="tenant-id" value="1" />
     <option name="instance-id" value="ussp-default-instance"/>
    </service>
 Install PRIME server certificate

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

To install the PRIME server certificate:

  1. Copy the jks keystore, either the existing one or the manually created prime.local.jks (see section Create SSL server certificate for PRIME), to Tomcat's folder ${catalina.home}/conf/.
  2. Open server.xml for editing.
  3. In Connector, set keystoreFile to prime.local.jks with the Tomcat file path and set keystoreType to JKS. In this example, the port is set to default SSL port 443:

    Example: server.xml
    <Connector 
            port="443" 
            protocol="HTTP/1.1" 
            SSLEnabled="true" 
            maxPostSize="-1" 
            scheme="https" 
            secure="true" 
            sslProtocol="TLS" 
            clientAuth="false" 
            keystoreFile="${catalina.home}/conf/prime.local.jks" 
            keystorePass="<password>" 
            keystoreType="JKS" 
    /> 
 Import PRIME 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 import the PRIME SAML certificate:

  1. If the keystore samlKeystore.jks was created manually (see Create PRIME SAML Certificate above), replace the existing keystore in the folder prime_explorer\WEB-INF\classes with the manually created file. Alternatively, the default keystore could be used. If the default keystore file is used, remember to change the password.
  2. Open the file \prime_explorer\WEB-INF\classes\spring\saml-meta-beans.xml for editing.
  3. Go to the section <!-- Central storage of cryptographic keys --> where the keystore samlKeystore.jks is configured. Edit the values to match the configuration chosen in the creation of the certificate, for example password:

    Example: saml-meta-beans.xml
    <!-- Central storage of cryptographic keys --> 
    <bean id="keyManager" class="org.springframework.security.saml.key.JKSKeyManager"> 
        <!-- Used keystore file --> 
        <constructor-arg value="classpath:samlKeystore.jks"/> 
        <!-- Keystore password --> 
        <constructor-arg type="java.lang.String" value="password"/> 
        <!-- Map with passwords for private keys with alias-password value pairs --> 
        <constructor-arg> 
            <map> 
                <entry key="sp" value="password"/> 
            </map> 
        </constructor-arg> 
        <!--  Alias of the default certificate --> 
        <constructor-arg type="java.lang.String" value="sp"/> 
    </bean> 
  4. Go to the section <!-- Prime Explorer file metadata -->. In signingKey and encryptionKey, enter the alias of the service provider key, as imported into samlKeystore.jks:

    Example: saml-meta-beans.xml - PRIME Explorer metadata
    <!-- Prime Explorer file metadata -->
    <bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
        ...
        <constructor-arg>
            <bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
                <property name="local" value="true"/>
                <property name="securityProfile" value="metaiop"/>
                <property name="sslSecurityProfile" value="pkix"/>
                <property name="sslHostnameVerification" value="default"/>
                <property name="signMetadata" value="false"/>
                <property name="signingKey" value="sp"/>
                <property name="encryptionKey" value="sp"/>
                <property name="requireArtifactResolveSigned" value="false"/>
                <property name="requireLogoutRequestSigned" value="false"/>
                <property name="requireLogoutResponseSigned" value="false"/>
            </bean>
        </constructor-arg>
    </bean>
  5. Go to the section <!-- USSP file metadata -->. In signingKey and encryptionKey, enter the alias of the service provider key, as imported into samlKeystore.jks. See example above.
  6. To be able to decrypt messages from Hybrid Access Gateway, import the SAML certificate of Hybrid Access Gateway into the PRIME keystore, or alternatively the complete chain of certificates: 

    Example: java keytool command
    keytool -importcert -alias <alias> -file hag.saml.pem -keystore samlKeystore.jks
 Configure metadata in PRIME

SAML is based on the trust relationship established between the Identity Provider (IdP) Hybrid Access Gateway and the Service Provider (SP) PRIME. This trust is based on an exchange of metadata files between IdP and SP. Also, it’s very important to know how to exchange the messages in a safe and encoded way. 

The service provider metadata for PRIME are preconfigured and located in the PRIME application folder \prime_explorer\WEB-INF\classes\saml_config\

  1. Open the file \prime_explorer\WEB-INF\classes\saml_config\prime_explorer_saml_metadata.xml for editing.
  2. Edit the host location, where the application will receive the SAML token, by replacing <protocol>://<hostname>:<port> with the real location, including the correct protocol, DNS name of the PRIME server and corresponding port:

    Example: prime_explorer_saml_metadata.xml
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="<protocol>://<hostname>:<port>/prime_explorer/saml/SingleLogout"/> 
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="<protocol>://<hostname>:<port>/prime_explorer/saml/SingleLogout"/> 
    ... 
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="<protocol>://<hostname>:<port>/prime_explorer/saml/SSO" index="0" isDefault="true"/> 
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="<protocol>://<hostname>:<port>/prime_explorer/saml/SSO" index="1"/>

    Example for SSL port 443: https://prime.local/ 

  3. Open the certificate file prime.saml.pem that was created in the section Create PRIME SAML certificate in base64 format in a text editor. Copy the content between BEGIN CERTIFICATE and END CERTIFICATE.

  4. Back in the file prime_explorer_saml_metadata.xml, in the sections for signing and encryption, paste the copied base64 content to replace Base64_Certificate:

    Example: prime_explorer_saml_metadata.xml
    <md:KeyDescriptor use="signing"> 
        <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> 
            <ds:X509Data> 
                <ds:X509Certificate> 
                    Base64_Certificate 
                </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> 
                    Base64_Certificate 
                </ds:X509Certificate> 
            </ds:X509Data> 
        </ds:KeyInfo> 
    </md:KeyDescriptor>  
  5. Open the file \prime_explorer\WEB-INF\classes\saml_config\ussp_saml_metadata.xml for editing.
  6. In ussp_saml_metadata.xml, follow steps 2 and 3 to edit the host location and enter the base64 content of the certificate.
 Create SAML authentication profile

To integrate Nexus PRIME with SAML single sign-on, use SAML authentication in PRIME. This is configured in PRIME Designer in the section Authentication Profile: 

  1. In PRIME Designer, configure an Authentication profile with the following content:
    1. Set Profile Type to SAML SSO Core Object.
    2. Set Identity template to the type of core template PRIME wants to authenticate with, for example Employee in standard. 
    3. Set User name to the field name the user shall authenticate with
      For example, iHybrid Access Gateway is configured to send the sAMAccountName within the SAML response, PRIME needs to map the value to the same field.  
    4. Enter a value in User Display, for example FirstName, LastName. The value must reflect available field names in the Identity template selected above.
      The User Display for the logged-in user will be shown in PRIME Explorer in the upper right corner.
    5. On the SAML configuration tab, check Enable SAML settings.
    6. Optional: Go to the tab User processes. Add processes that can be run for the logged-in user, for example Change PIN.
      The User Processes for the logged-in user will be available when clicking on the User Display in PRIME Explorer.

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

    Keep the SAML IdP metadata file name, since it is configured in the PRIME spring beans.

    If the file name needs to be changed, then also change the configuration in /prime_explorer/WEB-INF/classes/spring/saml-meta-beans.xml accordingly.