Product Documentation

Configuring an OpenTrust PKI Adapter for Device Manager

May 07, 2015

XenMobile OpenTrust Adapter was validated with OpenTrust PKI Version 4.7.1 (r131349).

The XenMobile OpenTrust Adapter is a web application running on Tomcat:

  • Windows 2008 R2
  • Java 1.6.0_29 or above, 32 bits version
  • Apache Tomcat 7.0.27
Note: You only need Tomcat core features, not the manager or the documentation, unless you need it. After installation, you can also delete the directory <tomcat_dir>/webapps/ROOT.
The XenMobile OpenTrust Adapter provides an interface that allows Device Manager to submit certificate requests for a signature to an OpenTrust Certificate Manager server. Device Manager submits a request to the OpenTrust adapter to sign a certificate. The OpenTrust Certificate Manager receives the request, signs the certificate and returns it to Device Manager. Device Manager makes these certificate requests in order to generate device identity for mobile device management mutual authentication, or user credential certificates to be used in conjunction with WiFi, VPN, and Exchange ActiveSync profiles for iOS devices. XenMobile recommends that the OpenTrust Adapter is installed on a separate server from the Device Manager host, using its own instance of Tomcat 7.0.

To install OpenTrust Adapter

  1. Copy the provided WAR file to the Tomcat webapps directory. You can change the WAR file name to fit the usage of this adapter instance (wifi_certificate, exchange_certificate, and so on).
  2. Start Tomcat. It will automatically expand and install the web application in its directory.
  3. To check that the adapter is properly running, connect to: http://<server_name>:<port>/<adapter_name/. An Available SOAP services page appears.

To obtain an authentication certificate from OpenTrust PKI

The authentication between the OpenTrust Adapter is secured by using a client certificate that needs to be generated from OpenTrust PKI server.
  1. Log in to the OpenTrust PKI server, browse to Enrollment Entity and then click Request a Certificate.
  2. Select Other and then click Next.
  3. Select Authentication and then click Next.
  4. Enter the required parameters and then click Next.
  5. You now need to validate the certificate request. Navigate to Registration Authority > Enrollment > List Certificate Requests.
  6. Select your certificate request and then click Process selected requests.
  7. Click Approve.
  8. You now need to retrieve the certificate. Navigate toEnrollment Entity > Search for a Certificate > Enrollment.
  9. Enter your search criteria and then click Search.
  10. Find your certificate and then click the name.
  11. Click Integrate this certificate into your browser (or smartcard).
  12. Open the certificate store of your web browser. For example, with Firefox, navigate to Options, click the Encryption tab and then click View Certificates.
  13. In the Certificate Manager, click the Your Certificates tab.
  14. Select your certificate and then click Backup.
  15. Enter the password and save the resulting p12 file. You will need the file and password when you configure the adapter.

To set up access rights on OpenTrust PKI

You need to provide the required access rights to the generated identity.
  1. Navigate to Access Control.
  2. Select your User.
  3. If you already have a group defined to allow SOAP access to the Registration Authority, you can add this user to this group. Select the group and then click Save.
  4. To give individual rights to that user, click the Rights on Modules tab.
  5. Select the Execute check box to give access rights to the Registration Authority.
  6. Click the Rights on Zones & Profiles tab.
  7. For each profile you want the user to be able to control, next to Enrollment, select the Execute check box.
  8. Click Save.

To configure the OpenTrust adapter

  1. Open the file opentrust_adapter.properties in tomcat/webapps/<adapter_name>/WEB_INF/classes and edit it accordingly:
    Key Value

    OpenTrust.RA.Url

    Web address used to access the SOAP interface of the OpenTrust PKI server

    Enrollment.Profile

    OpenTrust Profile name used by this instance

    KeyPair.FileName

    Path to the keypair used to authenticate to OpenTrust PKI SOAP interface

    KeyPair.Psw

    Password of the above mentioned keypair

To set the connection to the adapter

  1. To configure Device Manager with your adapter, on the Options menu, click PKI Entity.
  2. Click New and then enter the required information:
    Parameter Value

    Entity Name

    Name your adapter connection.

    URL

    Enter the URL of the adapter web services interface: http://<server>:<port>/<adapter_name>/GpkiAdapter?wsdl

    Certificate path

    If you are using an authenticated HTTPS connection, select your client cert (p12).

    Certificate password

    Enter the password for the above p12.

  3. Click Load to initiate the connection with the adapter.
  4. Click Ping to check the connectivity.
  5. Click Create to save the adapter configuration.

To configure an iOS profile to deliver certificates to iOS devices

To deliver certificates to iOS devices, you need to configure an iOS profile in Device Manager. For more information on configuring PKI integration with Device Manager, see About XenMobile PKI.
  1. Click the Policies tab.
  2. On the left side, under iOS, click Configurations.
  3. Create a new policy for the PKI authority that you installed by clicking New Configuration > Profiles and Settings > Credentials.
  4. On the General tab, enter the following information:
    1. Identifier. Enter a unique identifier to distinguish the certificate policy.
    2. Display name. Enter a name that will be used to label the policy on the device.
    3. Organization. Enter your company name here.
    4. Descriptions. Type an optional description.
  5. In Allow profile removal operation, click on of the following options:
    • Always: This option allows the profile to always be removable.
    • Authentication: Allows you to enter a required password that is used when profile is removed. Requires a password
    • Never: Prevents the profile from ever being removed.
  6. Select the Allows you to select a specific date check box to specify a date you want to remove the profile.
  7. Select the Duration until removal (in days) check box to enable you to set a period of time after which the profile will automatically be removed.
  8. Next, on the Credential tab, enter the following information:
    1. Credential name. Provide a unique name for the credential.
    2. Description. Optionally, you can type a description for the credential.
    3. Credential Type. Select a credential type according to the PKI configuration you have set up for Device Manager, such as a certificate, a keystore, a server certificate, or a credential provider.
    4. Credential file path, Server certificate, or Credential provider. Select the path or the name of the credential you are adding to the policy. If you are using a Keystore file, then you need to provider the keystore password.
  9. Click Create.

To configure an OpenTrust adapter to use HTTP by using a self-signed certificate

If you want the adapter to be accessible using HTTPS, you need to configure the Tomcat connector accordingly. You can configure the adapter by using a self-signed certificate. This process uses openssl and java keytool.

  1. Create a directory called certs. In that directory, create another directory called ca.
  2. Create a root CA. You need to adapt the subject name and passwords to fit your needs. In the certs directory, issue the following commands:
    openssl genrsa -aes256 -passout pass:zenprise -out ca/ca.key 1024 
     
    openssl req -new -x509 -passin pass:zenprise -key ca/ca.key -out ca/ca.pem -days 3650 -subj "/C=US/ST=CA/L=RWC/O=Zenprise/OU=Zenprise/CN=ZenTestCA/emailAddress=none@zenprise.com" 
     
    openssl x509 -inform PEM -in ca/ca.pem -outform DER -out ca.crt
  3. Create an HTTPS certificate using that CA. Change at least the CN to fit the XenMobile OpenTrust Adapter server name. For example:
    openssl genrsa -aes256 -passout pass:zenprise -out server-key.pem 1024 
     
    openssl req -new -passin pass:zenprise -subj "/C=US/ST=CA/L=RWC/O=Zenprise/OU=Zenprise/CN="MyServerName.zenprise.com"/emailAddress=none@zenprise.com" -days 3650 -key server-key.pem > server.csr 
     
    openssl x509 -req -passin pass:zenprise -in server.csr -out server-crt.pem -CA ca/ca.pem -CAkey ca/ca.key -CAcreateserial -CAserial ca.srl
  4. Create a p12 containing your key and certificate.
    openssl pkcs12 -export -in server-crt.pem -inkey server-key.pem -out MyServerName.p12 -name server
  5. Create a java keystore containing that PKCS12 file.
    keytool -importkeystore -deststorepass changeit -destkeypass changeit  -destkeystore keystore.jks -srckeystore MyServerName.p12  -srcstoretype PKCS12 -alias server
  6. Modify the Tomcat server.xml file to create the HTTPS connector. The file needs to reference the keystore previously created.
    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" 
     
    maxThreads="150" scheme="https" secure="true" 
     
    clientAuth="false" sslProtocol="TLS" 
     
    keystoreFile="C:\Zenprise\Apache Software Foundation\Tomcat 7.0\conf\keystore.jks" keystorePass="changeit"/>
  7. Import the root cert in the java keystore of DeviceManager so that this server certificate can be trusted. On the Device Manager server, issue the following command:
    ke​ytool -import -trustcacerts -alias root -file ca.crt -keystore cacerts
    The keystore file used by Java (cacerts) is usually located in: C:\Program Files\Java\jdk1.6.0_22\jre\lib\security

To configure Device Manager to generate identity certificates from OpenTrust adapter

You will need to generate a certificate from OpenTrust with the following keyUsage:

  • keyEncipherment
  • digitalSignature

Furthermore, you will need an OpenTrust root certificate and a CA certificate.

Caution: This procedure will invalidate all certificates used previously by Device Manager. All devices using a certificate to authenticate, such as iOS and Android, Symbian, and Windows Mobile using Strong Authentication mode will need to be re-enrolled.
  1. Modify pki.xml. This file is located in tomcat/webapps/zdm/WEB-INF/classes. Open it with a text editor, and modify it as follows (the modified parts are in bold text). Keep in mind the following considerations:
    • Path to the certificates.
    • keyUsage of the certs.
    • Name of the OpenTrust connector in the console.
    • The CSR template that has to match your profile definition on the OpenTrust PKI Server.
    <?xml version="1.0" encoding="UTF-8"?> 
     
    <beans xmlns="http://www.springframework.org/schema/beans" 
     
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     
    xmlns:p="http://www.springframework.org/schema/p" 
     
    xsi:schemaLocation=" 
     
    http://www.springframework.org/schema/beans     http://www.springframework.org/schem...-beans-3.0.xsd 
     
    "> 
     
      
     
        <bean id="legacyRoot" class="com.sparus.nps.pki.def.PublicCertFileParams" 
     
              p:certificateFilePath="${ios.mdm.pki.ca-root.certificatefile}" 
     
              p:publiclyTrusted="false" 
     
        /> 
     
      
     
        <bean id="legacyIOsDevicesCa" class="com.sparus.nps.pki.def.KeyStoreParams" 
     
              p:keyStoreType="${ios.mdm.pki.ca-mdm.keystoretype}" 
     
              p:keyStorePath="${ios.mdm.pki.ca-mdm.certificatefile}" 
     
              p:entryAlias="" 
     
              p:keyStorePass="${ios.mdm.pki.ca-mdm.privatekey.password}" 
     
              p:publiclyTrusted="false" 
     
              p:issuerParams-ref="legacyRoot" 
     
        /> 
     
      
     
        <!-- SHTP is the proprietary protocol ZDM uses to communicate 
     
            with Windows and Android devices --> 
     
      
     
        <bean id="legacyShtpDevicesCa" class="com.sparus.nps.pki.def.KeyStoreParams" 
     
              p:keyStoreType="${secure.device.keystore.type}" 
     
              p:keyStorePath="${secure.device.certificate.file}" 
     
              p:entryAlias="${secure.device.alias}" 
     
              p:keyStorePass="${secure.device.private.key.password}" 
     
              p:publiclyTrusted="false" 
     
              p:issuerParams-ref="legacyRoot" 
     
        /> 
     
      
     
        <alias alias="legacyDigitalSigner" name="legacyIOsDevicesCa" /> 
     
      
     
        <bean id="legacySslCert" class="com.sparus.nps.pki.def.KeyStoreParams" 
     
              p:keyStoreType="${ios.mdm.pki.ssl.keystoretype}" 
     
              p:keyStorePath="${ios.mdm.pki.ssl.certificatefile}" 
     
              p:entryAlias="" 
     
              p:keyStorePass="${ios.mdm.pki.ssl.privatekey.password}" 
     
              p:publiclyTrusted="false" 
     
        /> 
     
      
     
      
     
        <bean id="OT_Root_cert" class="com.sparus.nps.pki.def.PublicCertFileParams" 
     
              p:certificateFilePath="C:\Program Files\Zenprise\Zenprise Device Manager\tomcat\conf\otroot.cer" 
     
              p:publiclyTrusted="false" 
     
        /> 
     
      
     
        <bean id="OT_CA_cert" class="com.sparus.nps.pki.def.PublicCertFileParams" 
     
              p:certificateFilePath="C:\Program Files\Zenprise\Zenprise Device Manager\tomcat\conf\otinter.cer" 
     
              p:publiclyTrusted="false" 
     
              p:issuerParams-ref="OT_Root_cert" 
     
        /> 
     
      
     
        <bean id="OT_RA_cert" class="com.sparus.nps.pki.def.KeyStoreParams" 
     
              p:keyStoreType="PKCS12" 
     
              p:keyStorePath="C:\Program Files\Zenprise\Zenprise Device Manager\tomcat\conf\otadmin.p12" 
     
              p:entryAlias="" 
     
              p:keyStorePass="opentrust" 
     
              p:issuerParams-ref="OT_CA_cert" 
     
        /> 
     
      
     
        <bean class="com.sparus.nps.pki.spi.impl.GpkiCa" id="OT_CA"> 
     
            <property name="caCertificate"> 
     
                <description> 
     
                    This CA's certificate. 
     
      
     
                    WARNING! In order for tomcat to accept clients presenting identities 
     
                    issued by this CA, tomcat's truststore has to be modified accordingly 
     
                     (e.g. installing in it the certificate referred to here). 
     
                </description> 
     
                <bean factory-bean="certFactory" factory-method="buildPublic"> 
     
                    <constructor-arg ref="OT_CA_cert" /> 
     
                </bean> 
     
            </property> 
     
            <property name="entityName" value="OTAdapter"> 
     
                <description> 
     
                    This is the GPKI entity name as defined in the console. 
     
                </description> 
     
            </property> 
     
            <property name="requestProperties"> 
     
                <description> 
     
                    If the adapter defines user parameters (i.e., non-injected parameters), 
     
                    then they can be defined here. EMC adapter currently does not define 
     
                    any parameters. 
     
                </description> 
     
                <bean class="com.sparus.nps.pki.gpki.util.SimpleRequestProperties"> 
     
                    <constructor-arg index="0" type="java.util.Map"> 
     
                        <map key-type="java.lang.String" value-type="java.lang.String"> 
     
                            <!--<entry key="[PARAMETER NAME]" value="[PARAMETER VALUE]" />--> 
     
                        </map> 
     
                    </constructor-arg> 
     
                </bean> 
     
            </property> 
     
            <property name="raEncryptionCert"> 
     
                <description> 
     
                    RA encryption cert. MUST be issued by the certificate referred to 
     
                    in property caCertificate, i.e. the CA certificate, i.e. the certificate 
     
                    that will sign device identities. 
     
      
     
                    This cert MUST have keyUsage: keyEncipherment. 
     
      
     
                    RA encryption cert may be the same one as RA signing cert. 
     
                </description> 
     
                <bean factory-bean="certFactory" factory-method="buildPrivate"> 
     
                    <constructor-arg ref="OT_RA_cert" /> 
     
                </bean> 
     
            </property> 
     
            <property name="raSigningCert"> 
     
                <description> 
     
                    RA signing cert. MUST be issued by the certificate referred to 
     
                    in property caCertificate, i.e. the CA certificate, i.e. the certificate 
     
                    that will sign device identities. 
     
      
     
                    This cert MUST have keyUsage: digitalSignature. 
     
      
     
                    RA signing cert may be the same one as RA encryption cert. 
     
                </description> 
     
                <bean factory-bean="certFactory" factory-method="buildPrivate"> 
     
                    <constructor-arg ref="OT_RA_cert" /> 
     
                </bean> 
     
            </property> 
     
            <property name="csrTemplate"> 
     
                <bean class="com.sparus.nps.pki.spi.impl.CsrMacroTemplate"> 
     
                    <description> 
     
                        Template for the CSR. 
     
      
     
                        WARNING! Macros have to be specified using '%{...}', instead 
     
                        of '${...}', in XML files. 
     
                    </description> 
     
                    <property name="dnFields"> 
     
                        <list> 
     
                            <description> 
     
                                The following are samples. Remove or add others as you like. 
     
                            </description> 
     
                            <bean class="com.sparus.nps.pki.def.DNFieldBean" p:oid="CN" p:value="%{user.loginname}" /> 
     
                            <bean class="com.sparus.nps.pki.def.DNFieldBean" p:oid="OU" p:value="aeotn" /> 
     
                            <bean class="com.sparus.nps.pki.def.DNFieldBean" p:oid="O" p:value="noise" /> 
     
                            <bean class="com.sparus.nps.pki.def.DNFieldBean" p:oid="C" p:value="DE" /> 
     
                        </list> 
     
                    </property> 
     
                    <property name="altnames"> 
     
                        <list> 
     
                            <description> 
     
                                The following are samples. Remove or add others as you like. 
     
                            </description> 
     
                            <bean class="com.sparus.nps.pki.def.AltNameBean" p:sanType="rfc822Name" p:value="%{user.mail}" /> 
     
                            <bean class="com.sparus.nps.pki.def.AltNameBean" p:sanType="userPrincipalName" p:value="%{user.username}@home.net" /> 
     
                        </list> 
     
                    </property> 
     
                </bean> 
     
            </property> 
     
        </bean> 
     
      
     
      
     
        <!-- 
     
            The new PkiSpi infrastructure is designed to support all the PKI 
     
            capabilities we can reasonably be expected to need in the average term. 
     
            However, the rest (installer / business process) isn't up to par 
     
            yet; as such, we're retrofitting this infrastructure to work with 
     
            our current setup. That's the meaning behind the word "legacy" 
     
            in this context. 
     
        --> 
     
      
     
        <bean id="certFactory" class="com.sparus.nps.pki.def.ZdmCertificateFactory"> 
     
            <description> 
     
                The ZdmCertificateFactory builds public key certificate objects 
     
                from either PublicCertFileParams, PrivateCertFileParams or 
     
                KeyStoreParams; and private key certificate objects (public 
     
                key + private) from PrivateCertFileParams and KeyStoreParams. 
     
      
     
                Factory method for the former is: buildPublic; for the latter: buildPrivate. 
     
            </description> 
     
        </bean> 
     
      
     
        <bean id="serialNumberGen" class="com.sparus.nps.pki.gen.CertificateSerialNumberSequenceImpl" /> 
     
      
     
        <bean id="com.everywan.security.PkiSpi.internal" class="com.sparus.nps.pki.spi.impl.PluggablePki" lazy-init="true"> 
     
            <property name="digitalSignatureRoot"> 
     
                <bean factory-bean="certFactory" factory-method="buildPublic"> 
     
                    <constructor-arg ref="legacyRoot" /> 
     
                </bean> 
     
            </property> 
     
            <property name="sslRoot"><null /></property> <!-- We don't have the config for this... --> 
     
      
     
            <property name="digitalSigningCertificate"> 
     
                <bean factory-bean="certFactory" factory-method="buildPrivate"> 
     
                    <constructor-arg ref="legacyDigitalSigner" /> 
     
                </bean> 
     
            </property> 
     
            <property name="sslCertificate"> 
     
                <bean factory-bean="certFactory" factory-method="buildPrivate"> 
     
                    <constructor-arg ref="legacySslCert" /> 
     
                </bean> 
     
            </property> 
     
      
     
            <property name="shtpCa" ref="OT_CA" /> 
     
      
     
            <property name="iosMdmCa" ref="OT_CA" /> 
     
        </bean> 
     
      
     
        <bean id="com.everywan.security.PkiSpi" factory-bean="com.everywan.security.PkiSpi.factory" factory-method="getBean" /> 
     
      
     
        <bean id="com.everywan.security.PkiSpi.factory" class="com.sparus.nps.pki.def.PkiSpiFacade"> 
     
            <property name="enabled" value="${zdm.pki.enable}" /> 
     
            <property name="enabledBeanId"><idref local="com.everywan.security.PkiSpi.internal" /></property> 
     
        </bean> 
     
       </beans>

To add certificates to the Device Manager keystore

You now need to add the intermediate and root ca certificates to the Device Manager keystore.

  1. Use the java keytool command (adapt the path to your environment): "C:\Program Files\Java\jdk1.6.0_23\jre\bin\keytool" -importcert -trustcacerts -alias "externalCA" -file "C:\Program Files\Zenprise\Zenprise Device Manager\tomcat\conf\mycert.cer" -keystore "C:\Program Files\Zenprise\Zenprise Device Manager\tomcat\conf\cacerts.pem.jks" -storepass notMeaningFul
  2. Restart the Device Manager service to activate the new PKI usage.

To activate logging on Device Manager for the adapter

Logs from the adapter can be found in the tomcat/logs directory of the adapter.
  1. Add a new logger in the log4j configuration to ensure proper error handling and auditing. In Internet Explorer, navigate to the following URL based on your installation: http://<host>/<instance>/log.jsp
  2. Navigate to the bottom of the table and in Add New Logger, add an entry for the com.sparus.nps.pki
  3. Set the logging level to TRACE.