ADFS Server

Prerequsiste:
  • The user should also be a Local Admin on the ADFS server.
  • ADFS service should be up and running.
  • For the profile below, ensure that the certificate contains a private key. For endpoint-enrolled certificates, verify that the private key is marked as exportable.
    • Token-Signing
    • Token-Decryption
    • SSL Certificate
    • Service Communications
    Note: For endpoint enrolled certificate, the Private Key Exportable option is set to False by default. However, you can enable this setting in the Windows Gateway (GW) if required. Restart the GW service for the change to take effect.
  • Ensure that the Subject Name / Subject Alternative Name (SAN), Key Usage and Extended Key Usage requirements are followed for each ADFS profile.
  • Whether you use the default internally generated certificates or externally enrolled certificates, you must ensure that all relying parties are updated with the new certificate information whenever the token-signing certificate changes.
  • Similarly, when the token-decrypting certificate is changed, all claims providers must be updated with the new certificate information.
The supported profiles for push and bind are as follows:
Category Profile Name
Relying Party Trust Encryption ADFS_DEVICE_NAME:Encryption:RPT_NAME
Relying Party Trust Signature ADFS_DEVICE_NAME:Signature:RPT_NAME
Note: Backup and Rollback are not applicable for the profiles since these profiles allow importing multiple certificate.
Token-Decrypting ADFS_DEVICE_NAME:Token-Decrypting:Primary

ADFS_DEVICE_NAME:Token-Decrypting:Secondary

Note:
  • Prerequsites - Key usage should either have KeyEncipherment or DataEncipherment.
  • Backup and Rollback are not applicable for the Secondary profiles since these profiles allow importing multiple certificate.
  • Ensure that the private key for the chosen certificate is accessible to the service account for this Federation service on each server in the farm.
Token-Signing ADFS_DEVICE_NAME:Token-Signing:Primary
ADFS_DEVICE_NAME:Token-Signing:Secondary
Note:
  • Prerequsites - Key usage should have DigitalSignature.
  • Backup and Rollback are not applicable for the Secondary profiles since these profiles allow importing multiple certificate.
  • Ensure that the private key for the chosen certificate is accessible to the service account for this Federation service on each server in the farm.
Service-Communication ADFS_DEVICE_NAME:Service-Communication
Note: Prerequsites are as follows:
  • Ensure that the certificate includes the Server Authentication Extended Key Usage (EKU) extension.
  • Ensure that the Federation Service name configured in the Federation Service properties must match the subject name or be one of the values in the SAN.
  • Certificate must have a private key and is marked exportable as True.
AdfsSslCertificate ADFS_DEVICE_NAME:AdfsSslCertificate
Note: Prerequsites are as follows:
  • Ensure that the certificate includes the Server Authentication Extended Key Usage (EKU) extension.
  • Ensure that the Federation Service name configured in the Federation Service properties must match the subject name or be one of the values in the SAN.
  • Certificate must have a private key and is marked exportable as True.
Note: For ADFS, any certificate pushed through this process is first imported into the Local Computer's Personal Store. From there, the certificate is imported and configured in the ADFS server.

Steps:

  1. On the certificate holistic view, click Add Connector.
  2. Enter the General Information for the connector.
    Table 1. Field descriptions for the connector General Information
    Field Description
    *Category From the dropdown list, select Server.

    If the certificate being pushed was enrolled with CSR generation at endpoint, this field is auto populated with the category selected at the time of certificate enrollment.

    For the endpoint enrolled certificate, the Category field is pre-populated by default and editable.
    *Vendor From the dropdown list, select ADFS Server.

    If the certificate being pushed was enrolled with CSR generation at endpoint, this field is auto populated with the vendor selected at the time of certificate enrollment.

    For the endpoint enrolled certificate, the Vendor field is pre-populated by default and editable.
    *Connector Name Enter a name for this connector, to be able to identify it later.
    Tip: AppViewX recommends naming connectors according to use cases so they are easily distinguishable.
    Description Enter any additional details you want to record for this connector.
    Based on the information entered here, the Server selection section is populated with the list of available ADFS Server devices already onboarded in AppViewX.
  3. To select the device(s) to which the certificate will be pushed, under Server selection, from the list of Available Devices, click .
    The Selected devices list is updated automatically.
  4. Enter the Certificate Details.
    Field Description
    *Certificate File Name Enter the file name of the certificate to be pushed. This field is auto-populated based on the common name.
    Push Root and Intermediate Certificates By default this checkbox will be selected.

    To push the root and intermediate certificates, along with the end certificates, select this checkbox.

    The push operation is successful even if checkbox is unselected.
    Service Restart This option is applicable only for the Service Communication certificate profile.

    If a federation server farm is deployed, the ADFS server must be restarted for every server in the farm for changes to take effect.
    Based on the information populated here, the Server selection section is populated with the list of available ADFS Server devices already onboarded in AppViewX.
  5. Enter the Push Details.
    Field Description
    *Script Location Script files are commonly used to perform certain tasks required to be completed before and/or after a certificate is pushed to the target system.

    The script to be run before the certificate is pushed is called a pre-push script and the script to be run after the push is called a post-push script. The script that automates the push operation is called a push script.

    From the following options, select the location of the script file(s):

    • In AppViewX
    • In Device
    Pre - Push Script File Name Enter the file name of the pre-push script.
    Important: Read the pre and push script usage instructions here.
    Pre - Push Script File Path This field is displayed when Script Location = In Device.
    Enter the location on your local system where the pre-push script file is stored.
    Important: Read the pre and push script usage instructions here.
    Pre - Push Script Parameters Enter the values that will be passed to the pre-push script.
    *Push Script File Name Enter the name of the push script.
    Push Script Parameters Enter the values that will be passed to the push script.
    Post - Push Script File Name Enter the file name of the post push script.
    Important: Read the pre and push script usage instructions here.
    Post Push Script Parameters Enter the values that will be passed to the post-push script.
    Post Push Script File Path This field is displayed when Script Location = In Device.
    Enter the location on your local system where the post-push script file is stored.
    Important: Read the pre and push script usage instructions here.
    Rollback Location

    To recover from a conflict or failure during a push operation, copies of the certificate and configuration file are stored in a directory or storage location.

    In the Rollback Location field, enter the path to this location.

    Rollback Parameters Enter the rollback parameters (settings) used to initiate the rollback process.
    Overwrite The Overwrite option is used to specify if existing certificates on the target system will be overwritten with the certificate being pushed.

    If this option is enabled, the certificate being pushed will overwrite any existing certificates with the same identifier on the target system. This will also ensure that only the latest version of the certificate is available on the target system.

    If it is disabled, the push operation will fail in the event of conflicts with the certificates on the target system.
    Push Automatically To automatically push the certificate after it is renewed/reissued to the target system, enable this checkbox.
    Note: The auto push feature for a certificate works only if enabled for the certificate application connector as well the associated certificate group.
    Secure Push The Secure Push option ensures that the certificate is pushed to the target system securely, protected from any unauthorized access.
  6. Click Save.
    The connector is displayed on the certificate holistic view.
Remember:
  • Certificates can be repushed to the store, these include renewed/regened/reenrolled certificates.
  • The Appconnector is copied to the renewed/regened/reenrolled certificates.

Troubleshooting

  1. Token-Signing or Token-Decryption Profiles
    • If a certificate already exists for Token-Signing or Token-Decryption and the system attempts another bind operation, the system returns the following error:
      Note: This is only applicable when the certificates are pushed to the Secondary profile.
      PS0108: Given certificate is already being used as a secondary Signing certificate.
    • If the same certificate is pushed as Primary, the system ignores the error and proceeds to set the certificate as Primary.
    • If the same certificate is pushed again as Secondary, the system fails the operation.
    • If the certificate is already configured as Primary and when attempted to push as Secondary, the system fails the operation and returns the following error:
      PS0107: Given certificate is being used as primary Signing certificate.
    • When AutoCertificateRollover is enabled (the default setting), ADFS automatically manages these certificates. In this case, the system fails the bind operation by default.
    • If AutoCertificateRollover is disabled, AppViewX allows users to bind external certificates for Token-Signing and Token-Decryption.
  2. AdfsSslCertificate Profiles
    • Binding to AdfsSslCertificate profile works when run locally on the ADFS server, but when executed via remote PowerShell (from Gateway installed in another machin) it fails with the following error:
      PS0316: AD FS Server: 'localhost', Error: 'Connecting to remote server localhost failed with the following error message: Access is denied…'

      This is a known double-hop / remoting limitation with Set-AdfsSslCertificate.

    • Workaround: Install the Windows Gateway on the same machine where ADFS is installed and bind the certificate to the AdfsSslCertificate profile to complete the binding successfully.