Certificate pinning for AppConnect apps

You can heighten security for the communication between AppConnect apps and enterprise servers or cloud services by using certificate pinning. Certificate pinning can protect an AppConnect app from man-in-the-middle attacks and rogue Certificate Authorities. This protection is possible because in the MobileIron Core Admin Portal, you configure a set of trusted certificates and domain names for the AppConnect app. When the app makes a connection request, the AppConnect library within the app makes sure that:

• the certificate presented by the server in response to the connection request is in the trusted set of certificates, or chains to a certificate in the trusted set.
• the domain in the app's URL request matches a domain name or domain wildcard that you specified for that certificate.

If either of these requirements is not met, the app's connection request fails.

Note the following:

• Do not use certificate pinning with AppTunnel with HTTP/S tunneling or AppTunnel with TCP tunneling (Advanced AppTunnel).

• You can use certificate pinning with the feature Certificate authentication from AppConnect apps to enterprise servicesIn this feature, the app sends a certificate to identify and authenticate the app user to the enterprise server or cloud service.

Certificate pinning for AppConnect apps requires:

• Apps built with AppConnect 4.1 for iOS or supported newer versions.
• Mobile@Work 10.0.0 for iOS or supported newer versions.

Related topics 

• About certificates used in certificate pinning
• About domains in certificate pinning
• Configuring certificate pinning
• Uploading the trusted certificates
• Creating a Client TLS configuration
• Modifying an AppConnect app configuration, Web@Work setting, or Docs@Work setting
• Viewing certificate pinning information in Mobile@Work

About certificates used in certificate pinning

Part of configuring AppConnect apps for certificate pinning is uploading the trusted certificates to MobileIron Core so that Core can deliver them to AppConnect apps.  Each certificate that you upload can be:

• a root CA certificate
• a intermediate CA certificate, which can include chained intermediate CAs with or without a root CA.
• a leaf certificate

A trusted certificate used in certificate pinning cannot include a leaf certificate combined with an intermediate CA or root CA.

The certificate must be an X.509 certificate file (.cer, .crt, .pem, or .der) and encoded as binary DER or ASCII PEM.

About domains in certificate pinning

• Certificate pinning domains for root and intermediate CA certificates
• Certificate pinning domains for leaf certificates

Certificate pinning domains for root and intermediate CA certificates

When you specify root CA and intermediate CA certificates for certificate pinning, you also provide the domains of the target enterprise server or cloud service allowed in the AppConnect app's URL request. The AppConnect app's URL request must match one of these domains for the connection to succeed. You can provide specific domains, or domains using the wildcard character *. The following table provides examples.

Table 39.  Allowed domains in certificate pinning

Domain	Description
www.mycompany.com	App URL request must match exactly.
*.mycompany.com	App URL request must end in mycompany.com.
*	App URL request can be anything. When a domain is the wildcard character * by itself, the field Allow use of system CA certificates is automatically not selected and disabled.

Certificate pinning domains for leaf certificates

When you specify a leaf certificate for certificate pinning, Core extracts the domains from the certificate. The AppConnect app's URL request must match one of these domains for the connection to succeed. You cannot add to or modify the list of domains.

Core extracts the domains from these fields in the certificate:

• the CN (Common Name) in the Subject field
• the SAN (Subject Alternative Name) fields, if available

Configuring certificate pinning

The overall tasks to configure certificate pinning are:

1. Uploading the trusted certificates
2. Creating a Client TLS configuration
3. Modifying an AppConnect app configuration, Web@Work setting, or Docs@Work setting

Uploading the trusted certificates

Upload to MobileIron Core the certificate that the enterprise server will present to the app in response to a connection request. You upload the certificate into a certificate setting.

Procedure 

1. In the Admin Portal, go to Policies & Configs > Configurations.
2. Click Add New > Certificates.
3. Fill in the entries:
   Name: Enter brief text that identifies certificate setting.
   Description: Enter additional text that clarifies the purpose of this certificate setting.
   Click Browse to select the X.509 certificate file (.cer, .crt, .pem, or .der) to upload to Core. The certificate must be encoded as binary DER or ASCII PEM.
4. Click Save.

Do not apply a label to the certificate setting. You will apply a label to the AppConnect app configuration, Web@Work setting, or Docs@Work setting that refers to a Client TLS configuration that refers to this certificate setting.

Creating a Client TLS configuration

Create a Client TLS configuration that references the certificate setting.

Procedure 

1. In the Admin Portal, go to Policies & Configs > Configurations.
2. Click Add New > Client TLS.
3. For Name, enter a name for the Client TLS configuration.
4. For Description, enter text that clarifies the purpose of this Client TLS configuration.
5. Click Add+.
   A row displays in the Trusted Certificates table.
6. For Name, select from the drop-down the certificate setting you added in Uploading the trusted certificates.Uploading the trusted certificates
7. For the Domain:
   • For intermediate and root CA certificates, enter one or more domains, as described in Certificate pinning domains for root and intermediate CA certificates.
     Enter a comma after a domain to make additional entries. Use the Enter key when you have finished entering domains.
   • For leaf certificates, you cannot enter domains. Core automatically extracts the domains from the certificate and displays them.

8. Select Allow use of system CA certificatesto allow the app to also accept system CA certificates if presented by the enterprise service.

   System CA certificates are the certificates in the device's trusted certificate store.

   This option is automatically not selected and disabled when a domain you specify is the wildcard character * by itself.

9. Click Save.

The Admin Portal does not allow you to apply a label to the Client TLS configuration. You will apply a label to the AppConnect app configuration, Web@Work setting, or Docs@Work setting that refers to the Client TLS configuration.

You cannot delete a certificate setting if it is referenced from a Client TLS configuration.

Modifying an AppConnect app configuration, Web@Work setting, or Docs@Work setting

Do the following tasks to reference the Client TLS configuration from the AppConnect app configuration for the AppConnect app.

• Creating an AppConnect app configuration for the app if one does not already exist
• Configuring the Client TLS configuration in the AppConnect app configuration

For Web@Work and Docs@Work, follow similar steps in a Web@Work setting and Docs@Work setting. Just as you do in an AppConnect app configuration, you select Enable Client TLS Configuration, and select the appropriate Client TLS configuration from the drop-down options.

Creating an AppConnect app configuration for the app if one does not already exist

Do the following if an AppConnect app configuration does not exist for the app.

Procedure 

1. In the Admin Portal, go to Policies & Configs > Configurations.
2. Look for an APPCONFIG setting type for the app.
3. If found, continue to Configuring the Client TLS configuration in the AppConnect app configuration.
4. If not found, click Add New > AppConnect > App Configuration.
5. For Name, enter a name for the AppConnect app configuration.
6. For Description, enter a description for the AppConnect app configuration.
7. For Application, enter the bundle ID of the app, or select the app from the drop-down list if it is in the App Catalog.
8. Click Save.

Apply the appropriate labels to the new AppConnect app configuration:

1. Select the AppConnect app configuration that you just created.
2. Select Actions > Apply To Label.
3. Select the appropriate labels.
4. Click Apply.
5. Click OK.

Configuring the Client TLS configuration in the AppConnect app configuration

Procedure 

1. In the Admin Portal, go to Policies & Configs > Configurations.
2. Select the AppConnect app configuration for the app (the Setting Type is APPCONFIG).
3. Click Edit.
4. In the Client TLS section, select Enable Client TLS Configuration.
5. From the drop-down, select the Client TLS configuration that you created.
6. Click Save.

You cannot delete a Client TLS configuration if it is referenced from an AppConnect app configuration.

Viewing certificate pinning information in Mobile@Work

You can use Mobile@Work to view certificate pinning information for an AppConnect app.

Procedure 

1. Open Mobile@Work on the device.
2. Tap Settings.
3. Tap Secure Apps.
4. Tap the app of interest.
5. Tap Client TLS, which is near the bottom of the screen.
   The client TLS screen displays the set of trusted certificates.
6. Tap a certificate.
   A screen displays with the domains allowed for the certificate.
7. Tap Certificate to see the certificate's details, such as its expiration date.

You can also view the certificate's details in Mobile@Work in Settings > Secure Apps > Stored Certificates.