• Installed PRIME, see Install Identity Manager
• Installed Hybrid Access Gateway, see Deploy Hybrid Access Gateway and do initial setup

To be able to use the XPI interface of HAG an SSL server certificates needs to be provided. 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 HAG, a p12 container is required with the corresponding certificate. 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. Extract the certificate:

   Example: Extract certificate

   openssl pkcs12 -in hag.local.p12 -nokeys -out hag.local.pem

   
   

4. Extract the key:

   Example: Extract key

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

   
   

To install the server certificate in Hybrid Access Gateway:

1. Log in to Hybrid Access Gateway administration interface and go to Manage System > Certificates.
2. In the section Server Certificates, click Add Server Certificate… 

3. Fill out the required information, for example:

   Example: Add server certificate in HAG

   Display name: hag.local

   Certificate: hag.local.pem

   Key: key.pem

   Click ? for more information.

4. Click Next > to finish the wizard.

The server certificate needs to be added to the trust store, to make the PRIME server trust the certificate during the XPI call.

1. Add the certificate to the cacerts file of the Java version that the PRIME server runs with.

   Make sure to use the right Java version.

   Example: Trust server certificate

   keytool -import -v -trustcacerts -alias selfsigned -file hag.local.pem -keystore 
   "<path to Java>\lib\security\cacerts"

   The default password of the the cacerts keystore is changeit.

An Authentication Method of type Password must be set up, so that PRIME can authenticate against Hybrid Access Gateway XPI.

1. Log in to Hybrid Access Gateway administration interface and go to Manage System > Authentication Method.
2. Click Add Authentication Method…

3. Check Portwise Password. This option will be renamed to Nexus Password in the release Hybrid Access Gateway 5.13.

4. Click Next >.

5. Enter a Display Name, that is, the name to identify the method for example on the portal.

6. If the password authentication method is only to be used for XPI authentication, uncheck Visible in authentication menu.

7. In the following form, add the default authentication method server, by clicking Add Authentication Method Server... and then Next >.

8. Click Next > until the wizard is finished and the password authentication method is created.

To authenticate to the XPI with username and password, a delegated administrator must be defined. The user must be in the already connected user storage. See Add user storage for more information.

To assign the delegated administrator role to a user:

1. Log in to Hybrid Access Gateway administration interface and go to Manage System > Delegated Management.
2. Click Super Administrator and go to the tab Administrators.
3. Register the user by clicking Add Administrator… Type in the username from the user storage and click Search.
4. Go to Manage Account and Storage > User Accounts. to define the password for the user account.

5. In User ID, enter the user name, or a part of it with wildcards, for example xpi*. Click Search to search for the user and click the corresponding user in the search results.

6. On the tab PortWise Authentication, check Enable PortWise Password for the user account.

7. Provide a password of the user for authentication to the XPI, in either of the following ways:

   1. Enter a password in Password and Verify Password.
      
      OR

   2. Check Use password from User storage. to use the LDAP password.

For PRIME to get access to Hybrid Access Gateway over the XPI, the XPI must be enabled.

To enable the Hybrid Access Gateway XPI:

1. Log in to Hybrid Access Gateway administration interface and go to Manage System > Policy Services.
2. Click the link to the configured Registered Policy Services.
3. Go to the section XPI:REST and WS. Check Enable XPI:WS.
4. Enter the following information:
   1. In Host, enter the IP address or DNS name of the HAG appliance.
   2. In Server Certificate, select the certificate that was added before, for example hag.local.

To activate the HAG Settings option in PRIME Explorer under the Admin tab:

1. Open this file for editing:
   prime_explorer/WEB-INF/classes/spring/custom-beans-BIM.xml

2. Add the following bean definition:

   Example: custom-beans-BIM.xml - Add hagXPIContext bean

   <bean id="hagXPIContext" class="de.vps.act.frontend.admin.systemproperty.ContextVO" scope="prototype">
   
     <property name="contextVOName" value="hagXPIContext"></property>
     <property name="name" value="hag.xpi.settings"></property>
     <property name="propertyVOs">
       <list>
         <bean name="hagXPIuserProperty" class="de.vps.act.frontend.admin.systemproperty.PropertyVO" scope="prototype">
            <property name="name" value="user"></property>
            <property name="text" value="hag.xpi.property.user" />
            <property name="type"><util:constant static-field="de.vps.act.kernel.datatype.DataType.STRING" /> 
            </property>
            <property name="defaultValue" value="xpiadmin"></property>
         </bean>
         <bean name="hagXPIPasswordProperty" class="de.vps.act.frontend.admin.systemproperty.PropertyVO" scope="prototype">
            <property name="name" value="password"></property>
            <property name="text" value="hag.xpi.property.password" />
            <property name="isSecretValue" value="true" />
            <property name="type">
               <util:constant static-field="de.vps.act.kernel.datatype.DataType.REF"/>
            </property>
         </bean>
         <bean name="hagXPIAuthenticationMethodIdProperty" class="de.vps.act.frontend.admin.systemproperty.PropertyVO" scope="prototype">
            <property name="name" value="authenticationMethodId"></property> 
            <property name="text" value="hag.xpi.property.authenticationMethodId" />
            <property name="type"><util:constant static-field="de.vps.act.kernel.datatype.DataType.NUMERIC" />
            </property>
            <property name="defaultValue" value="3"></property>
         </bean>
       </list>
     </property>
   </bean>
   

3. To activate the hagXPIContext bean, add it to the systemPropertyBuilder bean in the same file:

   Example: custom-beans-BIM.xml - Update systemPropertyBuilder bean

   <bean id="systemPropertyBuilder" class="de.vps.act.frontend.admin.systemproperty.SystemPropertyBuilder" scope="prototype">

   <property name="systemProperties">

   <list>

   <ref bean="hagXPIContext" />

   <ref bean="smtpContext" />

   <ref bean="licenseContext" />

   <ref bean="tunnelServerContext" />

   <ref bean="coreTemplateContext" />

   </list>

   </property>

   </bean>

4. Save the file custom-beans-BIM.xml.
5. If the Tomcat server is running, restart it to reload all configurations.

To enter the Hybrid Access Gateway XPI credentials in PRIME:

1. Open PRIME Explorer, and go to Admin > Configure System Properties > HAG Settings.
2. Enter the following data:
   1. In User and Password, enter the details of the user that was set up as Super Administrator in Hybrid Access Gateway.
   2. In Authentication Method ID, enter the ID of the authentication method from Hybrid Access Gateway.
      
      In this example from Hybrid Access Gateway, the Authentication Method ID is 4:
      
3. Click Save.

To define which data should be provision from PRIME to HAG, the settings in the HAG provisioning task must be adapted. For more information, see provisionUserToHagParameterizedTask in Standard service tasks.

The task is used in the PRIME processes that provision the data to HAG. There are processes available in the Base configuration package (BIM), called BaseProcActivateAndProvisionUserToHag and BaseProcDeactivateAndProvisionUserToHag.

To adapt the settings in the HAG provisioning task, do the following for each process:

1. Open the process, for example BaseProcActivateAndProvisionUserToHag.
2. Click the edit icon on the corresponding task. The available parameters are displayed.
3. Enter parameter values:
   1. In hagUrl, provide the host and port information.
      Since PRIME is communicating with HAG over HTTPS we need to make sure the configured host provides a corresponding SSL certificate. See Install Server Certificate and Trust Server Certificate above.
   2. Adapt the other fields to reflect the PRIME configuration. For more information on the parameters, see provisionUserToHagParameterizedTask in Standard service tasks.