Product Documentation

Credential Providers

May 07, 2015

Credential Providers are the actual configurations you will use in the various parts of the XenMobile system. They define the sources, parameters, and life-cycles of your certificates, whether these are part of device configurations or stand-alone, that is pushed as is, to the device.

Figure 1. Certificates Lifecycle


The certificates’ life-cycle is constrained by the device enrollment. That is, no certificates are issued before enrollment, although some may indeed be issued as part of enrollment, and all certificates issued within the context of one enrollment are revoked when the enrollment is revoked; that is, no certificate remains valid after the management relationship. the enrollment, has been terminated.

One Credential Provider configuration may be used in multiple places, to the effect that configuration may govern any number of certificates at the same time. The unicity, then, is on the deployment resource and the deployment: if the Credential Provider P is “deployed” to device D as part of the configuration C, then P’s issuance settings will determine the certificate that is deployed to D, its renewal settings will apply when C is updated, and its revocation settings will apply when C is deleted or D is revoked.

With the aforementioned in mind, the Credential Provider configuration:
  • Determines the source of certificates — that is, which PKI Entity certificates will be obtained from
  • Determines the method using which certificates are obtained — signing a new certificate or fetching (recovering) an existing certificate and key pair
  • Determines the parameters for the issuance or recovery (for example, CSR parameters such as key size, key algorithm, distinguished name, certificate extensions, and so on)
  • Determines the manner in which certificates are delivered to the device
  • Determines revocation conditions. While all certificates are revoked when the management relationship is severed, the configuration may specify an earlier revocation, for instance when the associated device configuration is deleted. In addition, under some conditions the revocation of the associated certificate in XenMobile may be sent to the back-end PKI; that is, its revocation in XenMobile may cause its revocation on the PKI
  • Determines renewal settings. Certificates obtained through a given Credential Provider may be automatically renewed when they near expiration, or, separately from that, notifications may be issued when that expiration approaches.

To what extent various configuration options are available will mainly depend on which type of PKI Entity and issuance method are selected for a Credential Provider.

Methods of Certificate Issuance

There are two fundamental methods of obtaining a certificate, which in this context shall be called methods of issuance:
  • SIGN. With this method, the 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.
  • FETCH. With this method, the issuance (from the point of view of XenMobile) is in actuality a recovery of an existing certificate and key pair.

A Credential Provider uses exactly one of these methods; which method is selected impacts which configuration options are available. Notably, CSR configuration and distributed delivery are only available if the issuing method is sign. If the certificate is fetched, it is always sent as a pkcs#12 to the device (equivalent to centralized delivery mode for the sign method).

Which issuing methods are available for a Credential Provider will depend on the capabilities the PKI Entity it uses supports.

Certificate Delivery

An important notion is the delivery mode of certificates. The delivery is independent of the issuance, although it only applies when the issuing mode is newly issued [sign], not recovered [fetch] from the PKI).

Two modes of certificate delivery are available: centralized and distributed. Distributed mode uses the SCEP protocol and is only available in situations where the client supports the protocol, and is even mandatory in some situations.

For a Credential Provider to support distributed (SCEP-assisted) delivery, a special configuration step is necessary: setting up Registration Authority (RA) certificates. Those are required because when using the SCEP protocol, XenMobile acts like a delegate (a registrar) to the actual CA, and must prove to the client that it has the authority to act as such. That authority is established by providing XenMobile with the aforementioned certificates.

Two distinct certificate roles are required (although one and the same certificate can fulfill both): RA signature and RA encryption. The constraints for these roles are as follows:
  • The RA signing certificate must have the X.509 key usage digital signature.
  • The RA encryption certificate must have the X.509 key usage key encipherment

To configure the Credential Provider’s RA certificates, you must first upload them to the Server Certificates repository, and then link to them in the Credential Provider.

A Credential Provider is considered to support distributed delivery if, and only if, it has a certificate configured for each of the aforementioned roles. Each Credential Provider can be configured to either prefer centralized mode, to prefer distributed mode, or to require distributed mode. The actual result will depend on the context: if the context does not support distributed mode, but the Credential Provider requires it, deployment will fail. Likewise, if the context mandates distributed mode, but the Credential Provider does not support it, deployment will fail. In all other cases, the preferred setting will be honored.

Table 1. SCEP Distribution Availability
Context SCEP supported SCEP required
iOS Profile Service yes yes
iOS MDM enrollment yes no
iOS configuration profiles yes no
SHTP    enrollment no no
SHTP configuration no no
Windows Phone enrollment no no
Windows Phone configuration no no

Certificate Revocation

There are three separate aspects to a certificate’s revocation, three types of revocation: internal revocation, externally propagated revocation and externally induced revocation.
  • Internal revocation Internal revocation affects the certificate’s status as maintained by XenMobile (in its database). This status is taken into account when XenMobile evaluates a certificate presented to it, or when it has to provide OCSP status information for some certificate). The Credential Provider configuration determines how this status is affected under various conditions. For instance, the Credential Provider may specify that certificates obtained through it should be (flagged as) revoked when they have been deleted from the device.
  • Externally propagated revocation Also known as “Revocation from XenMobile”, this type of revocation applies to certificates obtained from an external PKI, and means that the certificate will be revoked on the PKI when it is internally revoked by XenMobile (under the conditions defined by the Credential Provider configuration). The call to perform the revocation requires a revoke-capable GPKI Entity.
  • Externally induced revocation Also known as “Revocation from PKI”, this type of revocation also only applies to certificates obtained from an external PKI, and means that whenever XenMobile evaluates a given certificate’s status, it will query the PKI as to that status, and, if the PKI returns that the certificate is revoked, will internally revoke it. This mechanism uses the OCSP protocol.

These three types are not exclusive, but rather apply together: the internal revocation is caused either by an external revocation or by independent findings, and in turn it potentially effects an external revocation.

Certificate Renewal

A certificate renewal is the combination of a revocation (of the existing certificate) and an issuance (of another certificate).

Note that XenMobile will first attempt to obtain the new certificate before revoking the previous one, in order to avoid discontinuation of service if the issuance fails. If distributed (SCEP-supported) delivery is used, the revocation will also only happen once the certificate has been successfully installed on the device; otherwise, the revocation will occur before the new certificate is sent to the device and independently of the success or failure of its installation.

The revocation configuration requires that you specify a certain duration (in days); when the device connects, the server verifies whether the certificate’s NotAfter date is later than the current date minus the specified duration. If it is, a renewal is attempted.

To create a credential provider using discretionary CA entities

Configuring a Credential Provider varies mostly as a factor of which issuing entity and which issuing method are selected for it. You can distinguish between Credential Provider using an internal entity, such discretionary, and those using an external entity, such as Microsoft CA or GPKI.

This task shows you how to create a discretionary entity. The issuing method for a discretionary entity is always sign, meaning that with each issuing operation, Device Manager will sign a new key pair with the CA certificate selected for the entity whether the key pair is generated on the device or on the server will depend on the selected distribution method.

  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 discretionary entity.
  4. On the CSR tab, you configure the parameters for the key pair that will be created during issuance, as well as the parameters of the new certificate. Enter the following information:
    1. Key algorithm. The key algorithm for the new key pair. Available values are RSA, DSA and ECDSA.
    2. 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 and software), Device Manager will not enforce key sizes. You should always test Credential Provider configurations in a test environment before activating them in production.
    3. 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.
    4. Subject name. The Distinguished Name (DN) of the new certificate’s subject. For example: CN=${user.username}, OU=${user.department}, O=${user.companyname}, C=${user.c}\endquotation
    5. Subject alternative names. X.509 subject alternative names. To create a new entry, click on New alternative name and then click on the first column to select the type of alternative name from those available. Last, 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 on the Distribution tab. Because the Credential Provider uses a Discretionary CA Entity, the CA certificate for the Credential Provider will always be the CA certificate configured on the entity itself; it will be presented here for mere consistency with configurations that use external entities.

    The second element on this tab is the configuration of certificate delivery. If you have defined RA certificates at the entity level, they will be filled by default here, but you can change them if you desire (but that the constraints on RA certificates still apply).

    You can then select the delivery mode for certificates obtained from this entity. If you select the Prefer centralized delivery mode, RA certificates are optional; otherwise, they’re mandatory.

  6. Next, click on the Revocation tab. In this tab, you can configure under what conditions Devce Manager should (internally) flag certificates issued through this provider configuration as revoked. You can also instruct the system to send a notification when it flags a certificate as revoked. Do this by selecting a template for the event type Certificate revoke. Device Manager will create a default template for that type, but you can edit it or create others).Note that the revocation configured here will be what determines the responses from the Device Manager OCSP Responder for certificates created with this configuration, if OCSP support is enabled for the PKI Entity.
  7. Next, click on the Renewal tab. In this tab, you can configure the renewal of certificates obtained through this configuration. Two basic operations can be configured:
    1. 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. Device Manager will not renew certificates once they have been internally revoked.
    2. 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. Device Manager will create default Notification Templates for both these event types, but you can modify them or create new ones.

      Note that renewal takes precedence over notification before renewal. That is, if at a given moment Device Manager 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.

  8. Click Create.

To create a credential provider using external PKI entities

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.