Product documentation
Citrix Endpoint Management
View PDF

Upload, update, and renew certificates

February 26, 2024
Contributed by: 
K C K

We recommend that you list the certificates needed for your Citrix Endpoint Management deployment. Use the list to track the certificate expiration dates and passwords. This article helps you administer certificates throughout their lifespan.

Your environment might include the following certificates:

  • Citrix Endpoint Management server
    • SSL Certificate for MDM FQDN (Needed if you migrated from XenMobile Server to Citrix Endpoint Management. Otherwise, Citrix manages this certificate.)
    • SAML Certificate (for Citrix Files)
    • Root and Intermediate CA Certificates for the preceding certificates and any other internal resources (StoreFront/Proxy, and so on)
    • APNs Certificate for iOS Device Management
    • PKI User Certificate for connectivity to PKI (required if your environment requires certificate-based authentication)
  • MDX Toolkit
    • Apple Developer Certificate
    • Apple Provisioning Profile (per application)
    • Apple APNs Certificate (for use with Citrix Secure Mail)
    • Android Keystore File

    The MAM SDK doesn’t wrap apps, so it doesn’t require a certificate.

  • NetScaler Gateway
    • SSL Certificate for MDM FQDN
    • SSL Certificate for Gateway FQDN
    • SSL Certificate for ShareFile SZC FQDN
    • SSL Certificate for Exchange Load Balancing (offload configuration)
    • SSL Certificate for StoreFront Load Balancing
    • Root and Intermediate CA Certificates for the preceding certificates

Note:

The client device must have the required root/intermediate certificate to establish trust with the certificate authority who issued the server certificate. Otherwise, you might receive SSL Error 61. To resolve the issue:

  1. Download or get the SSL root/intermediate certificate file (.crt or .cer) issued by your SSL certificate provider. Usually the root/intermediate/server certificate is present in the certificate bundle provided by your SSL service provider.
  2. Install the root/intermediate certificate on the client device.
  3. If an antivirus is installed on the client device, make sure the antivirus trusts the certificate.

Upload certificates

Each certificate you upload has an entry in the Certificates table, including a summary of its contents. When you configure PKI integration components that require a certificate, choose a server certificate to satisfy the criteria. For example, you might want to configure Citrix Endpoint Management to integrate with your Microsoft certificate authority (CA). The connection to the Microsoft CA must be authenticated by using a client certificate.

Citrix Endpoint Management might not have the private key for a given certificate. Likewise, Citrix Endpoint Management might not require a private key for uploaded certificates.

This section provides general procedures for uploading certificates. For details about creating, uploading, and configuring client certificates, see Client certificate or certificate plus domain authentication.

You have two options for uploading certificates:

  • Upload the certificates to the console individually.
  • Do a bulk upload of certificates using the REST API. This option is available for iOS devices only.

When uploading certificates to the console, you can:

  • Import a keystore. Then, you identify the entry in the keystore repository you want to install, unless you are uploading a PKCS #12 format.
  • Import a certificate.

You can upload the CA certificate (without the private key) that the CA uses to sign requests. You can also upload an SSL client certificate (with the private key) for client authentication.

When configuring the Microsoft CA entity, you specify the CA certificate. You select the CA certificate from a list of all server certificates that are CA certificates. Likewise, when configuring client authentication, you can select from a list of all the server certificates for which Citrix Endpoint Management has the private key.

To import a keystore

A keystore is a repository of security certificates. By design, keystores can have many entries. When loading from a keystore, you must specify the entry alias that identifies the entry you want to load. If you don’t specify an alias, the first entry from the store loads. Because PKCS #12 files usually have only one entry, the alias field doesn’t appear when you select PKCS #12 as the keystore type.

  1. In the Citrix Endpoint Management console, click the gear icon in the upper-right corner of the console. Use the search bar to find and open the Certificates setting.

    The Certificates configuration page

  2. Click Import. The Import dialog box appears.

  3. Configure these settings:

    • Import: Select Keystore.

    The Certificates configuration page

    • Keystore type: Click PKCS #12 in the drop-down list.
    • Use as: In the list, click how you plan to use the certificate. The available options are:
      • Server: Server certificates are certificates used functionally by Citrix Endpoint Management. You upload server certificates to the Citrix Endpoint Management web console. Those certificates include CA certificates, RA certificates, and certificates for client authentication with other components of your infrastructure. Also, you can use server certificates as storage for certificates you want to deploy to devices. This use especially applies to CAs used to establish trust on the device.
      • SAML: Security Assertion Markup Language (SAML) certification allows you to provide SSO access to servers, websites, and apps.
      • APNs: APNs certificates from Apple enable Mobile Device Management via the Apple Push Network.
      • SSL Listener: The Secure Sockets Layer (SSL) Listener notifies Citrix Endpoint Management of SSL cryptographic activity.
    • Keystore file: Browse to find the keystore you want to import. The keystore is a .p12 or .pfx file. Select the file and click Open.
    • Password: Type the password assigned to the certificate.
    • Description: Optionally, type a description for the keystore to help you distinguish it from your other keystores.

  4. Click Import. The keystore is added to the Certificates table.

To import a certificate

When importing a certificate, Citrix Endpoint Management tries to construct a certificate chain from the input. Citrix Endpoint Management imports all certificates in a chain to create a server certificate entry for each certificate. This operation only works if the certificates in the file or keystore entry do form a chain. Each subsequent certificate in the chain must be the issuer of the previous certificate.

You can add an optional description for the imported certificate. The description only attaches to the first certificate in the chain. You can update the description of the remaining certificates later.

  1. In the Citrix Endpoint Management console, click the gear icon in the upper-right corner of the console. Use the search bar to find and open the Certificates setting.

  2. On the Certificates page, click Import. The Import dialog box appears. Configure the following:

    • Import: click Certificate.
    • Use as: Select how you plan to use the certificate. The available options are:
      • Server: Server certificates are certificates used functionally by Citrix Endpoint Management. You upload server certificates to the Citrix Endpoint Management web console. Those certificates include CA certificates, RA certificates, and certificates for client authentication with other components of your infrastructure. Also, you can use server certificates as storage for certificates you want to deploy to devices. This option especially applies to CAs used to establish trust on the device.
      • SAML: Security Assertion Markup Language (SAML) certification allows you to provide single sign-on (SSO) access to servers, websites, and apps.
      • SSL Listener: The Secure Sockets Layer (SSL) Listener notifies Citrix Endpoint Management of SSL cryptographic activity.
    • Certificate import: Browse to find the certificate you want to import. Select the file and click Open.
    • Private key file: Browse to find an optional private key file for the certificate. The private key is used for encryption and decryption along with the certificate. Select the file and click Open.
    • Description: Type a description for the certificate, optionally, to help you identify it from your other certificates.

  3. Click Import. The certificate is added to the Certificates table.

Upload certificates in bulk using the REST API

Sometimes uploading certificates one at a time isn’t reasonable. In those cases, do a bulk upload of certificates using the REST API. This method supports certificates in the .p12 format. For more information about the REST API, see REST APIs.

  1. Rename each of the certificate files in the format device_identity_value.p12. The device_identity_value can be the IMEI, Serial Number, or MEID of each device.

    As an example, you choose to use serial numbers as your identification method. One device has a serial number A12BC3D4EFGH, so name the certificate file you expect to install on that device A12BC3D4EFGH.p12.

  2. Create a text file to store the passwords for the .p12 certificates. In that file, type the device identifier and password for each device on a new line. Use the format device_identity_value=password. See the following:

    A12BC3D4EFGH.p12=password1!
A12BC3D4EFIJ.p12=password2@
A12BC3D4EFKL.p12=password3#
<!--NeedCopy-->
  3. Pack all certificates and the text file that you created into a .zip file.
  4. Launch your REST API client, log in to Citrix Endpoint Management, and get an authentication token.

  5. Import your certificates and make sure that you put the following in the message body:

    {
    "alias": "",
    "useAs": "device",
    "uploadType": "keystore",
    "keystoreType": "PKCS12",
    "identityType":"SERIAL_NUMBER",        # identity type can be "SERIAL_NUMBER","IMEI","MEID"
    "credentialFileName":"credential.txt"   # The credential file name in .zip
}
<!--NeedCopy-->

    REST API client

  6. Create a VPN policy with the credential type Always on IKEv2 and the device authentication method Device Certificate Based on Device Identity. Select the Device identity type you used in your certificate file names. See VPN device policy.

  7. Enroll an iOS device and wait for the VPN policy to deploy. Confirm the certificate installation by checking the MDM configuration on the device. You can also check the device details in the Citrix Endpoint Management console.

    iOS MDM management

    Device details

You can also delete certificates in bulk by creating a text file with the device_identity_value listed for each certificate to delete. In the REST API, call the delete API and use the following request, replacing device_identity_value with the appropriate identifier:

```
{
    "identityType"="device_identity_value"
}
<!--NeedCopy--> ```

REST API client

Update a certificate

Citrix Endpoint Management only allows one certificate per public key to exist in the system at a time. If you try to import a certificate for the same key pair as an already imported certificate you can:

  • Replace the existing entry.
  • Delete the entry.

After you upload a new certificate to replace an old certificate, you can’t delete the old certificate. When you configure the PKI Entities setting, both certificates exist in the SSL client certificate menu. The newer certificate is lower in the list than the old certificate.

To update your certificates

  1. Create a replacement certificate by following the steps in Client certificate or certificate plus domain authentication.

    Important:

    Do not use the option to create a certificate with the existing private key. When you create a certificate to update an expiring certificate, the private key must be new as well.

  2. In the Citrix Endpoint Management console, click the gear icon in the upper-right corner of the console. Use the search bar to find and open the Certificates setting.
  3. In the Import dialog box, import the new certificate.

When you update a server certificate, components using the previous certificate automatically switch to using the new certificate. Likewise, if you have deployed the server certificate on devices, the certificate automatically updates on the next deployment.

To update an APNs certificate, do the steps to create a certificate, then go to the Apple Push Certificates Portal. For more information, see Renew an APNs certificate.

If your NetScaler Gateway is set up for SSL offload, make sure that you update your load balancer with the new cacert.pem.

Note:

If you have migrated from XenMobile on-prem to Citrix Endpoint Management, and you are updating your certificate, contact Citrix Support after completing the previous steps. You need to supply them with a copy of the new certificate (in PFX format), including the certificate password. Citrix Support updates the cloud NetScaler and reboot tenant nodes to finalize the certificate update process.

To update a PKI service certificate authority (CA)

You can request that Citrix Cloud Operations refresh or regenerate the internal PKI certificate authorities (CAs) in your Citrix Endpoint Management deployment. Open a Technical Support case for these requests.

When the new CAs are available, Cloud Operations lets you know that you can proceed with renewing the device certificates for your users.

Renew device certificates

If a certificate on a device expires, the certificate becomes invalid. You can no longer run secure transactions on your environment and you can’t access Citrix Endpoint Management resources. The Certification Authority (CA) prompts you to renew your SSL certificate before the expiration date. Do the steps described previously to update the certificate, and then start a certificate renewal on enrolled devices.

For supported iOS, macOS, and Android devices, you can start certificate renewal through the security action, Certificate Renewal. You renew device certificates from the Citrix Endpoint Management console or the Public REST API. For enrolled Windows devices, users must re-enroll their devices to receive a new device certificate authority (CA).

The next time that devices connect back to Citrix Endpoint Management, the Citrix Endpoint Management server issues new device certificates based on the new CA.

To renew device certificates by using the console

  1. Go to Manage > Devices and select the devices for which you want to renew device certificates.

  2. Click Secure and then click Certificate Renewal.

    Certificate Renewal in Security Actions

    Enrolled devices continue to work without disruption. Citrix Endpoint Management issues a device certificate when a device connects back to the server.

To query for the devices that are in a specific device certificate issuer CA group:

  1. In Manage > Devices, expand the Filters pane.

  2. In the Filters pane, expand Device Certificate Issuer CA and then select the issuer CAs that you want to renew.

    In the table of devices, the devices for the selected issuer CAs appear.

    Device list filtering by CA certificate group

To renew device certificates by using the REST API

Citrix Endpoint Management uses the following certificate authorities (CAs) internally for PKI: Root CA, device CA, and server CA. Those CAs are a logical group and have a group name. During Citrix Endpoint Management provisioning, the server generates three CAs and gives them the group name “default”.

The CA issues the following APIs to manage and renew the device certificates. Already enrolled devices continue to work without disruption. Citrix Endpoint Management issues a device certificate when a device connects back to the server. For more information, download the Public API for REST Services PDF.

  • Return a list of devices still using the old CA (see section 3.16.2 in the Public API for REST Services PDF)
  • Renew Device Certificate (see section 3.16.58)
  • Get all CA groups (see section 3.23.1)

APNs certificate for Citrix Secure Mail

Apple Push Notification Service (APNs) certificates expire every year. Be sure to create an APNs SSL certificate and update it in the Citrix portal before the certificate expires. If the certificate expires, users face inconsistency with Citrix Secure Mail push notifications. Also, you can no longer send push notifications for your apps.

APNs certificate for iOS device management

To enroll and manage iOS devices with Citrix Endpoint Management, set up and create an APNs certificate from Apple. If the certificate expires, users cannot enroll in Citrix Endpoint Management and you cannot manage their iOS devices. For details, see APNs certificates.

You can view the APNs certificate status and expiration date by logging on to the Apple Push Certificates Portal. Be sure to log on as the same user who created the certificate.

You also receive an email notification from Apple 30 and 10 days before the expiration date. The notification includes the following information:

The following Apple Push Notification Service certificate, created for Apple ID CustomerID will expire on Date. Revoking or allowing this certificate to expire will require existing devices to be re-enrolled with a new push certificate.

Please contact your vendor to generate a new request (a signed CSR), then visit https://identity.apple.com/pushcert to renew your Apple Push Notification Service certificate.

Thank You,

Apple Push Notification Service
<!--NeedCopy-->

MDX Toolkit (iOS distribution certificate)

An app that runs on a physical iOS device (other than apps in the Apple App Store) have these signing requirements:

  • Sign the app with a provisioning profile.
  • Sign the app with a corresponding distribution certificate.

To verify that you have a valid iOS distribution certificate, do the following:

  1. From the Apple Enterprise Developer portal, create an explicit App ID for each app you plan to wrap with MDX. An example of an acceptable App ID is: com.CompanyName.ProductName.
  2. From the Apple Enterprise Developer portal, go to Provisioning Profiles > Distribution and create an in-house provisioning profile. Repeat this step for each App ID created in the previous step.
  3. Download all provisioning profiles. For details, see Wrapping iOS Mobile Apps.

To confirm that all Citrix Endpoint Management server certificates are valid, do the following:

  1. In the Citrix Endpoint Management console, click Settings > Certificates.
  2. Check that all certificates including APNs, SSL Listener, Root, and Intermediate certificates are valid.

Android keystore

The keystore is a file that has certificates used to sign your Android app. When your key validity period expires, users can no longer seamlessly upgrade to new versions of your app.

NetScaler Gateway

For details on how to handle certificate expiration for NetScaler Gateway, see How to handle certificate expiry on NetScaler in the Citrix Support Knowledge Center.

An expired NetScaler Gateway certificate prevents users from enrolling and accessing the Store. The expired certificate also prevents users from connecting to Exchange Server when using Citrix Secure Mail. Also, users cannot enumerate and open HDX apps (depending on which certificate expired).

The Expiry Monitor and Command Center can help you to track your NetScaler Gateway certificates. The Center notifies you when the certificate expires. These tools assist to monitor the following NetScaler Gateway certificates:

  • SSL Certificate for MDM FQDN
  • SSL Certificate for Gateway FQDN
  • SSL Certificate for ShareFile SZC FQDN
  • SSL Certificate for Exchange Load Balancing (offload configuration)
  • SSL Certificate for StoreFront Load Balancing
  • Root and Intermediate CA Certificates for the preceding certificates
Upload, update, and renew certificates
February 26, 2024
Contributed by: 
K C K
February 26, 2024
Contributed by: 
K C K

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.