Central Credential Provider web service configuration

This topic describes how to access and configure the Central Credential Provider web service.

The default name for this web service is AIMWebService. This topic refers to this default name. If you gave it a different name during installation, replace AIMWebService in this topic with the name you gave. For installation details, see Install the CCP web service. This topic assumes you know how to work with the Windows Server Manager and the Internet Information Services (IIS) Manager. For instructions on using your version of this tool, see the relevant Microsoft documentation. This topic assumes that the CyberArk CRL (Certificate Revocation List) is open from the Central Credential Provider server.

Define the Central Credential Provider web service

In the PVWA, define the internal application that the web service will use to access the Credential Provider.

To define the internal application:

1. Select APPLICATIONS > Add Application to open the Add Application dialog box.

2. Define an application called AIMWebService. Click Add.

3. Add the following authentication requirements for the AIMWebService application:

   Parameter	Description
   Path	Add a Path authentication requirement for the web service application: The path of the internal dll for the web service. By default, this is C:\inetpub\wwwroot\AIMWebService\bin\AIMWebService.dll.
   Windows OS User	The name of the operating system user that runs the IIS web service. By default, IIS APPPOOL\DefaultAppPool. Privilege Cloud user: Use this authentication method if the CCP is installed on the Privilege Cloud Connector machine.
   Hash	The hash of the internal dll of the web service. To enable hash authentication of the web service, calculate and configure the hash using the NetAIMGetAPPInfo utility. This utility is copied to the ApplicationPasswordProvider\Utils folder during installation. Calculate the hash using the following command:   NETAIMGetAppInfo.exe GetHash /AppExecutablesPattern=”C:\inetpub\wwwroot\AIMWebService\bin\AIMWebService.dll” The above example includes the default path. If you installed the web service in a different path, specify the correct path. For more information about calculating a hash value, see the NetAIMGetAppInfo utility.

   For more information about defining applications, see Add applications.

Central Credential Provider web service configuration file

Configure the Central Credential Provider web service, AIMWebService, using the web.config file. This file is located in C:\inetpub\wwwroot\.

The following parameters in this file can be modified:

We recommend not modifying any other parameters.

Parameter	Description
AppID	The unique ID of the web service issuing the password request. Default: AIMWebService   <appSettings> <add key="AppID" value ="AIMWebService"/> </appSettings>
AIMWebServiceTrace	The level of debug messages written to the AIMWSTrace.log file. Default: 0 Accepted values: 0 - No messages written to the log. This is the default debug level. 1 - Errors 2 - Errors and warnings 3 - Errors, warnings and information 4 - Errors, warnings, information and activities. This value should only be set for troubleshooting purposes due to the volume of messages.

Verify .NET Framework version

This section describes how to verify the .NET framework version that the Central Credential Provider web service, AIMWebService, is using.

To verify that AIMWebService uses .NET Framework v4.0, in the IIS Manager:

1. Open the Application Pools page.

2. In the .NET Framework column, verify that the application pool running AIMWebService uses .NET Framework v4.0.

   To change the .NET Framework version, double-click the application pool and select .NET Framework v4.0.

Multiple security configurations and authentication methods for the Central Credential Provider web service

You can configure the Central Credential Provider web service, AIMWebService, to work with several different security configurations and authentication methods concurrently.

For example:

• Some applications access the Credential Provider using client certificates, while other applications access it without client certificates.

• Some applications access the Credential Provider using Windows Domain Authentication, while others access it using a different authentication method.

To use this functionality, you may need to adjust your URL when calling the API. When using an external certificate, the Central Credential Provider server must have access to the CyberArk CRL (Certificate Revocation List).

SOAP API

To define multiple security configurations, set up multiple subfolders under the web service folder:

1. In the AIMWebService installation folder (by default, inetpub\wwwroot\AIMWebService\), under the V.1.1, copy the aim.asmx file.

2. In the AIMWebService installation folder, create additional subfolders (for example V1.2, V1.3, and so on) and paste the aim.asmx file into the new folders.

3. Define the required security configuration for each AIMWebService subfolder, as described in Secure communication between applications and the Central Credential Provider below.

4. Define the required authentication method configuration for each AIMWebService subfolder, as described in Configure Windows Domain Authentication below.

REST API

To define multiple security configurations and authentication methods:

1. On the Central Credential Provider server, open the Internet Information Services (IIS) Manager.

2. Add a virtual application for each authentication:

   1. Select the folder where the Central Credential Provider web service is installed. By default, this is Default Web Site.

   2. Under Default Web Site, add an application (right-click Default Web Site > Add Application)

   3. Provide an Alias (for example, WithOutCert) and the physical path to the AIMWebService, and click OK.

   4. Repeat for each authentication.

3. Define the required security configuration for each virtual application, as described in Secure communication between applications and the Central Credential Provider below.

4. Define the required authentication method configuration for each virtual application, as described in Configure Windows Domain Authentication below.

Secure communication between applications and the Central Credential Provider

It is recommended to secure connections between the requesting application and the Central Credential Provider using one or both of the following layers:

Layer	Description
SSL	Strongly recommended: Use SSL between the requesting application and the Central Credential Provider web service, AIMWebService.
Client Authentication	In addition to SSL, use Client Authentication to authenticate the requesting application using a client certificate.

To configure secure connections between the requesting application and Central Credential Provider:

1. Configure SSL

   Configure SSL between the requesting application and the Central Credential Provider web service.

   This procedure enables HTTPS communication, using a server side certificate.

   Although the Central Credential Provider web service supports non-SSL connections, it is recommended to work with SSL.

   1. Configure HTTPS between the requesting application and the Central Credential Provider web service using a self-signed server certificate or a certificate signed by a private Certificate Authority (CA).

   2. In the IIS Manager, create an HTTPS binding to the web site where the Central Credential Provider web service was created (by default, Default Web Site), using the certificate you just created.

   3. On the Central Credential Provider machine:

      If you configured multiple SOAP/REST APIs endpoints, do the following for each endpoint that needs this authentication.

      1. Select the folder where the Central Credential Provider web service is installed. By default, this is Default Web Site > AIMWebService.

      2. In the SSL settings for this folder, select Require SSL.

         For example (IIS Manager 10.0.x):

         

   4. On the application machine, make sure that you have a corresponding server certificate. Store this certificate in the trusted certificates store.

2. Configure Client Authentication with client certificates

   In addition, you can enable client-side authentication of the requesting application against the Central Credential Provider web service, using a client certificate.

   From the application machine, configure client authentication against the Central Credential Provider web service using a self-signed or CA-signed client certificate:

   1. Create the relevant client certificate to authenticate the requesting application against the Central Credential Provider web service.

   2. Copy and import the client certificate to the trusted certificates store on the Central Credential Provider machine.

      For information about importing trusted certificates, see  http://technet.microsoft.com/en-us/library/cc765181(v=ws.10).aspx.

   3. On the Central Credential Provider machine:

      If you configured multiple SOAP/REST APIs endpoints, do the following for each endpoint that needs this authentication.

      1. In the IIS Manager, under Sites > Default Web Site, select the folder where the Central Credential Provider web service is installed. By default, this is AIMWebService.

      2. In the SSL settings for this folder, under Client certificates, select:

         • Accept to accept incoming connections from any clients
         • Require to accept only authorized connections if Client Authentication (using a client certificate) was used

         

   4. Copy the client certificate to the machine where the application is located. When requesting a password, the generated web service request must be sent to the Central Credential Provider with this certificate.

Configure Windows Domain Authentication

This section describes how to configure Windows Authentication on the Central Credential Provider machine to enable the Central Credential Provider to authenticate applications with the Windows domain user that runs the application.

In addition, you need define the allowed authentication in the application definition in the PVWA. For details, see Manage applications.

To enable some applications to authenticate with Windows Domain authentication and others to authenticate using different authentication methods, configure the Central Credential Provider web service to work with multiple endpoints. For more information, see Multiple security configurations and authentication methods for the Central Credential Provider web service above.

To configure Windows domain authentication on the Central Credential Provider machine:

1. In the Windows Server Manager, make sure that the Windows Authentication role service is installed. For details, see the Microsoft documentation.

2. In the IIS Manager, make sure that DefaultAppPool v4.0 application pool is installed. For details, see Microsoft documentation.

3. Define the Windows Authentication Providers:

   If you configured multiple SOAP/REST APIs endpoints, do the following for each endpoint that needs this authentication.

   1. In the IIS Manager, navigate to Sites > Default Web Site, and select the folder where the Central Credential Provider web service is installed. By default, this is AIMWebService.

   2. In Authentication, select Windows Authentication.

      1. Enable Windows Authentication.

      2. Click Advanced Settings, and disable Kernel mode authentication.

      3. Add the Windows Authentication Providers according to your organization’s needs. To do this, click Providers and add the necessary providers from the Available Providers list to the Enabled Providers list. Always add Negotiate, then add the provider required by your organization, for example, Negotiate:Kerberos.

         Remove any other providers from the Enabled Providers list.

      4. In the Authentication list, disable all other authentications.

4. Restart IIS by running the following PowerShell command:

   iisreset

Enable HSTS

HTTP Strict Transport Security (HSTS) is a policy mechanism that helps to protect websites against man-in-the-middle attacks such as protocol downgrade attacks and cookie hijacking. It allows web servers to declare that web browsers (or other complying user agents) should automatically interact with it using only HTTPS connections.

Configure a hardened server to accept OS user authentication

When hardening a server, all non-administrator users become blocked from authenticating to the hardened server using OS user authentication.

When Central Credential Provider is installed on a hardened PVWA, you need to reconfigure the authenticated users on this server:

1. Go to the Local security policy.
2. Under User Rights Assignment, select Access this computer from the network.

3. In the policy's properties, add the Authenticated Users group. This allows all non-administrator users to connect to Central Credential Provider using OS user authentication and successfully retrieve secrets.

This configuration change allows more users to connect to your PVWA server and, as a result, may expand the attack surface on that server. To control user access on this server, you can add a user-defined group instead of the Authenticated Users group.