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 Central Credential Provider 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.

Define internal application in the PVWA

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.

    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.

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.

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:

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, NTLM or 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.