Product Documentation

Credential Providers

Mar 21, 2016

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

Device enrollment constrains the certificate life cycle. That is, XenMobile does not issue certificates before enrollment, although XenMobile may issue some certificates as part of enrollment. In addition, certificates issued from the internal PKI within the context of one enrollment are revoked when the enrollment is revoked. After the management relationship terminates, no valid certificate remains.

You may use one credential provider configuration in multiple places, to the effect that one configuration may govern any number of certificates at the same time. The unity, then, is on the deployment resource and the deployment. For example, if Credential Provider P is deployed to device D as part of configuration C, then the issuance settings for P determine the certificate that is deployed to D. Likewise, the renewal settings for D apply when C is updated, and the revocation settings for D also apply when C is deleted or when D is revoked.

With this in mind, the credential provider configuration in XenMobile does the following:

  • Determines the source of certificates.
  • Determines the method in which certificates are obtained: Signing a new certificate or fetching (recovering) an existing certificate and key pair.
  • Determines the parameters for issuance or recovery. For example, Certificate Signing Request (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. Although all certificates are revoked in XenMobile 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 public key infrastructure (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 situation, notifications may be issued when that expiration approaches.

To what extent various configuration options are available mainly depends on the type of PKI Entity and issuance method that you select for a credential provider.

Methods of Certificate Issuance

You can obtain a certificate, which is referred to as methods of issuance in two ways:

  • sign. With this method, the issuance involves creating a new private key, creating a CSR, and submitting the CSR to a Certificate Authority (CA) for signature. XenMobile supports the sign method for the three PKI entities (MS Certificate Services Entity, Generic PKI and Discretionary CA).
  • fetch. With this method, the issuance, for the purposes of XenMobile, is a recovery of an existing key pair. XenMobile supports the fetch method only for Generic PKI.

A credential provider uses either the sign or fetch method of issuance. The selected method affects the available configuration options. Notably, CSR configuration and distributed delivery are available only if the issuing method is sign. A fetched certificate is always sent to the device as a PKCS#12, the equivalent of centralized delivery mode for the sign method.

Certificate Delivery

Two modes of certificate delivery are available in XenMobile: centralized and distributed. Distributed mode uses Simple Certificate Enrollment Protocol (SCEP) and is only available in situations in which the client supports the protocol (iOS only). Distributed mode 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. The RA certificates 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 a single certificate can fulfill both requirements): 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 RA certificates, you must upload the certificates to XenMobile and then link to them in the credential provider.

A credential provider is considered to support distributed delivery only if the provider has a certificate configured for certificate roles. Each credential provider can be configured to either prefer centralized mode, to prefer distributed mode, or to require distributed mode. The actual result depends on the context: If the context does not support distributed mode, but the credential provider requires this mode, deployment fails. Likewise, if the context mandates distributed mode, but the credential provider does not support distributed mode, deployment fails. In all other cases, the preferred setting is honored.

The following table shows SCEP distribution throughout XenMobile:

Context SCEP supported SCEP required
iOS Profile Service Yes Yes
iOS mobile device management 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 types of revocation.

  • Internal revocation. Internal revocation affects the certificate status as maintained by XenMobile. This status is taken into account when XenMobile evaluates a certificate presented to it, or when XenMobile 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 the certificate provider should be flagged as revoked when the certificates have been deleted from the device.
  • Externally propagated revocation. Also known as Revocation XenMobile, this type of revocation applies to certificates obtained from an external PKI. The certificate is revoked on the PKI when the certificate is internally revoked by XenMobile, under the conditions defined by the credential provider configuration. The call to perform the revocation requires a revoke-capable General PKI (GPKI) entity.
  • Externally induced revocation. Also known as Revocation PKI, this type of revocation also only applies to certificates obtained from an external PKI. Whenever XenMobile evaluates a given certificate status, XenMobile queries the PKI as to that status. If the certificate is revoked, XenMobile internally revokes the certificate. 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 the internal revocation 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 first attempts to obtain the new certificate before revoking the previous certificate, in order to avoid discontinuation of service if the issuance fails. If distributed (SCEP-supported) delivery is used, the revocation also only happens after the certificate has been successfully installed on the device; otherwise, the revocation occurs 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 NotAfter date is later than the current date, minus the specified duration. If it is, a renewal is attempted.

To create a credential provider

Configuring a credential provider varies mostly as a factor of which issuing entity and which issuing method you select for the credential provider. You can distinguish between a credential provider using an internal entity, such as discretionary, and a credential provider using an external entity, such as Microsoft CA or GPKI. The issuing method for a discretionary entity is always sign, meaning that with each issuing operation, XenMobile signs 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 depends on the distribution method you select.

  1. In the XenMobile web console, click Configure > Settings > More > Credential Providers.
  2. On the Credential Providers page, click Add.

    The Credential Providers: General Information page appears.



  3. On the Credential Providers: General Infomation page, do the following:
    1. Name: Type a unique name for the new provider configuration. This name is used later to refer to the configuration in other parts of the XenMobile console.
    2. Description: Describe the credential provider. Although this is an optional field, a description can be useful in the future to help you remember details about this credential provider.
    3. Issuing entity: Click the certificate issuing entity.
    4. Issuing method: Click Sign or Fetch to serve as the method that the system uses to obtain certificates from the configured entity.
    5. If the template list is available, select a template for the credential provider.
      Note: These templates become available when Microsoft Certificate Services Entities are added at Configure > Settings > More > PKI Entities.
    6. Click Next.

      The Credential Providers: Certificate Signing Request page appears.



  4. On the Credential Providers: Certificate Signing Request page, do the following:
    1. Key algorithm: Click the key algorithm for the new key pair. Available values are RSA, DSA and ECDSA.
    2. Key size: Type the size, in bits, of the key pair. This is a required field.
      Note: The permissible values depend on the key type; for instance, the maximum size for DSA keys is 1024 bits. To avoid false negatives, which will depend on the underlying hardware and software, XenMobile does not enforce key sizes. You should always test credential provider configurations in a test environment before activating them in production.
    3. Signature algorithm: Click a value for the new certificate. Values are dependent on the key algorithm.
    4. Subject name: Type the Distinguished Name (DN) of the new certificate subject. For example: CN=${user.username}, OU=${user.department}, O=${user.companyname}, C=${user.c}\endquotation. This is a required field.
    5. To add a new entry to the Subject alternative names table, click Add. Select the type of alternative name and then type a value in the second column.
      Note: As with Subject name, you can use XenMobile macros in the value field.
    6. Click Next.

      The Credential Providers: Distribution page appears.

  5. On the Credential Providers: Distribution page, do the following:
    1. In the Issuing CA certificate list, click the offered CA certificate. Because the credential provider uses a discretionary CA entity, the CA certificate for the credential provider is always be the CA certificate configured on the entity itself; it will be presented here for consistency with configurations that use external entities.
    2. In Select distribution mode, click one of the following ways of generating and distributing keys:
      • Prefer centralized: Server-side key generation. Citrix recommends this centralized option. It supports all platforms supported by XenMobile and is required when using NetScaler Gateway authentication. The private keys are generated and stored on the server and distributed to user devices.
      • Prefer distributed: Device-side key generation. The private keys are generated and stored on the user devices. This distributed mode uses SCEP and requires an RA encryption certificate with the keyUsage keyEncryption and an RA signing certificate with the KeyUsage digitalSignature. The same certificate can be used for both encryption and signing.
      • Only distributed: Device-side key generation. This option works the same as Prefer distributed: Device-side key generation, except that since it is "Only," rather than "Prefer," no option is available if device-side key generation fails or is unavailable.

      If you select Prefer distributed: Device-side key generation or Only distributed: Device-side key generation, you must also select an RA signing certificate and an RA encryption certificate. New fields appear for these certificates.


       

    3. If you selected Prefer distributed: Device-side key generation or Only distributed: Device-side key generation, click the RA signing certificate and RA encryption certificate. The same certificate can be used for both.
    4. Click Next.

      The Credential Providers: Revocation XenMobile page appears. On this page, you configure the conditions under which XenMobile internally flags certificates, issued through this provider configuration, as revoked.

  6. On the Credential Providers: Revocation XenMobile page, do the following:
    1. In Revoke issued certificates, select one of the options indicating when certificates should be revoked.
    2. If you would like XenMobile to send a notification when the certificate is revoked, set the value of Send notification to On and choose a notification template.

       


       

    3. If you would like to revoke the certificate on PKI when the certificate has been revoked from XenMobile, set Revoke certificate on PKI to On and, in the Entity list, click a template. The Entity list shows all the available GPKI entities with revocation capabilities. When the certificate is revoked from XenMobile, a revocation call is sent to the PKI selected from the Entity list.

       


       

    4. Click Next.

      The Credential Providers: Revocation PKI page appears. On this page you identify what actions to take on the PKI if the certificate is revoked. You also have the option of creating a notification message.


       

  7. On the Credential Providers: Revocation PKI page, do the following if you want to revoke certificates from the PKI:
    1. Change the setting of Enable external revocation checks to On.

      Additional fields related to revocation PKI appear.

    2. In the OCSP responder CA certificate list, click the distinguished name (DN) of the certificate's subject.
      Note: You can use XenMobile macros for the DN field values. For example: CN=${user.username}, OU=${user.department}, O=${user.companyname}, C=${user.c}\endquotation
    3. In the When certificate is revoked list, click one of the following actions to take on the PKI entity when the certificate is revoked:
      • Do nothing.
      • Renew the certificate.
      • Revoke and wipe the device.
    4. If you would like XenMobile to send a notification when the certificate is revoked, set the value of Send notification to On.

      You can choose between two notification options:

      • If you select Select notification template, you can select a pre-written notification message which you can then customize. These templates are in the Notification template list.
      • If you select Enter notification details, you can write your own notification message. In addition to providing the recipient's email address and the message, you can set how often the notification is sent.
    5. Click Next.
      The Credential Providers: Renewal page appears. On this page, you can configure XenMobile to do the following:
      • Renew the certificate, optionally sending a notification when this is done (notification on renewal), and optionally excluding already expired certificates from the operation.
      • Issue a notification for certificates that near expiration (notification before renewal).
  8. On the Credential Providers: Renewal page, do the following if you want to renew certificates when they expire:
    1. Set Renew certificates when they expire to On.

      Additional fields appear.



    2. In the Renew when the certificate comes within field, type how many days prior to expiration the renewal should be made.
    3. Optionally, select Do not renew certificates that have already expired.
      Note: In this case, "already expired" means that the certificate's NotAfter date is in the past, not that it has been revoked. XenMobile will not renew certificates once they have been internally revoked.
    4. If you want XenMobile to send a notification when the certificate has been renewed, set Send notification to On.

      You can choose between two notification options:

      • If you select Select notification template, you can select a pre-written notification message which you can then customize. These templates are in the Notification template list.
      • If you select Enter notification details, you can write your own notification message. In addition to providing the recipient's email address and the message, you can set how often the notification is sent.
    5. If you want XenMobile to send a notification when the certification nears expiration, set Notify when certificate nears expiration to On.

      You can choose between two notification options:

      • If you select Select notification template, you can select a pre-written notification message which you can then customize. These templates are in the Notification template list.
      • If you select Enter notification details, you can write your own notification message. In addition to providing the recipient's email address and the message, you can set how often the notification is sent.
    6. In the Notify when the certificate comes within field, type how many days prior to the certificate's expiration the notification should be sent.
  9. Click Save.

    The credential provider is added to the Credential Provider table.