Product Documentation

To create a credential provider using external PKI entities

Dec 21, 2015
When you create a Credential Provider using an external (Microsoft or GPKI) entity, the main difference in configuring the two is the issuing method for the provider; which methods are available depends on the capabilities of the selected PKI entity:
  • If you opt for using a Microsoft CA entity for your Credential Provider, your choice of issuing method will be limited to sign. The sign method of issuance involves creating a new key pair, creating a Certificate Signing Request (CSR) for the key pair, and submitting it to a CA for signature. (You will be prompted to select which certificate template to use for issuance). You must choose a value from those you have defined during the creation of the PKI entity. This is the template name that will be sent to the Microsoft CA along with the Certificate Signing Request during issuance. A Credential Provider can only use one template. If you want to issue certificates based on different templates, create a Credential Provider configuration for each of them.
  • If you opt for using a GPKI entity for your Credential Provider, your choice of issuing method will depend on which capabilities are supported by the adapter. If the GPKI adapter defines user parameters for the selected capability, you will be presented with an interface to specify values for each of those. The parameters are specific to a capability; different capabilities have different sets of user parameters.
Note: For information on configuring Microsoft Certificate Services to work with Device Manager, see Configuring Device Manager with Microsoft Certificate Services
  1. In the Device Manager web console, click Options.
  2. In the Options dialog box, select PKI > Credential Provider.
  3. In the Define a new credential provider dialog box, on the General tab, enter the following information
    1. Credential Provider name. Type a unique name for the new provider configuration. This name will be used subsequently to refer to the configuration in other parts of the administration console.
    2. Description. An optional description for the configuration.
    3. Issuing method. The method that the system should obtain certificates from the configured entity. Select a Microsoft of GPKI entity.
  4. On the CSR tab (sign method only), you can configure the parameters for the key pair that will be created during issuance, as well as the parameters of the new certificate:
    1. Key algorithm. The key algorithm for the new key pair. Available values are RSA, DSA and ECDSA. Key size The size, in bits, of the key pair. Note that which values are permissible depends on the type of key (for instance, the maximum size for DSA keys is 1024 bits). To avoid false negatives (which will be dependent on the underlying hardware or software), Device Manager will not enforce key sizes. You should always test Credential Provider configurations in a test environment before activating them in production.
    2. Signature algorithm. The signature algorithm for the new certificate. Values are dependent on the key algorithm; in this case, Device Manager will limit your choices to matching values.
    3. Subject name. The Distinguished Name (DN) of the new certificate’s subject. The format the system expects is as described in [5]. Note that you can use Device Manager macros for the the DN field values. For example: CN=${user.username}, OU=${user.department}, O=${user.companyname}, C=${user.c}\endquotation
    4. Subject alternative. names X.509 subject alternative names. To create a new entry, click on “New alternative name”; then click on the first column to select the type of alternative name from those available; and finally enter a value in the second column. Note that as for the subject DN, you can use Device Manager macros in the value field.
  5. Next, click the Distribution tab. Here, you are required to specify the issuer CA of the certificates returned by the PKI entity in the configuration you have selected. You will be offered to choose one of the CA certificates defined on the entity. If the issuing method for this Credential Provider is sign, you will also be able to configure the delivery method, since the fetch method retrieves the key pair from the PKI server and hence there is no key generation involved at all, distributed key generation is not available with that method.
  6. Next, select the Revocation XenMobile tab. On this tab, you can configure the conditions and actions for the internal revocation of certificates. You can opt to have certificates revoked under the following conditions:
    1. When they are removed from the device, that is, either when the system detects that they have been removed from the device without server interaction, or when the server has removed them subsequent to the scheduling of a removal command.
    2. When they are updated on the device, that is, when they are replaced with a newer certificate for the same function.
    3. When the enrollment is revoked by the administrator.
    4. When the device is deleted.
    5. Or any combination of these.

    You can further opt to have a notification sent when the revocation action is undertaken; to do so, simply configure a notification template for the appropriate event type ('Certificate revoke').

    In addition to these conditions, since the certificates obtained through this configuration will have come from an external source, you can opt to propagate the revocation status externally (the common case would be to propagate it to the PKI that issued the certificates, but your choice is not restricted in that matter). The propagation is achieved using a GPKI entity with the revoke capability; the interface will propose you the list of revoke-capable GPKI entities that exist in the system. If the selected entity defines user-parameters for the revoke operation, you will be prompted to enter values for them. You can use Device Manager macros for the values.

  7. Next, select the Revocation PKI tab.

    In this tab, you can configure the system to perform external certificate status checks for certificates issued through this CredentialProvider configuration. The checks are performed using the OCSP protocol [1] and take place when a deployment is initiated. For the checks to occur, the back-end PKI must insert corresponding OCSP responder address extensions (ASN.1 OID: 1.3.6.1.5.5.7.1.1) in the certificates it issues. If that is not the case, the setting will be silently ignored

    As part of the OCSP protocol, the initiator of the OCSP request (in this case, XenMobile) must be able to validate the OCSP responder’s (likely your PKI server) signing certificate. To that effect, as part of the external revocation check configuration, you must specify the CA certificate of your PKI’s OCSP Responder’s signing certificate. The CA certificate must be uploaded to the Server Certificates repository so that you can select it in the drop down. Its private key is not required for this purpose.

    Note that OCSP Responder certificates are usually either the CA certificate itself (that is, the CA that signed the certificate the status of which is queried), or a certificate signed directly by that CA. It that sense, specifying that CA certificate in this section will usually be adequate.

    You can further define what actions XenMobile should undertake in the event that the OCSP verification yields a status indicating that the certificate in question was revoked. If that is the case, you can opt to:

    • Do nothing.
    • Remove the corresponding configuration from the device, that is, the configuration the certificate in question was deployed as part of.
    • Revoke the enrollment and wipe the device.

    In addition to the action you opt for, you can choose to have a notification sent in that case, by selecting a notification template for the appropriate event type (Certificate revoked by PKI). The external revocation and the internal revocation configured in the tab before are complementary, in the sense that if the external revocation check yields a revoked status and you have opted, for instance, to revoke the entire enrollment in that case, then the settings you have specified in the Revocation XenMobile tab will apply to all other certificates present on the device. The same thing goes for all certificates that were part of the same configuration if you have merely chosen to remove the configuration the certificate was deployed as a part of.

  8. Next, select the Renewal tab.
    On this tab, you can configure the renewal of certificates obtained through this configuration. Two basic operations can be configured:
    • Renewing the certificate, optionally sending a notification when this is done (notification on renewal), and optionally excluding already expired certificates from the operation. Note that 'already expired' in this case means that their NotAfter date is in the past; not that they already have been revoked. XenMobile will not renew certificates once they have been internally revoked.
    • Issuing a notification for certificates that near expiration (notification before renewal).

    To have notifications sent for either case, simply specify a Notification Template for the appropriate event type. The event type for the former is Certificate is renewed; for the latter, Certificate will expire. XenMobile will create default Notification Templates for both these event types, but you can modify them or create new ones.

    It is important to note that renewal takes precedence over notification before renewal. That is, if at a given moment XenMobile determines that a certificate must be renewed, it will not also send a notification before renewal (instead, the notification on renewal, if any configured, will be used). You should configure a greater period for the notification before renewal if you imperatively need both to be sent. Notifications before renewal will only be sent at most once for a given certificate.

  9. Click Create.