Client Authentication with a Certificate Server

MicroStrategy Mobile Server can use a certificate server to authenticate the identity of Android and iOS mobile clients. This certificate server can run on the same application server as the Mobile Server, or on a different one.

When client authentication is enabled and a certificate server is configured, a valid certificate must be issued to mobile clients that allows them to gain access to the Mobile Server. This process ensures that each mobile device is authorized to access the system, and allows you to deny authentication requests from devices which may have been compromised.

To Set Up the Client Certificate Server

Set up SSL between mobile devices and MicroStrategy Mobile using the procedure in the Administering MicroStrategy Web and Mobile chapter in the System Administration Help.
Install the certificate server using the ASP or JSP installation file from your MicroStrategy installation folder. The ASP files are located in MicroStrategy\Mobile Server ASPx\CertificateServer. The JSP file is located in MicroStrategy\Mobile Server JSP\CertificateServer.war.
Note the following:
- To set up a certificate server with Microsoft Internet Information Services (IIS) 6.0, you must have the Read Scripts and Run Scripts permissions, and you must deploy the certificate server as a virtual directory.
- To set up a certificate server with Microsoft Internet Information Services (IIS) 7.0 or newer, you must deploy the certificate server as an application.
You must choose a signed certificate from a third party certificate authority to configure the certificate server. Either use the same certificate generated for SSL, or obtain a different one.
Once you have the certificate, install it on your application server, add it to a previously created trust list, and enable client authentication. Refer to your application server documentation for information on installing the certificate, creating a trust list, and configuring the application server to use client authentication.

Configuring the CertificateServerConfig.xml File

Specify the Intelligence Server and project name in the certificateServerConfig.xml file, located by default in MicroStrategy\Mobile Server ASPx\CertificateServer\ WEB-INF\xml\certificateServerConfig.xml for the ASP version, or MicroStrategy\Mobile Server JSP\ CertificateServer\WEB-INF\xml\ certificateServerConfig.xml for the JSP version. This information is used to authenticate clients before they have obtained a certificate.
In the certificateServerConfig.xml file, ensure that the correct provider is selected. This information is dependent on the MicroStrategy Mobile Server platform, as displayed in the following example for Tomcat application servers:
```
<provider class="com.microstrategy.web.certificate.TomcatCertificateProvider"/>
```
In the certificateServerConfig.xml file, ensure that the X.509 parameters are correctly configured for your environment.
In the certificateServerConfig.xml file, specify your signing certificate format as either Java Keystore (JKS) or Distinguished Encoding Rules (DER).
To enable the certificate server to revoke specified client certificates, set up the Certificate Revocation List (CRL) on the application server. Also configure the CRL Distribution Point (CDP) to designate a URL where the application server can check for CRLs. Configure the CDPLocation parameter in the certificateServerConfig.xml file by specifying the URL for the CRL. Refer to your application server documentation for information on configuring the CRL and CDP.

Enabling the Certificate Server in the Mobile Configuration

When creating your MicroStrategy Mobile configuration, in the iPhone Settings, iPad Settings, Phone Settings, or Tablet Settings tab, select the Use Certificate Server check box, and in the text field, specify a URL for the certificate server. Because the certificate server must be configured with SSL, ensure that the URL employs the fully qualified name of the certificate server, and begins with https://, as in the following examples.

ASP:

https://fully_qualified_domain_name:port/ CertificateServer/asp/certificate.aspx

JSP:

https://fully_qualified_domain_name:port/ CertificateServer

https://fully_qualified_domain_name:port/ CertificateServer/servlet/certificate

Where:

• fully_qualified_domain_name:port is the location and port of your certificate server. For example, machine_name.domain.com:8443.

For more information on creating a mobile configuration, see Configuring MicroStrategy Mobile for iPhone or iPad or Configuring MicroStrategy Mobile for Android.

Downloading a Certificate to a Mobile Client

When a client requires a certificate, the Mobile user is prompted to begin the download. When a user clicks OK to begin the download, they are prompted to log in to the project specified in the certificateServerConfig.xml file.
Users can also manually download a client certificate from the Advanced Settings screen of the MicroStrategy Mobile application. For more information, see Downloading a Client Certificate from the Certificate Server.

Managing Certificates with the Certificate Server API

To obtain a certificate for each mobile device through the API, use one of the following URLs.
ASP:
https://fully_qualified_domain_name:port/ CertificateServer/asp/certificate.aspx?action=GetCertificate&loginParams=<auth><device_id>mobile_device</device_id><pkcs12_password>keystore_password</pkcs12_password><field n="pwd" v="MSTR_password"/><field n="login" v="MSTR_login"/></auth>
JSP:
https://fully_qualified_domain_name:port/ CertificateServer/servlet/certificate?action=GetCertificate&loginParams=<auth><device_id>mobile_device</device_id><pkcs12_password>keystore_password</pkcs12_password><field n="pwd" v="MSTR_password"/><field n="login" v="MSTR_login"/></auth>
Where:
- fully_qualified_domain_name:port is the location and port of your certificate server. For example, machine_name.domain.com:8443.
- mobile_device is the UUID of the mobile device.
- keystore_password is the pkcs12 password that is used for the generated keystore.
- MSTR_password is the user's MicroStrategy password for the project specified in certificateServerConfig.xml.
- MSTR_login is the user's MicroStrategy login for the project specified in certificateServerConfig.xml.
To view a list of certificates on the certificate server through the API, the application server administrator uses one of two URLs, as displayed in the examples below.
ASP:
https://fully_qualified_domain_name:port/ CertificateServer/asp/CertificateAdmin.aspx?action=GetCertificateList
JSP:
https://fully_qualified_domain_name:port/ CertificateServer/servlet/certificateAdmin?action=GetCertificateList
where fully_qualified_domain_name:port is the location and port of your certificate server. For example, machine_name.domain.com:8443.
To revoke a specific certificate through the API, the application server administrator uses one of two URLs, as displayed in the examples below.
ASP:
https://fully_qualified_domain_name:port/ CertificateServer/asp/CertificateAdmin.aspx?action=RevokeCertificate&serialNumber=serial_number
JSP:
https://fully_qualified_domain_name:port/servlet/ certificateAdmin?action=RevokeCertificate&serialNumber=serial_number
Where:
- fully_qualified_domain_name:port is the location and port of your certificate server. For example, machine_name.domain.com:8443.
- serial_number is the serial number of the certificate to be revoked. This number can be retrieved from the list of certificates.
To revoke all certificates for a specific mobile device through the API, the application server administrator uses one of two URLs, as displayed in the examples below.
ASP:
https://fully_qualified_domain_name:port/ CertificateServer/asp/CertificateAdmin.aspx?action=RevokeCertificate&uuid=device_uuid
JSP:
https://fully_qualified_domain_name:port/servlet/ certificateAdmin?action=RevokeCertificate&uuid=device_uuid
Where:
- fully_qualified_domain_name:port is the location and port of your certificate server. For example, machine_name.domain.com:8443.
- device_uuid is the universally unique identifier of the mobile device.