Derived credentials

Derived credentials provide strong authentication for mobile devices. The credentials, derived from a smart card, reside in a mobile device instead of the card. The smart card is a Personal Identity Verification (PIV) card.

The derived credentials are an enrollment certificate that contains the user identifier, such as UPN. Endpoint Management saves the credentials obtained from the credential provider in a secure vault on the device.

Endpoint Management can use derived credentials for device enrollment and authentication. If configured for derived credentials, Endpoint Management doesn’t support enrollment invitations or other enrollment modes. Citrix supports use of a derived credentials app during enrollment of iOS.

Architecture

For enrollment, Endpoint Management connects to the components, as shown in the following diagram.

Derived credentials enrollment architecture

  • During device enrollment, Secure Hub obtains certificates from the derived credentials app.
  • The derived credentials app communicates with the credential management server during enrollment.
  • You can use the same or different server for the credential management server and a third-party PKI provider.
  • Endpoint Management connects to your third-party PKI server to obtain certificates.

Requirements

  • Download and install Citrix Secure Hub.
  • Based on your derived credential solution, download and configure the app:

    • For Entrust Datacard:
      • Download and install the Citrix Derived Credential Manager app on your devices before enrolling in Endpoint Management. The Derived Credentials Manager app is the identity provider app for Citrix. The logo for that app follows. Derived credentials app logo

        Note:

        Citrix Derived Credential Manager app supports new enrollments only. Device users must re-enroll.

      • Endpoint Management must be configured for MDM+MAM mode.
    • For other derived credentials providers: While it’s likely that most other credential solutions are compatible with XenMobile, test the integration before deploying it to production.
  • Must have the root certificate of the authority that issues certificates to the Credentials Provider server. That setup enables Endpoint Management to accept the digitally signed certificates during enrollment. For information about adding the certificates, see Certificates and authentication.
    • If the user email domain differs from the LDAP domain, include the email domain in the Domain alias setting in Settings > LDAP. For example, if the domain for email addresses is citrix.com and the LDAP domain name is sample.com, set Domain alias to sample.com, citrix.com.
    • Endpoint Management doesn’t support the use of derived credentials with shared devices.
  • User identity certificates:
    • The user name in the Subject alternative name field must be formatted as the otherName, rfc822Name, or dNSName field of the SubjectAltName extension. Other fields are not supported. For more information about Subject alternative name, see the RFC, https://www.ietf.org/rfc/rfc5280.txt.
    • User identity in the Subject field in either Email or CN isn’t supported.
  • Citrix Gateway configured for certificate authentication or certificate plus security token authentication

Enable derived credentials

By default, the Endpoint Management console doesn’t include the Settings > Derived Credentials page.

To enable the interface for derived credentials:

  • Go to Settings > Server Properties, add derived.credentials.enable as the server property, and set the property value to true.

Server Properties configuration screen

Configure derived credentials

The assumption is that you have a working configuration for the derived credentials provider that you plan to integrate with Endpoint Management. You can configure Endpoint Management to communicate with that server. You can also choose a derived credentials CA certificate already added to Endpoint Management or import the certificate.

You can activate Online Certificate Status Protocol (OCSP) support for that CA certificate. For more information about OCSP, see “Discretionary CAs” in PKI entities.

  1. In the Endpoint Management console, go to Settings > Derived Credentials for iOS.

  2. For Choose derived credentials provider, choose Other for Entrust Datacard. Type dcapp://mode=SecureHub in the App URL (iOS).

    Derived Credentials configuration screen

  3. Optional parameters: Some derived credential providers might require that you provide parameters for the connection. For example, a vendor might require that you specify the URLs of a back-end server. Click Add to provide parameters.

  4. Specify a certificate for derived credentials: If the certificate is already uploaded to Endpoint Management, choose that certificate from Issuer CA. Otherwise, click Import to add a certificate. The Import Certificate dialog box appears.

  5. In the Import Certificate dialog box, click Browse to navigate to the certificate. Then click Browse to navigate to the private key file.

    Derived Credentials configuration screen

  6. Configure the settings.
    • For Citrix Derived Credential Manager app: The User Identifier field is Subject alternative name, and the User Identifier type is userPrincipalName.
    • Contact other derived credential providers for their information.
  7. You can optionally use an OCSP responder for certificate revocation checking. Citrix recommends using an OCSP responder for security purposes. By default, OSP checking is Off.

    • If you activate OCSP support for the CA certificate, choose an option for Use custom OCSP URL. By default, Endpoint Management extracts the OCSP URL from the certificate (the Use certificate definition for revocation option). To specify a responder URL, click Use custom and then type the URL.
    • Responder CA: From Responder CA, choose a certificate. Or, click Import and then use the Import Certificate dialog box to locate the certificate.
  8. Click Save. The Enabling Derived Credentials dialog box appears.

    Derived Credentials configuration screen

    • To enable the derived credentials configuration, click Save. To use derived credentials, you must also configure enrollment settings.

    • To enable the derived credentials configuration and then go immediately to Settings > Enrollment, click Save and Go to Enrollment.

  9. To enable derived credentials for enrollment: On the Settings > Enrollment page, under Advanced Enrollment, select Derived Credentials (iOS only) and then click Enable.

    Enrollment configuration screen

  10. A confirmation dialog box appears. To enable derived credentials, select the check box, and click Enable.

    Enrollment configuration screen

  11. To edit options for derived credentials enrollment, go to Settings > Enrollment, select Derived Credentials (iOS only) and then click Edit.

After you enable derived credentials: In the Devices Enrollment report, the column Enrollment mode shows derived_credentials.

Configure Endpoint Management for Secure Mail

To enable Secure Mail to work with derived credentials, add the LDAP Attributes client property. For information about adding a client property, see Client properties.

Use the following information for the client property:

  • Key: SEND_LDAP_ATTRIBUTES
  • Value: userPrincipalName=${user.userprincipalname},sAMAccountNAme=${user.samaccountname},displayName=${user.displayName},mail=${user.mail}

Client Properties configuration screen

Activating Entrust Datacard derived credentials on iOS devices

Note:

While using Entrust website:

  • Ensure that the Internet Explorer browser is Java-enabled, when you program the PIV card.
  • Clear the browser cache when changing the PIV card.
  1. To request new smart credentials, use a desktop or any device to log in to the Entrust site. Log in using the Smart Credential Log In button at the bottom of the page. Users insert their smart card into a reader attached to their desktop.

    Entrust login page

  2. From the Self-Administration Actions, select the I’d like to enroll for a derived mobile smart credential and click Done.

    Entrust admin actions

  3. In the Derived Mobile Smart Credential screen, provide the Identity Name. The user can choose a unique name such as a user name or ID numbers.
  4. Select the Citrix DCAPP from the Derived credential app menu, and click Ok.

    Derived mobile smart credentials

    A QR code Activation screen appears and prompts the user to scan the code with their mobile device.

    Note:

    By default, the derived credentials QR code expires in 3 minutes.

  5. Scan the QR code using the Derived Credential Manager app on the device to complete the activation.

    Derived mobile smart credentials QR code activation

Device enrollment

After you complete the setup described earlier in this article, users can enroll their devices by using derived credentials.

Note:

Screenshots in this section use Entrust Datacard as an example.

  1. Tap to open Secure Hub. When prompted, type the Endpoint Management server fully qualified domain name and then click Next.
  2. Click Yes, Enroll. Device enrollment in Secure Hub starts.

    Secure Hub enrolling

    If Endpoint Management is configured for derived credentials, Secure Hub prompts the user to create and confirm the Citrix PIN.

    Secure Hub PIN confirmation

    After confirming the Citrix PIN the Derived Credentials setup splash screen appears. Follow the instructions to activate smart credentials.

  3. Tap Scan code. The mobile phone camera activates.

    Splash screen

    Note:

    To scan the QR code, ensure your camera and microphone is enabled and has required access permissions.

  4. In the derived credentials app, scan the QR code that was created in earlier steps.

    Scanning QR code

  5. After scanning the QR code, on the Import New Certificate screen a password dialog box appears, enter the password and click OK.

    Certificate password

    Import New Certificate screen appears with fields auto-populated.

    New certificate

  6. After the certificates are added successfully, in the Derived Credentials screen, click Start Enrollment.

    Start enrollment

  7. In Secure Hub, enter a new PIN when prompted.

    After authenticating the PIN, Secure Hub downloads the certificates. Follow the prompts to complete the enrollment.

To view device information in the Endpoint Management console:

  • Go to Manage > Devices and then select a device to display a command box. Click Show more.
  • Go to Analyze > Dashboard.