PKI authentication (Personal Certificate)

This topic describes Public Key Infrastructure (PKI) authentication, and how to configure PKI authentication for the PVWA.

Overview

PKI enables the use of certificates in order for servers and users to identify each other and establish a secure connection. Amongst other items, certificates contain encryption values, or keys, that are used for encrypting and ensuring the integrity of messages sent between the two parties.

The CyberArk Vault fits into your existing PKI by letting users utilize their personal certificate to authenticate to the Vault. In addition, users can optionally be required to provide password authentication when they log on to the Vault through the PVWA as another authentication method.

When a user logs on to the Vault using the PKI authentication method, the user and the server establish a SSL (Secure Socket Layer) connection. During the SSL handshake, the parties exchange certificates and check their validity. They also check that the other party’s certificate was issued by a trusted CA (Certification Authority).

Configure PKI authentication for the PVWA

During installation, the PVWA is automatically configured to support PKI authentication for users who select this authentication method.

Make sure that all users who are required to authenticate using PKI authentication exist in the Vault, whether they have been provisioned using LDAP integration or were created manually as CyberArk users.

Requirements

■ SSL Certificate – A web server certificate that has been certified by a Certificate Authority (CA).

  1. Make sure that you have installed an SSL certificate on the web server.

  2. In the Default Web Site Properties window on the web site that will host the PVWA, display the Directory Security window, and click Edit to display the Secure Communications Properties window.

     

    This is relevant for IIS 6 only

  3. In the Secure Communications window, select Enable certificate trust list.

  4. If an IIS message appears indicating that the CA is not trusted, do the following:

  1. Click New to create a new CTL,
    or,
    Click Edit to modify an existing CTL list.

    A certificate trust list wizard appears.

  1. Click Next to begin the wizard.

  2. In the Certificates in the CTL window, select the Trusted CA that created the certificate and then complete the wizard.

     

    If the CA doesn’t appear in the Certificates list, add it to the local computer store then repeat this step

  1. Display the Microsoft Management Console.

  2. From the File menu, select Add/Remove Snap-in; the Add/Remove Snap-in window appears.

  3. Click Add; the Add Standalone Snap-in window appears.

  4. Select Certificates, then click Add; the Certificates snap-in window appears.

  5. Select Computer Account, then click Next; the Select Computer window appears.

  6. Select Local Computer, then click Finish; the Add Standalone Snap-in window appears.

  7. Click Close; the Add/Remove Snap-in window appears and displays Certificates (Local Computer).

  8. Click OK; the main Console window appears.

  9. Expand Certificates (Local Computer), then expand Trusted Root Certification Authorities; the Certificates folder appears.

  10. Select Certificates, then from the Action menu, select All Tasks, then Import …; the Certificates Import Wizard appears.

  11. Click Next; the File to Import window appears.

  12. Select the certificate file to import, then click Next; the Certificate Store window appears.

  13. Select Place all certificates in the following store, then click Next; the Completing the Certificate Import Wizard window appears and displays the details of the selected certificate.

  14. Click Finish; the selected certificate is imported to the local computer account.

  15. Open the PasswordVault/auth/pki subfolder, and display the Properties window.

  16. Make sure that Require client certificates is selected, then click OK.

  1. Log onto the PVWA as the predefined Administrator user.

  2. Click ADMINISTRATION to display the System Configuration page, then click Options; the main system configuration editor appears.

  3. Expand Authentication Methods; a list of the supported configuration methods is displayed.

  4. Select pki and make sure the Enabled property is set to Yes.

  5. Click Apply to save the new configurations and apply them immediately,

    or,

    Click Save to save the new configurations and apply them after the period of time specified in the RefreshPeriod parameter.

Enable PKI authentication in the version 10 PVWA interface

The PVWA's version 10 interface can be displayed from version 9.8 and higher, for specific functionality. The following procedure describes how to configure PKI authentication in the version 10 PVWA interface.

 

This can only be configured in version 9.8 and higher.

  1. Using Notepad (not Notepad++), open the IIS configuration file. By default, this is %WinDir%\System32\Inetsrv\Config\applicationHost.config.

  2. At the end of the file, add the following lines:

     

    <location path="Default Web Site/PasswordVault/api/auth/pki/logon">

    <system.webServer>

    <security>

    <access sslFlags="Ssl, SslNegotiateCert, SslRequireCert" />

    </security>

    </system.webServer>

    </location>
  3. Restart the IIS server.

Enable extended PKI/PKIPN validation

You can enable extended PKI/PKIPN certificate validation in the PVWA Configuration options using the ValidatePKICertificate parameter.

When the ValidatePKICertificate parameter is set to Yes, extended validation is enabled.

  1. Go to Administration > Configuration Options.

  2. Under Configuration, select General.

  3. Locate the ValidatePKICertificate parameter and set the value to Yes.

The certificate will pass validation when the following conditions are met:

  • The client and CA certificates don't use elliptic curves

  • The client certificate contains Client Authority in Extended Key Usage

  • The CA certificates have the CA flag set to True in the basic constraints

  • The client certificate is not self-signed

  • SHA1 and MD5 are not used in the signature algorithm

Test PKI authentication in the PVWA

 

Make sure that your personal certificate is accessible. If your certificate is stored on an external hardware device, such as a Smart Card or a USB token, attach it to the computer before you try to log on
■ In thePVWA, in the list of available authentication methods, click pki. Depending on your browser and the security configurations, one of the following scenarios will occur:
■ The PVWA will automatically locate the user’s certificate and log the user on to the Vault,
■ A list of certificates will be displayed where the user can select a certificate and be logged on to the Vault.

Authenticate with PKIPN

In addition to authenticating users with the distinguished name that is specified in the client certificate, the PVWA can also authenticate users with the Principal Name property from the client certificate.

  1. In the PVWA installation folder, by default wwwroot/PasswordVault, create a new folder called CustomAuthenticationDlls.

  2. Copy CyberArk.Authentication.CustomPKIPN.dll from wwwroot/PasswordVault/Bin into the new PasswordVault\CustomAuthenticationDlls folder.

  3. In the Authentication Methods section, create a new authentication method:

    1. Log in with the Administrator user.

    2. In System configuration, select Options, then right-click Authentication methods and select Create New.

    3. For the authentication method name, specify pkipn.

    4. In the ID section, set pkipn.

    5. Set Enabled to Yes.

  4. In thePVWA, configure LDAP integration:

    1. Click ADMINISTRATION to display the System Configuration page, then click Setup Wizard.

    2. Configure LDAP integration, as described in LDAP integration in V10.

    3. Click Administration > Configuration Options, and then click LDAP Integration; the LDAP Integration page appears.

    4. Expand Profiles, then select the profile that you configured when you set up LDAP integration. For example, Microsoft AD profile.

    5. In the profile’s Properties list, change the value of the UserLogonName property from sAMAccountName to userPrincipalName.

       

      To authenticate with the same Principal Name but with a different Logon Name, instead of step e, do the following:

      In the web.config file, under AppSettings,add the following:
      <add key="UsePKIPNAlternateUserName" value="yes"/>
    1. Click Apply to save the new LDAP directory configurations and apply them immediately,

      or,

      Click Save to save the new configurations and apply them after the period of time specified in the RefreshPeriod parameter.

  5. Make sure there is a corresponding directory mapping. For details, seeLDAP integration in V10.

  6. Using Notepad (not Notepad++), open the IIS configuration file. By default, this is %WinDir%\System32\Inetsrv\Config\applicationHost.config.

  7. At the end of the file, at the end of the configuration tag, add the following lines:

     

    <location path="Default Web Site/PasswordVault/api/auth/pkipn/logon">

    <system.webServer>

    <security>

    <access sslFlags="Ssl, SslNegotiateCert, SslRequireCert" />

    </security>

    </system.webServer>

    </location>
  8. Restart the IIS server.

  1. In the PVWA, enable PKI authentication:

    1. Click ADMINISTRATION to display the System Configuration page, then click Options; the Web Access Options are displayed.
    2. Expand Authentication Methods, then select PKI; a list of PKI authentication properties is displayed.
    3. Set Enabled to Yes.

  2. Configure the web.config for the PVWA:

    1. In the PasswordVault folder, open web.config. By default, this folder is in C:\inetpub\wwwroot\.

       

      Make sure that you open web.config in PasswordVault\Bin and not PasswordVault\Env.

    2. Under the <system.webServer> tag, change the following:

        
      <add name="PKIAuth" type="CyberArk.Authentication.PKIAuthentication,
CyberArk.Authentication.PKI" preCondition="managedHandler"/>

      To:

        
      <add name="PKIAuth" type="CyberArk.Authentication.PKIPNAuthentication,
CyberArk.Authentication.PKIPN" preCondition="managedHandler"/>

    3. Copy CyberArk.Authentication.PKIPN.dll from the installation package into the PasswordVault\Bin folder of the PVWA to configure.

  3. In the PVWA, configure LDAP integration:

    1. Click ADMINISTRATION to display the System Configuration page, and then click Setup Wizard.

    2. Configure LDAP integration, as described in Configure the Vault for LDAP.

    3. In the System Configuration page, click LDAP Integration; the LDAP Integration page appears.

    4. Expand Profiles, then select the profile that you configured when you set up LDAP integration. For example, Microsoft AD profile.

    5. In the profile’s Properties list, change the value of the UserLogonName property from sAMAccountName to userPrincipalName.

       

      To authenticate with the same Principal Name but with a different Logon Name, do the following:

      • In the web.config file, under AppSettings,add the following:

        <add key="UsePKIPNAlternateUserName" value="yes"/>

      • In addition, after upgrading, log on to the PVWA and in the LDAP Integration page, in the

        "UserPrincipalName" attribute, specify "userPrincipalName
    6. Save the new configuration.

  4. In the PrivateArk Client, make sure there is a corresponding Directory mapping.

Validate the certificate issuer for PKI and PKIPN authentication (optional)

This is only available in the version 10 UI.

  • In the PVWA web.config file, under AppSettings, add the following value:

    <add key="PKIAuthorizedIssuer" value="CA issuer" />

The value should contain the Certificate issuer, the name of the Certificate Authority (CA) that issued the certificate. It can be the Distinguished Name (DN) or the CN (CommonName/SimpleName).

Examples

  • Distinguished Name:

    <add key="PKIAuthorizedIssuer" value="CN=domain-DOMAIN-CA-CA, DC=domain, DC=com" />

  • CommonName/SimpleName:

    <add key="PKIAuthorizedIssuer" value="domain-DOMAIN-CA-CA" />