How to Configure Device Certificate on Citrix Gateway for Authentication

How to Configure Device Certificate on Citrix Gateway for Authentication

book

Article ID: CTX200290

calendar_today

Updated On:

Description

A device certificate verifies that a user device is allowed to connect to the internal network. NetScaler Gateway supports device certificates that enable you to bind the device identity to a public key.

Notes

  • You must install NetScaler Gateway 10.1, Build 120.1316.e or later or 10.5.e.x or 10.5.x to configure device certificates.

  • When users log on, you can require only the device certification as part of the authentication process. You can also require the device certificate when using pre-authentication or advanced endpoint analysis policies.

  • NetScaler Gateway needs to verify the device certificate before the endpoint analysis scan runs or before the logon page appears. If you configure endpoint analysis, the endpoint scan runs to verify the user device. When the device passes the scan and after NetScaler Gateway verifies the device certificate, users can then log on to the NetScaler Gateway.

  • If you install two or more device certificates on the client machines, users need to select the correct certificate when they start to log on to NetScaler Gateway or before the endpoint analysis scan runs.

  • When you create the device certificate, it must be an X.509 certificate.

  • If you have a device certificate issued by an intermediate CA, then both intermediate and root CA certificates need to be bound.

  • The EPA client needs the user to have local administrator rights to be able to access the machine certificate store. This is rarely the case, so a workaround is to install the full NetScaler Gateway plug-in which can access the local store.


Instructions

To configure Device Certificate, complete the following steps:

  1. Install the Device Certificate Issuer’s Certificate Authority Certificate on the NetScaler Gateway

  2. Bind the Device Certificate Issuer’s Certificate Authority Certificate to the NetScaler Gateway Virtual Server and Enable OCSP Check

  3. Create/Bind OCSP (Responder) on Device Certificate Issuer’s Certificate Authority Certificate

  4. Enable Device Certificate Check on the Virtual Server and Add Device Certificate Issuer’s Certificate Authority Certificate to the Device Certificate Checklist
  5. Client-Side Configuration and Verification of Device Certificate on Windows Machine

Note: All the Client intended to avail the Device Certificate EPA check should have the device certificate installed in the system certificate store of the machine.

User-added image

Install the Device Certificate Issuer’s Certificate Authority Certificate on the NetScaler Gateway

  1. Ensure that you have the Device Certificate issuer’s CA certificate.

  2. Upload the Device Certificate issuer’s certificate to the NetScaler Gateway to /flash/nsconfig/ssl/ or any custom location using SCP or NetScaler Gateway portal.

    Uploading Through SCP:

    User-added image

    Uploading Through NetScaler Gateway Portal:

    Navigate to Traffic Management > SSL Click Manage Certificates and upload the Device Certificate issuer’s CA certificate.

    User-added image

    User-added image

  3. Navigate to Traffic Management > SSL  > Certificates > Install 

    User-added image

  4. Enter the relevant information and select the location of the certificate file and click Install.

    User-added image

  5. If the certificate is installed correctly then it will be listed under the Traffic Management > SSL  > Certificates page.

Binding the Device Certificate Issuer’s Certificate Authority Certificate on the NetScaler Gateway Virtual Server

  1. Binding the CA certificate from CLI:
    bind ssl vserver TestClient -CertkeyName ag51.xm.nsi.test.com -CA -ocspCheck Mandatory
    Note: oscpCheck is optional if OCSP check is not required for Device Certificate.

  2. Binding using NetScaler Gateway Admin Portal:

    1. In the configuration utility, in the navigation pane, expand NetScaler Gateway and then click Virtual Servers.
    2. In the details pane, click a virtual server and then click Edit.
    3. In the main VPN Virtual Server details pane, click the pencil icon then expand More.
    4. In the selection dialog that appears, select Add then click a device certificate to enable. Click the plus icon next to the chosen device certificate and then click OK.

Create/Bind OCSP (Responder) on Device Certificate Issuer’s Certificate Authority Certificate

  1. To create OCSP responder using CLI:

    add ssl ocspResponder ocsp_responder1 -url "http:// www.myCA.org:80/ocsp/" -cache ENABLED -cacheTimeout 30 -batchingDepth 8 -batchingDelay 100 -resptimeout 100 -responderCert responder_cert -producedAtTimeSkew 300 -signingCert sign_cert  -insertClientCert YES
    bind ssl certKey ca_cert -ocspResponder ocsp_responder1 -priority 1
    ​
    sh ocspResponder ocsp_responder1
    1)Name: ocsp_responder1
    URL: http://www.myCA.org:80/ocsp/, IP: 192.128.22.22
    Caching: Enabled        Timeout: 30 minutes
    Batching: 8 Timeout: 100 mS
    HTTP Request Timeout: 100mS
    Request Signing Certificate: sign_cert
    Response Verification: Full, Certificate: responder_cert
    ProducedAt Time Skew: 300 s
    Nonce Extension: Enabled
     Client Cert Insertion: Enabled
    Done
    
    show certkey ca_cert
    Name: ca_cert     Status: Valid,   Days to expiration:8907
    Version: 3
    …
    1)  VServer name: vs1      CA Certificate
    1)  OCSP Responder name: ocsp_responder1     Priority: 1
    Done
     
    sh ssl vs vs1
    Advanced SSL configuration for VServer vs1:
    DH: DISABLED
    …
    1) CertKey Name: ca_cert CA Certificate OCSPCheck: Mandatory
    1) Cipher Name: DEFAULT
      Description: Predefined Cipher Alias

    Note: Insert Certificate is optional.

  2. To create OCSP Responder using NetScaler Gateway Portal, navigate to Traffic Management > SSL OCSP Responder > Add.

    User-added image

    User-added image

  3. Bind the OCSP responder to the Device Certificate issuer’s CA certificate.

    User-added image

Enable Device Certificate Check on the Virtual Server and Add Device Certificate Issuer’s Certificate Authority Certificate to the Device Certificate Checklist

To enable the Device Certificate feature and add the Device Certificate issuer’s CA Certificate name to the list, use the following command:
set vpn vserver TestClient -deviceCert on -certkeyNames DeviceCertCA1, DeviceCertCA2
Note: For multiple CAs add commas. Only max 10 CA certificates are supported.

To enable the device certificate feature on the NetScaler Gateway virtual server from Admin portal:

  1. Navigate to NetScaler Gateway > Virtual Server > Basic setting > More > Device Certificate Option.

    User-added image

  2. Click Add to add the available Device Certificate CA certificate name.

Client-Side Configuration and Verification of Device Certificate on Windows Machine

There are multiple ways to configure the Device Certificate on a Windows machine:

  1. Device Certificate install using Windows Certificate Web Enrollment.

  2. Device Certificate install using Active Directory GPO.

  3. Device Certificate install using Simple Certificate Enrollment Protocol (SCEP).

Note: Ensure that the logon user has privileges to read the Device Certificate key. It is recommended that NetScaler Gateway plug-in is installed on device for Device Certificate EPA Check to work smoothly.

Certificate System Store on Windows

User-added image

Verification of Device Certificate on a Windows Machine

  1. Open a browser and access the NetScaler Gateway FQDN.

  2. Allow the Citrix End Point Analysis (EPA) client to run. If not already installed then install EPA.

  3. Citrix EPA runs and validates the Device Certificate and redirects to the authentication page if the Device Certificate EPA check passes, else it redirects you to EPA error page. In case you have other EPA checks, then the EPA scan results depend on the configured EPA checks.

For further debugging on the client, examine the following EPA logs on client:
C:\Users\<User name>\AppData\Local\Citrix\AGEE\nsepa.txt

Note: Device certificate verification with CRL is not supported.

 

Issue/Introduction

This article describes how to configure Device Certificate on NetScaler Gateway.

Additional Information

Citrix Documentation - Creating Device Certificates for Authentication