Citrix Endpoint Management

Credential providers

Credential providers are the actual certificate configurations that you use in the various parts of the Citrix Endpoint Management 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, Citrix Endpoint Management doesn’t issue certificates before enrollment, although Citrix Endpoint Management might issue some certificates as part of enrollment. Also, 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 stays.

You can use one credential provider configuration in many places, to the effect that one configuration can 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 Citrix Endpoint Management determines the following:

  • The source of certificates.
  • The method in which certificates are got: 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 Citrix Endpoint Management when the management relationship is severed, the configuration might specify an earlier revocation. For instance, the configuration can specify to revoke a certificate when the associated device configuration is deleted. Also, under some conditions, the revocation of the associated certificate in Citrix Endpoint Management might be sent to the back-end public key infrastructure (PKI). That is, certificate revocation in Citrix Endpoint Management might cause certificate revocation on the PKI.
  • Renewal settings: Certificates got 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.

Method of certificate issuance

You can get a certificate, which is known as the method of issuance, by signing.

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. Citrix Endpoint Management supports the sign method for both MS Certificate Services entities and Discretionary CA entities.

A credential provider uses the sign method of issuance.

Certificate Delivery

Two modes of certificate delivery are available in Citrix Endpoint Management: centralized and distributed. Distributed mode uses the 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, Citrix Endpoint Management acts like a delegate (a registrar) to the actual certificate authority. Citrix Endpoint Management 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 Citrix Endpoint Management.

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 Citrix Endpoint Management 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 Citrix Endpoint Management:

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 Tablet enrollment No No
Windows Tablet configuration No, except for the network device policy, which is supported for Windows 10 and Windows 11 releases No

Certificate Revocation

There are three types of revocation.

  • Internal revocation: Internal revocation affects the certificate status as maintained by Citrix Endpoint Management. Citrix Endpoint Management considers this status when evaluating 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 Citrix Endpoint Management, this type of revocation applies to certificates got from an external PKI. The certificate is revoked on the PKI when Citrix Endpoint Management internally revokes the certificate, under the conditions defined by the credential provider configuration.
  • Externally induced revocation: Also known as Revocation PKI, this type of revocation also only applies to certificates got from an external PKI. Whenever Citrix Endpoint Management evaluates a given certificate status, Citrix Endpoint Management queries the PKI as to that status. If the certificate is revoked, Citrix Endpoint Management 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.

Citrix Endpoint Management first tries to get 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, Citrix Endpoint Management tries 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 Citrix Endpoint Management, is an internal entity. The issuing method for a discretionary entity is always a sign. Sign means that with each issuing operation, Citrix Endpoint Management 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.

  1. In the Citrix Endpoint Management 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 Citrix Endpoint Management 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 get 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 2048 bits. To avoid false negatives, which depend on the underlying hardware and software, Citrix Endpoint Management 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: SHA256withRSA
      • 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 Citrix Endpoint Management 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 Citrix Endpoint Management 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 Citrix Endpoint Management page appears. On this page, you configure the conditions under which Citrix Endpoint Management internally flags certificates, issued through this provider configuration, as revoked.

  9. On the Credential Providers: Revocation Citrix Endpoint Management page, do the following:

    • In Revoke issued certificates, select one of the options indicating when to revoke certificates.
    • To direct Citrix Endpoint Management 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 Citrix Endpoint Management: Set Revoke certificate on PKI to On and, in the Entity list, click a template. The Entity list shows all available entities with revocation capabilities. When the certificate is revoked from Citrix Endpoint Management, 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 Citrix Endpoint Management 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 Citrix Endpoint Management 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 Citrix Endpoint Management to do the following:

    • Renew the certificate. You can optionally send a 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. Citrix Endpoint Management doesn’t renew certificates after they are internally revoked.

    To direct Citrix Endpoint Management to send a notification when the certificate has been renewed: Set Send notification to On. To direct Citrix Endpoint Management 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.

Credential providers