Versions Compared

Old Version 7

changes.mady.by.user Karolin Hemmingsson (Unlicensed)

Saved on

compared with

New Version 8

changes.mady.by.user Karolin Hemmingsson (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: minor updates

This article describes how to connect Smart ID Identity Manager (PRIME) to the Smart ID Digital Access component (Hybrid Access Gateway) Extension Programming Interface (XPI), to enable provisioning of users and Smart ID Mobile App (Personal Mobile) profiles. 

Prerequisites

Expand
titlePrerequisites

Step-by-step instruction

Expand
titleOnly for demo use cases: Create Digital Access server certificate

To be able to use the Digital Access XPI interface, 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:

    Code Block
    languagetext
    titleExample: java keytool command
    keytool -genkey -keyalg RSA -alias selfsigned -keystore hag.local.jks -storepass <password> -validity 1080 -keysize 2048


  2. To use the Digital Access server certificate, a p12 container is required with the corresponding certificate. Use the created jks container to transform to p12:

    Code Block
    languagetext
    titleExample: 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:

    Code Block
    languagetext
    titleExample: Extract certificate
    openssl pkcs12 -in hag.local.p12 -nokeys -out hag.local.pem


  4. Extract the key:

    Code Block
    languagetext
    titleExample: Extract key
    openssl pkcs12 -in hag.local.p12 -nodes -nocerts -out key.pem



Expand
titleInstall server certificate

To install the server certificate in Digital Access component:

  1. Log in to Digital Access Admin and go to Manage System > Certificates.
  2. In the section Server Certificates, click Add Server Certificate… 

  3. Fill out the required information, for example:

    Panel
    titleExample: Add server certificate in Digital Access component

    Display name: hag.local

    Certificate: hag.local.pem

    Key: key.pem

    Click ? for more information.

  4. Click Next > to finish the wizard.


Expand
titleTrust server certificate

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

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

    Note

    Make sure to use the right Java version.


    Code Block
    languagetext
    titleExample: 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.


Expand
titleCreate password authentication method

An Authentication Method of type Password must be set up, so that Identity Manager can authenticate against Digital Access XPI.

  1. Log in to Digital Access Admin and go to Manage System > Authentication Method.
  2. Click Add Authentication Method…

  3. Check Nexus Password. 

  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.


Expand
titleDefine XPI user

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 in Digital Access for more information.

To assign the delegated administrator role to a user:

  1. Log in to Digital Access Admin 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 theLDAP password.


Expand
titleEnable XPI in Digital Access component

For Identity Manager to get access to Digital Access component over the XPI, the XPI must be enabled.

To enable the Digital Access XPI:

  1. Log in to Digital Access Admin 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 Digital Access appliance.
    2. In Server Certificate, select the certificate that was added before, for example hag.local.


note

To activate the HAG Settings option in Identity Manager main client under the Admin tab:

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

    • Add the following bean definition:

    Expand
    titleActivate Digital Access in Identity Manager

    This task is only necessary for PRIME version 3.7.1 and earlier. From version 3.7.2, the HAG Settings option will be activated by default.

    Code Block
    languagetext
    titleExample: 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>

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

    Panel
    titleExample: 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>

  • Save the file custom-beans-BIM.xml.
  • If the Tomcat server is running, restart it to reload all configurations.
    • Expand
    titleEnter Digital Access XPI credentials in Identity Manager

    To enter the Digital Access XPI credentials in Identity Manager:

    1. Open Identity Manager main client, 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 Digital Access.
      2. In Authentication Method ID, enter the ID of the authentication method from Digital Access.

        In this example from Digital Access, the Authentication Method ID is 4:
         
    3. Click Save.


    Expand
    titleConfigure Digital Access provisioning in Identity Manager

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

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

    To adapt the settings in the Digital Access 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 Identity Manager is communicating with Digital Access 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 Identity Manager configuration. For more information on the parameters, see provisionUserToHagParameterizedTask in Standard service tasks in Identity Manager. 


    This article is valid from Nexus PRIME 3.6. 

    Related information