Domain Pinning & Trust

Domain Pinning and Trust allows for the restricted use of certificates and public keys to be bound to specific domains. This allows for the support and use of private certificates and certificate authorities, or to validate the exact certificates matches expected from an app end point.

Configurations	Description
Add Domain	To adda a new entry into the Domain List, use the Add Domain button and provide the domain name (e.g. corp.mycompany.com) of the domain you want to pin a certificate of public key. You can also use a wildcard domain to include the root domain and the associated subdomains (e.g. .mycompany.com). This entry will include the base domain (mycompany.com) and its subdomains. Only a leading wildcard “” is accepted (e.g. *.mycompany.com).
Domain List	Domain Name This is a list of added domain names that are sortable in ascending or descending order. Include Subdomains (Checkbox) Select the check box to enable the inclusion of the subdomains associated to the provided domain. Note: This option only includes the subdomains and not the Domain Name itself. Trash Icon Delete the domain name, it’s certificates and public keys.
Certificates	Add Certificate Provide a public SSL/TLS Identity or issuing certificate file on your computer. Allowed formats (.pem, .crt, .ca-bundle, .cer). Uploading a certificate bundle will add all of it’s included certificates.
	Certificate Options The small options icon button next to the certificate name contains additional actions: Download Download the certificate. Delete Delete the certificate. Certificate Details Name Certificate name. Note: Clicking on the certificate name will open a modal window with the certificate details. Expiration Date of certificate expiration. Pin Checkbox Enabling Pin will require an exact match of the uploaded certificate presented by the app end point to the certificate uploaded. Trust Options This settings contains two options that determine how to use the certificate for overall trust. Chain Checkbox Select to use the uploaded certificate in addition to the OS’s trust chain. Note: The primary use of Chaining a certificate to the trust store is when certificates are used from private Certificate Authorities. Override Select to ignore certificate validation failures. Enabling this option for the certificate will allow the cert to be trusted even if it has validation failures.
Public Keys	Add Public Key Select a certificate file from your computer. The Platform will extract the public key from the certificate to add to the public key config and discard the rest of the certificate. Supported algorithms - RSA, DSA, Elliptic Curve, RSAPSS, PKCS #1, #5, #8.
	Public Key Options Name Public key name. Override Select to ignore certificate validation failures from certificates that match the Public Key.

Pinning and Trust FAQ’s

Q. Why would I use a Public Key?

A. Using the Public Key of a certificate allows for the app to trust the identity certificate presented from the app endpoint even if it has been replaced or updated. This trust remains valid as long as the identity certificate was created from the same issuing certificate that matches the registered public key. For example, you have an identity certificate on a server that the app calls to and you have pinned it’s public key. If that server identity certificate is replaced due to expiration or for other reasons, the app will not need to be re-integrated with the new identity certificate because of pinning the certificate to itself.

Q. Why should I chain a certificate?

A. Chaining a certificate should be used if your app is leveraging a server that has identity certificates issued from non-public Certificate Authorities. For example, if your organization uses an internal Microsoft or other Certificate Authority, any connection to endpoints utilizing certificates created by those CA’s will fail due to the root certificates not being present in the mobile devices trust store.

To include the use of private CA’s root or issuing Certificate for all of the app traffic calls, add those certificates via the Global Trust Feature.

Q. Why would I choose to use the override option?

A. Using the override option will allow the app’s http(s) connection to succeed even if the certificate presented by the endpoint has failed verification. Failed verification can be caused by an expired certificate, mismatched common name, missing DNS value in the Subject Alt Name, etc.

The override feature is generally used for testing purposes or when apps need a temporarily connect to a server until the failing certificate can be replaced.

Q. When do I use Pin and Trust together?

A. Using the Trust without the Pin option is essentially used for a private issuing certificate that is adding an additional trust for that domain or subdomain. If you also include the Pin Option with Trust, then the end point must present the exact domain certificate that is pinned to pass validation.

If you pin the private issuing certificate, then the domain or subdomains MUST have this issuing private CA cert in the chain.