Citrix Endpoint Management

Upload, update, and renew certificates

We recommend that you list the certificates needed for your 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:

  • Endpoint Management server
    • SSL Certificate for MDM FQDN (needed if you migrated from XenMobile Server to 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 Service or MDX Toolkit
    • Apple Developer Certificate
    • Apple Provisioning Profile (per application)
    • Apple APNs Certificate (for use with Citrix Secure Mail)
    • Android Keystore File
    • Windows Phone – DigiCert Certificate

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

  • Citrix 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

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 Endpoint Management to integrate with your Microsoft certificate authority (CA). The connection to the Microsoft CA must be authenticated by using a client certificate.

Endpoint Management might not possess the private key for a given certificate. Likewise, 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.
  • Perform 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 Endpoint Management has the private key.

To import a keystore

A keystore is a repository of security certificates. By design, keystores can contain multiple 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 contain only one entry, the alias field doesn’t appear when you select PKCS #12 as the keystore type.

  1. In the 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: In the list, click PKCS #12.
    • 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 Endpoint Management. You upload server certificates to the Endpoint Management web console. Those certificates include CA certificates, RA certificates, and certificates for client authentication with other components of your infrastructure. In addition, 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 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, Endpoint Management attempts to construct a certificate chain from the input. 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 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 Endpoint Management. You upload server certificates to the Endpoint Management web console. Those certificates include CA certificates, RA certificates, and certificates for client authentication with other components of your infrastructure. In addition, 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 Endpoint Management of SSL cryptographic activity.
    • Certificate impoort: 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, perform 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 tha 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#
    
  3. Pack all certificates and the text file you created into a .zip file.
  4. Launch your REST API client, log in to Endpoint Management, and get an authentication token.
  5. Import your certificates, ensuring 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
    }
    

    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 files 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 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"
}
```

REST API client

Update a certificate

Endpoint Management only allows one certificate per public key to exist in the system at a time. If you attempt 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 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, perform the steps to create a certificate, then go to the Apple Push Certificates Portal. For more information, see Renew an APNs certificate.

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

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 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 Endpoint Management resources. The Certification Authority (CA) prompts you to renew your SSL certificate before the expiration date. Perform the steps described previously to update the certificate, and then initiate a certificate renewal on enrolled devices.

For supported iOS, macOS, and Android devices, you can initiate certificate renewal through the security action, Certificate Renewal. You renew device certificates from the 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 Endpoint Management, the 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. 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

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 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. 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 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 Endpoint Management, set up and create an APNs certificate from Apple. If the certificate expires, users cannot enroll in 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

MDX Service or 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 Endpoint Management server certificates are valid, do the following:

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

Android keystore

The keystore is a file that contains 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.

Enterprise certificate from DigiCert for Windows phones

DigiCert is the exclusive provider of code signing certificates for the Microsoft App Hub service. Developers and software publishers join the App Hub to distribute Windows Phone and Xbox 360 applications for download through the Windows Marketplace. For details, see DigiCert Code Signing Certificates for Windows Phone in the DigiCert documentation.

If the certificate expires, Windows phone users cannot enroll. The users can’t install an app published and signed by the company, or start an installed company app.

Citrix Gateway

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

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

The Expiry Monitor and Command Center can help you to track your Citrix Gateway certificates. The Center notifies you when the certificate expires. These tools assist to monitor the following Citrix 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