Product Documentation

Credential providers

Credential providers are the actual certificate configurations you use in the various parts of the XenMobile system. Credential providers define the sources, parameters, and life cycles of your certificates. Those operations occur 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: 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.

According to those rules, the credential provider configuration in XenMobile determines the following:

  • The source of certificates.
  • The method in which certificates are obtained: Signing a new certificate or fetching (recovering) an existing certificate and key pair.
  • The parameters for issuance or recovery. For example, Certificate Signing Request (CSR) parameters, such as key size, key algorithm, and certificate extensions.
  • The manner in which certificates are delivered to the device.
  • Revocation conditions. Although all certificates are revoked in XenMobile when the management relationship is severed, the configuration may specify an earlier revocation. For instance, the configuration can specify to revoke a certificate 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, certificate revocation in XenMobile may cause certificate revocation on the PKI.
  • Renewal settings. Certificates obtained through a given credential provider can automatically renew when they near expiration. Or, separately from that situation, notifications can be issued when that expiration approaches.

The availability of configuration options 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 known 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 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 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, if you use the SCEP protocol, XenMobile acts like a delegate (a registrar) to the actual certificate authority. XenMobile must prove to the client that it has the authority to act as such. That authority is established by uploading the previously mentioned certificates to XenMobile.

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 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. You can configure each credential provider 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 requires 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 and Tablet enrollment No No
Windows Phone and Tablet configuration No, except for the Wifi device policy, which is supported for Windows Phone 8.1 and the latest Windows 10 release No

Certificate Revocation

There are three types of revocation.

  • Internal revocation: Internal revocation affects the certificate status as maintained by XenMobile. XenMobile considers this status when evaluatating a presented certificate, or when providing OCSP status information for a certificate. The credential provider configuration determines how this status is affected under various conditions. For instance, the credential provider might specify to flag certificates as revoked when the certificates are 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 XenMobile internally revokes the certificate, 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. An external revocation or independent finding can cause an internal revocation. An internal revocation potentially affects an external revocation.

Certificate Renewal

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

XenMobile first attempts to obtain the new certificate before revoking the previous certificate, to avoid discontinuation of service when issuance fails. For distributed (SCEP-supported) delivery, 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. That revocation is independent of the success or failure of certificate 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 the certificate meets that condition, XenMobile attempts to renew the certificate.

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 credential providers that use an internal entity or an external entity:

  • A discretionary entity, which is internal to XenMobile, is an internal entity. The issuing method for a discretionary entity is always sign. Sign means 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.

  • An external entity, which is part of your corporate infrastructure, includes Microsoft CA or a GPKI.

For detailed information about setting up Symantec Managed PKI, including creating the credential provider, see “Symantec Managed PKI” in PKI entities.

  1. In the XenMobile console, click the gear icon in the upper-right corner and then click Settings > Credential Providers.

  2. On the Credential Providers page, click Add.

    The Credential Providers: General Information page appears.

  3. On the Credential Providers: General Information page, do the following:

    • Name: Type a unique name for the new provider configuration. This name is used later to identify the configuration in other parts of the XenMobile console.
    • Description: Describe the credential provider. Although this field is optional, a description can provide useful details about this credential provider.
    • Issuing entity: Click the certificate issuing entity.
    • Issuing method: Click Sign or Fetch to serve as the method that the system uses to obtain certificates from the configured entity. For client certificate authentication, use Sign.
    • If the Template list is available, select the template that you added under the PKI entity for the credential provider.

      These templates become available when Microsoft Certificate Services Entities are added at Settings > PKI Entities.

  4. Click Next.

    The Credential Providers: Certificate Signing Request page appears.

  5. On the Credential Providers: Certificate Signing Request page, configure the following according to your certificate configuration:

    • Key algorithm: Choose the key algorithm for the new key pair. Available values are RSA, DSA, and ECDSA.

    • Key size: Type the size, in bits, of the key pair. This field is required.

      The permissible values depend on the key type. For example, the maximum size for DSA keys is 1024 bits. To avoid false negatives, which depends on the underlying hardware and software, XenMobile doesn’t enforce key sizes. Always test credential provider configurations in a test environment before activating them in production.

    • Signature algorithm: Click a value for the new certificate. Values depend on the key algorithm.

    • Subject name: Required. 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

      For example, for client certificate authentication, use these settings:

      • Key algorithm: RSA
      • Key size: 2048
      • Signature algorithm: SHA1withRSA
      • Subject name: cn=$user.username
    • To add an entry to the Subject alternative names table, click Add. Select the type of alternative name and then type a value in the second column.

      For client certificate authentication, specify:

      • Type: User Principal name
      • Value: $user.userprincipalname

        As with Subject name, you can use XenMobile macros in the value field.

  6. Click Next.

    The Credential Providers: Distribution page appears.

  7. On the Credential Providers: Distribution page, do the following:

    • 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 the CA certificate configured on the entity itself. The CA certificate is presented here for consistency with configurations that use external entities.
    • 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 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. New fields appear for these certificates.

  8. 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.

  9. On the Credential Providers: Revocation XenMobile page, do the following:

    • In Revoke issued certificates, select one of the options indicating when to revoke certificates.
    • To direct XenMobile to send a notification when the certificate is revoked: Set the value of Send notification to On and choose a notification template.

    • To revoke the certificate on PKI when the certificate is revoked from XenMobile: Set Revoke certificate on PKI to On and, in the Entity list, click a template. The Entity list shows all 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.
  10. 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.

  11. On the Credential Providers: Revocation PKI page, do the following if you want to revoke certificates from the PKI:

    • Change the setting of Enable external revocation checks to On. More fields related to revocation PKI appear.
    • In the OCSP responder CA certificate list, click the distinguished name (DN) of the certificate’s subject.

      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

    • 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.
    • To direct 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.
  12. Click Next.

    The Credential Providers: Renewal page appears. On this page, you can configure XenMobile to do the following:

    • Renew the certificate. You can optionally send a notification notification on renewal, and optionally exclude already expired certificates from the operation.
    • Issue a notification for certificates that near expiration (notification before renewal).
  13. On the Credential Providers: Renewal page, do the following if you want to renew certificates when they expire:

    Set Renew certificates when they expire to On. More fields appear.

    • In the Renew when the certificate comes within field, type how many days before expiration to renew the certificate.
    • Optionally, select Do not renew certificates that have already expired. In this case, “already expired” means that the NotAfter date is in the past, not that it has been revoked. XenMobile doesn’t renew certificates after they are internally revoked.

    To direct XenMobile to send a notification when the certificate has been renewed: Set Send notification to On. To direct XenMobile to send a notification when the certification nears expiration: Set Notify when certificate nears expiration to On. For either of those choices, you can choose between two notification options:

    • Select notification template: Select a pre-written notification message which you can then customize. These templates are in the Notification template list.
    • Enter notification details: Write your own notification message. Provide the recipient’s email address, a message, and a frequency for sending the notification.

    In the Notify when the certificate comes within field, type how many days before the certificate’s expiration to send the notification.

  14. Click Save.

    The credential provider appears in the Credential Provider table.