Set up the Citrix registration authority

To complete the Citrix FAS integration, you need to get and install the certificate for the Citrix registration authority (RA) and configure the rules for issuing user certificates.

Notice

DigiCert uses the "offline" method to get the long-lived RA certificate. You will request the certificate out-of-band through the Trust Lifecycle Manager REST API and then use a Citrix cmdlet to import the certificate into Citrix FAS. For additional details from Citrix, see https://docs.citrix.com/en-us/federated-authentication-service/current-release/config-manage/private-key-protection.

Step 1: Get the long-lived RA certificate

a. Generate the CSR in PowerShell

Enter the following two Citrix cmdlets in Windows PowerShell to generate the CSR for the RA certificate:

> Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1
> New-FasAuthorizationCertificateRequest -address <FAS server host>

For example:

PS C:\Users\Administrator> Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1
PS C:\Users\Administrator> New-FasAuthorizationCertificateRequest -address localhost


Id                 : 497cd087-0970-4dbd-81f7-bbdc6b96961a
Address            : [Offline CSR]
TrustArea          :
CertificateRequest : -----BEGIN CERTIFICATE-----
                     MIICaDCCAVACAQIwIzEhMB8GCgmSJomT8ixkARkWEUNpdHJpeFRydXN0RmFicmljMIIBIjANBgkq
                     hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwmkT9l4IKI9icLgmrSKiwMCRkN5CnIj57zZI6v4IC7qC
                     1hyItEbcFdfKn9oQ9v2ykb33oooD288onx61ujNadeIGb7YCq5lz+ZfROVXrzuPzC6dtQOlF4YwX
                     mqkujv16aVl0w8mTZtV78YfykaHT4xmilyAT5GnDwcteOXGcduEzPhtnyOgdRlFbf5LudF35e+it
                     ixHz3ZD3p5n9HXsgF65zs/GXiVkU7Pggt8Nw+6IZYPqs8ZnWtI28F48v3uY3zZ4TnZtx28XYgoLa
                     ZTdJQbSirJsKI2B0lQHK7sZv+XnFHZtgXx3qCO64Wxz0vJgU4z0teATRShQ09CJEWKka3QIDAQAB
                     oAAwDQYJKoZIhvcNAQENBQADggEBAHsJjJyZqKVx12uGnjuMSgbqXSaMUFqPc5Mse+NgdPcKa4EJ
                     F17iYuEQpUTbtQDCGe7C8ndIfTitXIplGrDmrJZS5+oUTNGPwC15/J2aV1iBBN2AJeHm4VjtS8GH
                     hErUW+RZRnZmVLNjEnH0cQqFDwgTvTR0fqc7hmwwhu1RRUJWYKCYR6ycjjNDFh6YHYAIhFvm7ogN
                     aMpUzx2a1SbbcQq/cA6noUj9r54bf+FxZpbsY1/yj/Q8P8QAY0+/IPsq8SI1Ks4e2Hcp2c47FbVO
                     E/nzNgob5vdPU4fT9DKDSv1F4hk47KK+uYh73NxZ1UaYioZH3Jf4gden+rFeORTIqg0=
                     -----END CERTIFICATE-----
Status             : WaitingForApproval

Copy the contents of the Id and CertificateRequest fields from the response and store them somewhere safe. You will need them to request the RA certificate and import it into Citrix FAS.

b. Create the RA requester entity in Microsoft AD

You can use any type of Microsoft Active Directory (AD) entity to request the RA certificate, such as a User, Computer, or Service Account. For security reasons, DigiCert recommends using an entity that is only scoped to manage the Citrix RA certificate.

Make sure the userPrincipalName (UPN) of the entity is filled out. For Computer or Service Accounts, use ADSI Edit to add the UPN value.

The following example shows the use of ADSI Edit to add a UPN to a Microsoft gMSA service account:

c. Request the RA certificate via the Trust Lifecycle Manager REST API

To get the RA certificate, use the certificate endpoint from the Trust Lifecycle Manager REST API's Inventory controller. You can read the API documentation by selecting Resources > API reference from the Trust Lifecycle Manager main menu.

Send the following values in the JSON request body:

profile: The ID of the Citrix_RegistrationAuthority profile. You can get this from the profile details screen in Trust Lifecycle Manager.
seat.seat_id: Supply any type of identification string, such as an email address.
csr: Send the value of the CertificateRequest field returned by the Citrix New-FasAuthorizationCertificateRequest cmdlet when generating the CSR. Remove the header, footer, and line feeds. Send only the raw Base64-encoded data.
delivery_format: Specify as PKCS7.
attributes.extensions.san.user_principal_names: Supply the userPrincipalName (UPN) of the RA requester you created in Microsoft Active Directory.
attributes.subject.common_name: Same as above. Supply the userPrincipalName (UPN) of the RA requester you created in Microsoft Active Directory.

Below is an example Trust Lifecycle Manager REST API request and response for issuing the Citrix RA certificate:

Example 1. cURL

curl -X POST \
  https://one.digicert.com/mpki/api/v1/certificate \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: {{api_key}}' \
  -d '{
        "profile": {
            "id": "734f7c98-8549-446b-a026-f290ec674b30"
        },
        "seat": {
            "seat_id": "john.doe@digicert.com"
        },
        "csr": "MIICaDCCAVACAQIwIzEhMB8GCgmSJomT8ixkARkWEUNpdHJpeFRydXN0RmFicmljMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAj1n8IksaaJlh2/THmNuVi92Dgvs0xfohkVo5i8Tm4i01CBMtb669y4SKLQyOfgMElH6Cb9eNnVhs1k0iwWV6x6ZmbcZfLyx45Ci3QM5F/tj2NfffuxFNzFJGDvirEl2eGQ9rt6hf7iw8IlivLNzp7G3boqyg0fa5Zix4zKeizRF4sA1dfKwT7qmNYonk5wub/j2Jf3tnWeFrCE+Gm0qzGfT2uGrjp93KoewH3XwB1oGyj/1j5h+uNc36JXmI5XQIAQul+aazF5zfhK51v0QhuAhNSGMFhkKR+abN+5abdeYzppkxkBs9AHfHgoILhujS9KDNZg8yz46ESEiY5aOkjQIDAQABoAAwDQYJKoZIhvcNAQENBQADggEBAF5YkbVscF3ph9+ogsEIhIZ61D32RmaU3ciE7/l41Tchghfz+877cc/SVBHR1h0MN24ASFSaXxzOxXVl/OqUGUR/zqHuhjLqWWvgLYTusMt8CAB6Dj3yCTd/ufHVwgAbroQ1oyc6v0g+rBJE71aZ6Kfs83Xne3lmspThAXfdX2nvPzcX8wVxqB+r/YT641rRuWme4MIj0revgu/xrFV8O+vcK/IMxuvU29nvBR83XdXqOC/zM5uJP9/Tc+zKN4vYevKidLEj07tdeLBA3+QxaEXM+thUNfOAU4JtU1UMxO/BY30VVkx+srcUAv1UkoBZoK0//btctQ3DND0Gr3JSdGE=",
        "validity": {
            "unit": "days",
            "duration": 730
        },
        "delivery_format": "PKCS7",
        "include_ca_chain": false,
        "attributes": {
            "extensions": {
                "san": {
                    "user_principal_names": [
                        "gmsa_citrix_fas@ws2016.pkidev.bbtest.net"
                    ]
                }
            },
            "subject": {
                "common_name": "gmsa_citrix_fas@ws2016.pkidev.bbtest.net"
            }
        }
     }'

Example 2. 201 OK

{
    "serial_number": "53B5D26CDC7F4EDBF3F56690B6744D49B72FF360",
    "delivery_format": "pkcs7",
    "certificate": "-----BEGIN PKCS7-----\nMIAGCSqGSIb3DQEHAqCAMIACAQExADCABgkqhkiG9w0BBwEAAKCAMIIFKDCCBBCg\nAwIBAgIUU7XSbNx/Ttvz9WaQtnRNSbcv82AwDQYJKoZIhvcNAQELBQAwgaIxCzAJ\nBgNVBAYTAkpQMRMwEQYDVQQIEwpLYWdhd2Eta2VuMRUwEwYDVQQHEwxLYXdhc2Fr\naS1zaGkxETAPBgNVBBETCDIxMi0wMDEzMSYwJAYDVQQJEx1TYWl3YWlrdSwgSG9y\naWthd2EtY2hvIDU4MC0xNjEVMBMGA1UEChMMVGVzdCBBY2NvdW50MRUwEwYDVQQD\nEwxJQ0EgUlNBIDIwNDgwHhcNMjMxMDI2MTYzMTI1WhcNMjQxMDI1MTYzMTI1WjAz\nMTEwLwYDVQQDDChnbXNhX2NpdHJpeF9mYXNAd3MyMDE2LnBraWRldi5iYnRlc3Qu\nbmV0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAj1n8IksaaJlh2/TH\nmNuVi92Dgvs0xfohkVo5i8Tm4i01CBMtb669y4SKLQyOfgMElH6Cb9eNnVhs1k0i\nwWV6x6ZmbcZfLyx45Ci3QM5F/tj2NfffuxFNzFJGDvirEl2eGQ9rt6hf7iw8Iliv\nLNzp7G3boqyg0fa5Zix4zKeizRF4sA1dfKwT7qmNYonk5wub/j2Jf3tnWeFrCE+G\nm0qzGfT2uGrjp93KoewH3XwB1oGyj/1j5h+uNc36JXmI5XQIAQul+aazF5zfhK51\nv0QhuAhNSGMFhkKR+abN+5abdeYzppkxkBs9AHfHgoILhujS9KDNZg8yz46ESEiY\n5aOkjQIDAQABo4IBwjCCAb4wDAYDVR0TAQH/BAIwADAdBgNVHQ4EFgQU2L0aTBjc\nUe9sG0Fk5aQfw2Vet/4wHwYDVR0jBBgwFoAUFpxgRdZt1O9O80AemkidHUjAnNcw\nDgYDVR0PAQH/BAQDAgeAMBUGA1UdJQQOMAwGCisGAQQBgjcUAgEwHQYJKwYBBAGC\nNxUKBBAwDjAMBgorBgEEAYI3FAIBMEMGA1UdEQQ8MDqgOAYKKwYBBAGCNxQCA6Aq\nDChnbXNhX2NpdHJpeF9mYXNAd3MyMDE2LnBraWRldi5iYnRlc3QubmV0MHYGCCsG\nAQUFBwEBBGowaDArBggrBgEFBQcwAYYfaHR0cDovL29jc3AuZGNvbmUuY2x1c3Rl\nci5sb2NhbDA5BggrBgEFBQcwAoYtaHR0cDovL2FpYS5kY29uZS5jbHVzdGVyLmxv\nY2FsL0lDQVJTQTIwNDguY3J0MD4GA1UdHwQ3MDUwM6AxoC+GLWh0dHA6Ly9jcmwu\nZGNvbmUuY2x1c3Rlci5sb2NhbC9JQ0FSU0EyMDQ4LmNybDArBgkrBgEEAYI3FQcE\nHjAcBhRghkgBhv1sJwEBAZWi2MuI/o3AfwIBZAIBATANBgkqhkiG9w0BAQsFAAOC\nAQEAfd3/o03CZ8j9coDG39ozvsRr6MxY9z+IlSaJSnQLX3+W9V09uzMM8fPNvObj\n7YM8XIS1GK3YvoTE3LnPrFyroPQF1/xxudJM52DnuLN1GLplJ1oJmj/c6WopmE7I\ngDMfJxt025DLq7iJazJNcs/ggkfFBednNZinVNO3Pm9DfbkRu1tr/ibLeBGAZANc\nYGYllGydOkBCH63bA765T4aLc24DLHjmZnPRt87QRLpP9ZK0L+Ej7D35uSCsZoFi\nntIYYn5tnKNTyKyjljLyKZp3exY7UaHqumrfgNetyJmm475TFW33Cdt7wODiaPVi\nGQpulB5nF5XQVC6XOHrque+/vDCCBPgwggPgoAMCAQICFFI360xDXyMouW9eczgT\njfngPVv8MA0GCSqGSIb3DQEBCwUAMIGjMQswCQYDVQQGEwJKUDETMBEGA1UECBMK\nS2FnYXdhLWtlbjEVMBMGA1UEBxMMS2F3YXNha2ktc2hpMREwDwYDVQQREwgyMTIt\nMDAxMzEmMCQGA1UECRMdU2Fpd2Fpa3UsIEhvcmlrYXdhLWNobyA1ODAtMTYxFTAT\nBgNVBAoTDFRlc3QgQWNjb3VudDEWMBQGA1UEAxMNUm9vdCBSU0EgMjA0ODAgFw0y\nMzEwMDQwMjU2NDJaGA8yMDUzMDcxMjA5MzAyN1owgaIxCzAJBgNVBAYTAkpQMRMw\nEQYDVQQIEwpLYWdhd2Eta2VuMRUwEwYDVQQHEwxLYXdhc2FraS1zaGkxETAPBgNV\nBBETCDIxMi0wMDEzMSYwJAYDVQQJEx1TYWl3YWlrdSwgSG9yaWthd2EtY2hvIDU4\nMC0xNjEVMBMGA1UEChMMVGVzdCBBY2NvdW50MRUwEwYDVQQDEwxJQ0EgUlNBIDIw\nNDgwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDw/WJ0EkQ0i/QcXyaC\nF1xDPYXkg+0pw0mKoAeXQIlyVYPBILnYiNkzqa5fFDvdKvaxnXGSO41rZBpCdQI5\nBD7qdo3NNdFawnOeza1Qbt3zCNuAl66AlZ/WLGFH2m0wxb/4A/vkW8vS3ACk5TBl\nuwevHg3JPbSOlSyTFW6dLjVQNvsilQj35RE7ufQu74VDiop29jKVTv0mskHvGDxv\noVAt601RMlFRRF+mnTM8VzXkEUG7KOQ2SSKQFnMPJHumFwTaYDE9Z2PaqUgtGUWf\no8CGjOOw99Fq2p0nLPyBGRv9V23gtp92Gqp0DxWF1ai23cCbep8+9hgW6QebGIh8\nyjIZAgMBAAGjggEfMIIBGzAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBQWnGBF\n1m3U707zQB6aSJ0dSMCc1zAfBgNVHSMEGDAWgBReHE6nSXBUu56moiD/SEGl+hcL\n+zAOBgNVHQ8BAf8EBAMCAYYwdwYIKwYBBQUHAQEEazBpMCsGCCsGAQUFBzABhh9o\ndHRwOi8vb2NzcC5kY29uZS5jbHVzdGVyLmxvY2FsMDoGCCsGAQUFBzAChi5odHRw\nOi8vYWlhLmRjb25lLmNsdXN0ZXIubG9jYWwvUm9vdFJTQTIwNDguY3J0MD8GA1Ud\nHwQ4MDYwNKAyoDCGLmh0dHA6Ly9jcmwuZGNvbmUuY2x1c3Rlci5sb2NhbC9Sb290\nUlNBMjA0OC5jcmwwDQYJKoZIhvcNAQELBQADggEBAIYXtrAIHjmRhVv0+ONAfaUf\nKm06wxRFPBIbqUfRTid8rVOmt1KG5oj2w4J9yzmsT0y2gNtXiEjl6NQpmcHTLEbL\nZPoM3BE50PErXSaWuITf0yVWJXW4MahCT24Nzk7vSDptSzsHriErVp/x+vKqdcop\nkrUhB2ApoCs8XJxu0SHCmP3Wd9GLg0Rh25U0oZD6dKVCzWEawj55fUZQImsHti8V\nDplbHYQQGMBrf928gqvyGpDvVg1jnjyn1K/drfTdGkLPqTmXlls/HoWZnXi52y8v\n8wmiBOWsBUVK48kl/miGLkYfuvWaFsJiv/Qqt+akbfIiZ+4YaOpkv9oTDvcvGPIA\nADEAAAAAAAAA\n-----END PKCS7-----"
}

To use the returned Citrix RA certificate, copy the value of the certificate field in the response into a file. Remove the quotes and replace the line feed characters ("\n") with actual line feeds in the file, so it looks like this:

At this point, the RA certificate is stored in PEM format. You need to convert it to DER format before importing into Citrix FAS.

The following example shows how to use the openssl command-line tool to convert a PEM certificate file called ra_cert.p7 into DER format and output to a new file called ra_cert_final.p7b:

openssl pkcs7 -in ra_cert.p7 -out ra_cert_final.p7b -outform der

Store the RA certificate file in DER format on the Citrix FAS system. You will import it into Citrix FAS in the next step.

Step 2: Import the RA certificate into Citrix FAS

Enter the following Citrix cmdlet in Windows PowerShell to import the RA certificate file in DER (p7b) format into Citrix FAS:

Import-FasAuthorizationCertificateResponse -address <FAS server host> -Id <Id from CSR generate> -Pkcs7CertificateFile <path to p7b file>

Make sure the Id value you enter matches the one from the initial CSR generation. For example:

PS C:\Users\Administrator\Desktop> Import-FasAuthorizationCertificateResponse -address localhost -Id 497cd087-0970-4dbd-81f7-bbdc6b96961a -Pkcs7CertificateFile .\ra_cert_final.p7b


Id                 : 497cd087-0970-4dbd-81f7-bbdc6b96961a
Address            : [Offline CSR]
TrustArea          : e28442fe-0bb8-435a-8ae5-ba96e5565bf5
CertificateRequest :
Status             : Ok

After importing the RA certificate, select Refresh on the top-right of the Citrix FAS console. It should now show a green checkmark for Authorize this service.

Example: Citrix FAS console after importing the RA certificate and refreshing

Step 3: Configure Citrix FAS rules

Configure the rules for how Citrix FAS authenticates users, as described in the Citrix documentation.

Under Template, make sure to select the Citrix_SmartcardLogon certificate template:

Under Certificate authority, make sure to select your DigiCert Autoenrollment Server (AES) CA:

What's next

You have now finished setting up the Citrix FAS integration for use with DigiCert® Trust Lifecycle Manager. Test the Citrix FAS integration before releasing it into production.

In this section: