Applies to Windows Server 2008 R2 and Windows Server 2012



Table of Contents

Introduction

Certificate Enrollment Web Services were first introduced in Windows Server 2008 R2. The term Certificate Enrollment Web Services refers to two Active Directory Certificate Services role services:



  • Certificate Enrollment Policy Web Service
  • Certificate Enrollment Web Service
These services utilize an enrollment protocol based on WS-Trust. They enable enables certificate policy retrieval, certificate enrollment, and certificate renewal using hypertext transfer protocol (HTTP) over secure sockets layer / transport layer security (SSL/TLS) encryption (HTTPS).



Return to top

How Certification Authority Web Enrollment Differs from Certificate Enrollment Web Services

Certification Authority (CA) Web Enrollment service was released in the Windows 2000 operating system. CA Web Enrollment allows client computers to submit PKCS #10 requests to the CA interactively through a web browser and Internet Information Services (IIS) application. For example, when this role service is installed, users in the contoso.com domain could enter http://ca.contoso.com/CertSrv in their web browser and see an interactive web site that allows them to upload requests, download completed certificates, and download certificate revocation lists (CRLs).







Although CA Web Enrollment and Certificate Enrollment Web Services both use HTTPS, they are fundamentally different technologies. CA Web Enrollment provides a browser-based interactive method of requesting individual certificates that does not require specific client components or configuration. CA Web Enrollment only supports interactive requests that the requester creates and uploads manually through the web site. For example, if an administrator want to provision a certificate to an Apache Web server running the Linux operating system, a PKCS #10 request that was created by using OpenSSL could be uploaded. After the CA issued the request, the certificate could be downloaded by using the browser.







The Certificate Enrollment Policy Web Service and the Certificate Enrollment Web Service focus on automated certificate requests and provisioning by using the native client starting with the Windows 7 and Windows Server 2008 R2 operating systems. The end user does not have to make a request manually or interact with a web site.







Certificate Enrollment Web Services and CA Web Enrollment are complementary technologies. CA Web Enrollment supports certificate requests and a broad set of client operating systems. The Certificate Enrollment Web Services offer automated requests and certificate provisioning for client computers starting with the Windows 7 and Windows Server 2008 R2 operating systems.







Return to top



Certificate Enrollment Capabilities Provided by Certificate Enrollment Web Services

Certificate Enrollment Web Services allow for additional certificate enrollment and renewal scenarios, which include:



Forest Consolidation

In Windows Server operating system releases prior to Windows Server 2008 R2, AD CS is a forest level resource. Organizations with multiple Active Directory Domain Services (AD DS) forests had to deploy one or more certification authorities (CA) into each forest in which there were users or computers that required automatic enrollment of certificates. Prior to Certificate Enrollment Web Services, even if

  • all forests were centrally managed,
  • there were trust relationships between all forests, and
  • all CAs are part of the same public key infrastructure (PKI) hierarchy
each forest still required its own templates and issuing CAs. This was due to the limitations of the DCOM based enrollment protocol. The result of these requirements is a higher cost and complexity for managing a PKI in a multiple AD DS forest environment.











Certificate Enrollment Web Services enables organizations with multiple forests to consolidate their PKI by eliminating the requirement for per-forest CA deployments. This enables organizations to consolidate PKI services by deploying fewer CAs.







Cross forest certificate issuance requires forest trust to be enabled between all forests, and clients from all forests must be running at least Windows 7 or Windows Server 2008 R2 operating systems.

Note: Starting in Windows Server 2008 R2 there is support for enrollment using the DCOM protocol across forests. This type of certificate enrollment across forests is supported on Windows 7, Windows Vista, and Windows XP clients, although it requires Active Directory objects such as templates to be copied manually from one forest to another.







Return to top

Perimeter Network Certificate Enrollment

Prior to the availability of Certificate Enrollment Web Services, AD CS required that client computers configured for certificate auto-enrollment be connected directly to the corporate network. Certificate Enrollment Web Services allows organizations to enable AD CS using a perimeter network. This allows users and computers outside the corporate network to enroll for certificates. For example, if an organization has an internal network and perimeter network environment, the web services could be run on a system in the perimeter network and connect to a CA running on the internal network. This design allows organizations to maintain existing network segmentation practices while still taking advantage of HTTPS enrollment.

Note: The Certificate Enrollment Web Service must be able to make an authenticated DCOM request to the CA.

For those organizations that do not want to allow internet-accessible servers to process new certificate enrollment requests, renewal-only mode allows the Certificate Enrollment Web Service to process only certificate renewal requests authenticated by a valid existing certificate. This mode requires a lower privilege level because the Certificate Enrollment Web Service does not have to delegate, or act as the end user or computer requesting the certificate. In this mode, full enrollment requests are denied by the Certificate Enrollment Web Service and never reach the CA.

For details on this mode, see the section Renewal-only mode. Renewal-only mode is primarily designed for the following scenario:

  • An organization has many salespeople who travel frequently and rarely connect to the corporate network; these users should be able to be provisioned with certificates in a manner that does not require corporate network connectivity.
  • While the organization could place a Certificate Enrollment Web Service computer on the internet to service the requests, the IT security department prefers not to allow delegated authentication from Internet facing servers back into its internal environment.
  • The organization implements renewal-only mode to satisfy both needs.  Salespeople are initially provisioned with certificates from an internal Certificate Enrollment Web Service endpoint on the corporate network, such as during the imaging and build process for their laptops. These initial certificates, when they reach their renewal overlap period, are then used by the Windows client to sign renewal requests to the internet facing Certificate Enrollment Web Service. A Certificate Enrollment Web Service operating in renewal-only mode does not require delegated authentication privileges, so it provides the lower relative level of risk desired by the organization's security group.
Return to top



Preparing to Deploy a Certificate Enrollment Web Services Infrastructure

When deploying a Certificate Enrollment Web Services infrastructure, there are multiple requirements and considerations. These include:

Installation Requirements

The following installation requirements and capabilities apply to both the Certificate Enrollment Web Service and Certificate Enrollment Policy Web Service, unless otherwise specified:

  • The administrator performing the installation must be a member of the Enterprise Admins group and the local Administrators group.
  • The administrator installing the Certificate Enrollment Web Service must have Request Certificates permission on the CA.
  • The services must be installed on a domain joined computers.
  • The AD DS forest must have at least the Windows Server 2008 R2 AD DS schema version (schema version 47). The recommended forest functional level is Windows Server 2008 or higher.
  • Multiple instances of Certificate Enrollment Web Services can be installed on the same computer, but multiple Certificate Enrollment Policy Web Service instances on the same computer are not supported in Windows Server 2008 R2. In Windows Server 2012, you can install multiple instances of Certificate Enrollment Web Services and Certificate Enrollment Policy Web Service instances by using the AD CS Deployment Cmdlets in Windows PowerShell. To see an example of this, see the Test Lab Guide: Demonstrating Certificate Key-Based Renewal. There is also an example of lab demonstrating a cross-forest certificate enrollment in the Test Lab Guide Mini-Module: Cross-Forest Certificate Enrollment using Certificate Enrollment Web Services.



    • On Windows Server 2008 R2, additional Certificate Enrollment Policy Web Service instances can be installed using certutil.exe.
  • The services can be installed on the same computer.
  • The services can be installed on the same computer as the CA, Web Enrollment, Online Responder, and Network Device Enrollment Services (NDES) role services.
  • The services can be installed on Windows Server 2008 R2 Foundation, Standard, Enterprise, Datacenter, or any edition of Windows Server 2012.
  • On Windows Server 2008 R2, the services do not support Server Core installation. On Windows Server 2012 both services support Server Core installation.
  • On Windows Server 2008 R2 the Enterprise or Datacenter edition is required for certificate enrollment across forests. Any version of Windows Server 2012 supports certificate enrollment across forests.
  • Both services must use secure sockets layer / transport layer security (SSL/TLS) connections (also known as HTTPS) for communication with clients. This means that there must be a valid Server Authentication certificate [enhanced key usage (EKU) object identifier (OID) of 1.3.6.1.5.5.7.3.1] in the local computer store for the computer hosting the service(s).
Return to top



CA Requirements

The following requirements apply to the CA that is targeted for certificate enrollment and renewal by Certificate Enrollment Web Services:



  • An Enterprise CA is required. The Certificate Enrollment Web Service cannot be configured to work with a stand-alone CA.
  • The Certificate Enrollment Web Service can be configured to work with an Enterprise CA on the same computer or a different computer. The CA must be running Windows Server 2003 or higher.
    • If client certificate authentication is used, the CA must be a Windows Server 2008 or higher version of the OS.  A Windows Server 2003 CA will not work as the targeted CA of an Certificate Enrollment Web Service that is configured for client certificate authentication.
    • Running the Certificate Enrollment Web Service in renewal-only mode requires at least a Windows Server 2008 R2 CA.
Note: The Certificate Enrollment Web Service will also work with a CA that is installed in a failover cluster.







Return to top



Client Requirements

Certificate Enrollment Web Services client computers must be computers running at least Windows 7 or Windows Server 2008 R2 operating systems. To utilize key-based renewal, client computers must be running at least Windows 8 or Windows Server 2012 operating systems.







Return to top

Network Connectivity Requirements

Network connectivity requirements are a key part of deployment planning, particularly for scenarios where the Certificate Enrollment Web Policy Service and Certificate Enrollment Web Service will be hosted in a perimeter network.  All client connectivity to both services occurs within an HTTPS session, so only HTTPS traffic is required between the client and the web services. The Certificate Enrollment Policy Web Service communicates with AD DS, using standard Lightweight Directory Access Protocol (LDAP) and secure LDAP (LDAPS) ports (TCP 389 and 636 respectively). The Certificate Enrollment Web Service communicates with the CA using DCOM. By default, DCOM uses random ephemeral ports. However, this behavior is configurable and the CA can be configured to reserve a specific range of ports to simplify firewall configuration. See Microsoft Knowledge Base article 154596: How to configure RPC dynamic port allocation to work with firewalls for more information.







Return to top

Firewall Requirements

If the Certificate Enrollment Policy Web Service is installed in a network location in which there is a firewall between it and a writeable domain controller, the following traffic types must be allowed through the firewall:

  • Kerberos ports: 464, 440
  • LDAP ports: 389, 636

In order to make network traffic across the firewall manageable, configure the CA to use a restricted set of ports. On the firewall, create a rule allowing TCP traffic on the port numbers selected, from the network or host on which the Certificate Enrollment Web Service runs to the CA. For more additional information about configuring a firewall with a Microsoft CA, see the blog post Certificate Enrollment Requires a Custom Protocol.







Return to top



Authentication Method Considerations

The Certificate Enrollment Web Service and the Certificate Enrollment Policy Web Service support three different authentication methods:

Note: Windows 7 clients can authenticate anonymously to web services that use the policy and enrollment protocols.  However, the Microsoft Certificate Enrollment Web services do not accept anonymous authentication requests.

Return to top

Windows Integrated Authentication

Windows Integrated Authentication uses Kerberos to provide a seamless authentication flow for devices connected to the internal network and joined to a domain. This method is preferred for internal deployments because it leverages the existing Kerberos infrastructure present within AD DS and requires minimal changes to certificate client computers. Use this authentication method if you only need clients to access the web service while connected directly to your internal network.







Return to top

Client Certificate Authentication

If certificates will be provisioned to computers, then clients computers can use client certificate authentication. Client certificate authentication does not require a direct connection to the corporate network. Client certificate authentication is preferred over username and password authentication because it provides a more secure method of authenticating.  However, this method requires that x.509 certificates be initially provisioned to clients by separate means. Use this authentication method if you plan to provide users with digital X.509 certificates for client authentication. This authentication method enables you to make the web service available on the Internet.







In Windows Server 2008 R2, if you want to use certificate-based authentication from outside the domain (for a computer configured in a workgroup or that is a member of a domain from which there is no forest trust relationship), then you must also do the following: 

  1. Ensure that a computer account exists in the forest of which the CA is a member that has the same computer name as the computer to which the certificate is to be issued
  2. Issue a certificate using names that are appropriate for the computer to which the certificate is issued. For example, if the CA is a member of a domain named Contoso.com, and
    • the computer to which the certificate is issued is named Client1 (and is configured in a workgroup), then it must have a common name or subject alternative name of Client1.contoso.com.
    • the computer to which the certificate is issued is named Client1, but it is a member of a different domain in a different forest from which there is no trust relationship (for example fabrikam.com), then the certificate should either:
      • include a common name that matches the DNS name of the domain in which it is a member (for example, client1.fabrikam.com) as well as have a subject alternative using a DNS name that matches the forest and domain from which the certificate was issued (for example, client1.contoso.com).

 or

    • include only the computer name as the common name, such as client1, and then also include two subject alternative names:
      • one subject alternative name specific to the domain of which it is a member (for example, client1.fabrikam.com).
      • one subject alternative name specific to the domain from which it was issued (for example, client1.contoso.com).

 

3. Manually transfer the issued certificate from a computer inside the domain to the appropriate computer that is either configured in a workgroup or that is a member of a domain from which there is no forest trust relationship.

 



Return to top

User Name and Password Authentication

The simplest form of authentication is username and password. This method is typically used for servicing clients that are not directly connected to the internal network. It is a less secure authentication option than using client certificates, but it does not require provisioning a certificate to clients. Thus, it is often easier to implement than client certificate authentication. Use this authentication method if you would like users to enter a username and password to authenticate to the web service. This authentication method can be used when the web service is accessed on the internal network or over the Internet.







Return to top

Delegation Requirements

Delegation is the act of allowing a service to impersonate a user account or computer account in order to access resources throughout the network. When a service is trusted for delegation, that service can impersonate a user to use other network services. For general information about delegation and authentication, see Delegating authentication.

Delegation is required for the Certificate Enrollment Web Service account when all of the following are true:

  • the CA is not on the same computer as the Certificate Enrollment Web Service

  • Certificate Enrollment Web Service needs to be able to process initial enrollment requests, as opposed to only processing certificate renewal requests

  • the authentication type is set to Windows Integrated Authentication or Client certificate authentication

Delegation for the Certificate Enrollment Web Service is not required when:

  • the CA and the Certificate Enrollment Web Service are on the same computer
  • username and password is the authentication method

If the Certificate Enrollment Web Service is running as the built-in application pool identity, you should configure delegation on computer account that is hosting the service. If the Certificate Enrollment Web Service is running as a domain user account, then you must first create an appropriate service principal name (SPN) and then configure delegation on the domain user account.







To create an SPN for a domain user account, you can use the setspn command. The setspn command to create SPN for a user account named CES for the Certificate Enrollment Web Policy service running on a computer with a fully qualified domain name (FQDN) of cpandl-ces1.cpandl.com in the cpandl.com domain is as follows:



setspn -s http/cpandl-ces1.cpandl.com cpandl\ces








The specific type of delegation that you should configure depends upon the authentication method selected for the Certificate Enrollment Web Service:

  • If you selected Windows integrated authentication, then you should configure delegation to Use Kerberos only.
  • If the service is using client certificate authentication, then you should configure delegation to Use any authentication protocol.

The specific services that you should delegate are the host service and the Remote Procedure Call system service (RPCSS).







To configure delegation, you can access the computer account or domain user account properties (as applicable to your situation) using Active Directory Users and Computers. Right-click the account and then click Properties. On the Delegation tab, configure the settings as described in this section depending upon the situation. For example, if you have configured client certificate authentication and are using a user account name CES to enable delegation to a certification authority with computer account named CPANDL-CA1, the Delegation tab should be set as shown in the following figure.







 

 Caution
Changes to the Certificate Enrollment Web Service account's Primary group membership has not been tested and may lead to unexpected behavior.



Return to top

Renewal-Only Mode Requirements

If an organization does not wish to enable delegation, but does run the Certificate Enrollment Web Service on a different computer from the CA, renewal-only mode can be implemented. Renewal-only mode does not require delegation. However, renewal-only mode does require that the CA Policy Module flag is enabled to accept renewal-only requests. To enable CA Policy Module flag to allow renewal-only, you must run the following command as an administrator on the CA:







certutil -config "CAConfig" -setreg policy\EditFlags +EDITF_ENABLERENEWONBEHALFOF







You must replace the CAConfig portion of the command with the actual CA configuration. You can see the CA Configuration by running the command certutil on the CA. The following example comes from the Test Lab Guide: Demonstrating Certificate Key-Based Renewal:







Certutil -config "APP1.corp.contoso.com\IssuingCA-APP1" -setreg policy\EditFlags +EDITF_ENABLERENEWONBEHALFOF







The CA must be restarted after this command is run.







When Certificate Enrollment Web Services is configured in renewal-only mode, the CA that issues the certificate must be the same CA used for certificate renewal. The CA will still be able to process standard certificate enrollment requests even after this change is implemented. For additional details on renewal-only mode, see the section entitled Renewal-only mode.

Return to top

Service Account Requirements

During the Certificate Enrollment Web Service installation, the installation wizard presents the choice of either running as application pool identity or as a domain user specified by the administrator. The recommended configuration is that you configure the Certificate Enrollment Web Service to use a domain user account.







The Certificate Enrollment Policy Web Service runs using the credentials of the Internet Information Services (IIS) DefaultAppPool (ApplicationPoolIdentity) by default. The account used is not configurable during role installation, but can be modified using IIS manager after installation. For example, you could modify the service to utilize a domain user account instead of the default application pool.







The following requirements apply to the configuration of service accounts:



  • Both the Certificate Enrollment Web Service and Certificate Enrollment Policy Web Service must run as either a domain user or built-in application pool identity. 
    • Local users are not supported and installation prevents them from being configured.
    • Managed Service Accounts may be used, though they must be configured manually, as described in Managed service accounts.
  • The service account for the Certificate Enrollment Web Service must
    • be a member of the local IIS_IUSRS group.
    • have Request Certificates permission on the CA.
There are a couple of known issues related to the configuration of service accounts for the Certificate Enrollment Web Service and Certificate Enrollment Policy Web Service.
  • If the authentication type is set to Windows integrated authentication, and the Certificate Enrollment Policy Web Service and Certificate Enrollment Web Service are installed on the same computer, and the Certificate Enrollment Web Service is running as a domain user with delegation enabled, authentication fails. The cause is that the service principal name (SPN) assigned to the Certificate Enrollment Web Service is identical to the SPN for the Certificate Enrollment Policy Web Service, which runs as built-in application pool identity by default. This configuration is not supported because of this error.
  • If other Kerberos authenticated http/https services are running on the same host as an Certificate Enrollment Policy Web Service or Certificate Enrollment Web Service configured for Kerberos authentication, enrollment failures may occur because of an SPN collision. The resolution is to configure all of the services to run as the same user account.

Return to top

Managed Service Accounts

The Certificate Enrollment Web Service can run using a Managed service account (MSA), although the role service installation does not support this option. To configure the Certificate Enrollment Web Service to run as an MSA:

  1. Configure the service to use the built-in application pool during initial configuration.
  2. Use the IIS Manager snap-in to change the WSEnrollmentPolicyServer application pool’s identity setting to the managed service account name. Use the name format of “CORP\serviceaccountname$”, where CORP is replaced with the domain name, and serviceaccountname is the name of the managed service account. The $ at the end of the account name is required. The password field must be left blank.

For more information about creating and managing MSA’s, see Service Accounts Step-by-Step Guide.







Return to top

Planning for Performance and Availability

Microsoft conducts various performance tests during the development of its products.  Using release candidate builds of Windows 7 and Windows Server 2008 R2, the following performance metrics were observed for the Certificate Enrollment Web Service. Note that these metrics are not a guarantee of performance within customer environments, and that they can be dramatically impacted by the hardware and network configuration used in a given environment.

  • CA and Certificate Enrollment Web Servicee installed on separate computers, each running Windows Server 2008 R2 release candidate build with 2 2.33 GHz Intel dual core processors and 8GB of RAM
  • Domain controller installed on a Windows Server 2008 R2 server with 2 dual-core AMD Opteron 2.4 GHz processors and 4GB RAM.
  • Enrollment service configuration designed to represent common customer deployment scenario where the CA, Certificate Enrollment Web Service, and Domain Controller all run on separate systems
  • Enrollment service configured to run in the context of a domain user account, with constrained delegation configured for “normal mode” tests.
  • three client computers used to generate load against Certificate Enrollment Web Service

Summary of Observations

Enrollment service processing was as follows.  The single biggest factor affecting throughput was network latency.

  • In normal mode, the enrollment web service processes enrollment requests at a rate of 60 requests per second.
  • In renewal-only mode, the enrollment web service processes renewal requests at a rate of 170 requests per second.

Enrollment service mode

Delegation configuration

Requests / second

W3wp.exe Memory consumption

W3wp.exe CPU consumption

Normal

Constraint with Kerb only auth

60

120 M

%20 to %40

Renewal only

None

170

150 M

%20 to %40

Certificate Enrollment Web Service Performance Counter Data

Item

Value

Note

Call duration

0.39 – 0.45 second

The time Certificate Enrollment Web Service spends to process one request

Calls per second

33

How many requests Certificate Enrollment Web Service can process per second

Client Performance Data

The following metrics described the overall time required to complete various request types from the time the client initiated the request until the time it was completed. 

Request type

Round trip time

Enroll

14 seconds

Renew

12 seconds

Retrieve CA cert

3 seconds

QueryTokenStatus

2 seconds

Planning Hardware Requirements

As noted in the previous section, the primary factor governing throughput of the Certificate Enrollment Web Services design is network latency. Thus, hardware requirements planning should first begin at the network layer by ensuring that all Certificate Enrollment Policy Web Service and Certificate Enrollment Web Service endpoints are connected over high bandwidth, low latency links to each other and to back end CAs.  Ideally, Gigabit Ethernet will connect these systems and there will be few, if any, network hops separating them.

When considering server hardware, the standard hardware platform used for web servers in your organization is a good place to start. Typically, web services are more efficiently scaled ‘out’ rather than ‘up’.  In other words, if additional capacity is needed in the future, it’s typically more effective to add additional nodes, rather than adding memory or CPU capacity to existing ones.  Policy and Certificate Enrollment Web Service endpoints can also be good candidates for running in a virtualized environment, such as Hyper-V.







Return to top

Planning Load Balancing and Fault Tolerance

Rather than relying on network load balancing (NLB) technologies, the Certificate Enrollment Policy Web Service and Certificate Enrollment Web Service client components have load balancing and fault tolerance logic built in. For example, the clients will automatically randomize the list of endpoints they’re provided and attempt to iterate through the list if the first endpoint is unresponsive. Thus, as long as multiple uniform resource identifiers (URIs) are published, basic load balancing and fault tolerance is built in.

Note that NLB should not be used to provide fault tolerance or high availability because NLB could route traffic to a host where the policy or web service is stopped or unavailable.  If all endpoints are published behind a single NLB balanced URI, the built in client logic would not be able to try the next URI, which would result in a less fault tolerant solution than if no special load balancing was used at all.

General best practices for load balancing the policy and enrollment web services include:

  • Publish multiple enrollment and policy URIs, each with unique DNS names and preferably available through different network paths; allow the built in client logic to provide load balancing and fault tolerance

  • Do not publish multiple URIs behind a single URI (unless that URI is load balanced behind a device that is both network and application layer aware).

  • Do not use DNS round robin or other DNS load balancing techniques that do not provide application layer intelligence and routing

Return to top

Windows Client Enrollment – Policy Server Load Balancing

For Group Policy configured policy settings, you can configure two servers (URLs) as part of the same policy.  As a result, both policy server URLs will be functionally equivalent. The client then selects one URL to use, based upon the following rules:

Note: To configure the load balancing behavior described below, Group Policy configured settings must be used. User configured policies do not enable multiple URLs to be configured as part of the same policy.

  1. The URI whose policy has been cached from a previous request and whose next update time is the latest is most preferred.
  2. If two URI’s have the same next update time then:
    • The URI with the lower value in the “Cost” registry entry is preferred. The default value is that all costs are equal. If two costs are equal then:
      • The URI is selected based on authentication type, in the following order: Kerberos, Anonymous, Username/Password cached in the vault or Client Authentication Certificate cached in the vault, Username/Password or Client Authentication Certificate.
      • If all properties are equal then a URI is randomly selected.

Return to top

Windows Client Enrollment – Enrollment Server Load Balancing

Once a policy server is selected there may be multiple enrollment servers to choose from. The client will pick an enrollment server using the URI that has the lowest priority number as defined in the enrollment policy. If two enrollment servers have the same priority, then:

    • The URI with the following authentication type is preferred in order: Kerberos, Anonymous, Username/Password cached in the vault or Client Authentication Certificate cached in the vault, Username/Password or Client Authentication Certificate.
    • If all properties are equal then a URI is randomly selected.

Return to top

Example Configurations

The following sections discuss different configurations depending on the circumstances of the organization.

Intranet with a Single Forest

The most simple deployment scenario involves a single forest with intranet connected clients. In this design, the Certificate Enrollment Policy Web Service and Certificate Enrollment Web Service may be installed on an issuing CA, but it is recommended that they are installed on separate computers. If the Certificate Enrollment Policy Web Service and Certificate Enrollment Web Service are run on separate computers, the Certificate Enrollment Policy Web Service must be able to communicate with AD DS using LDAP. The Certificate Enrollment Web Service must be able to connect to the CA using DCOM.  In intranet scenarios, Kerberos would typically be selected as the authentication type.







Intranet with Multiple Forests

A more advanced intranet scenario involves multiple forests with centralized issuing services in only one (or some) of them. In this design, the forests are connected with a two-way forest trust and the CA and the certificate enrollment web services are hosted in the same forest. The advantages of this model are that it provides for a high degree of consolidation in multiple forest environments.  Whereas in the past, each forest required its own CA for auto-enrollment, now all PKI services can be centralized, potentially resulting in a large reduction of the total number of CAs required.  Again, because this is an intranet scenario, the most common authentication scheme to use would be Kerberos.







Return to top

Perimeter Network & Branch Office

A new deployment option not previously feasible is a perimeter network or branch office facing Certificate Enrollment Web Service. Specifically, this deployment scenario provides the ability to enroll users and computers that are not directly connected to an organization’s network or connected over a virtual private network (VPN). In this design, the Certificate Enrollment Policy Web Service and the Certificate Enrollment Web Service are both placed in the perimeter network, and internet based clients enroll over HTTPS to these endpoints. This deployment model is ideally suited to domain users who often work remotely or branch office scenarios in which the VPN or direct connection back to the corporate network is unreliable. The scenario is depicted below.







Note that a Read Only Domain Controller (RODC) can optionally be used. The external clients (remote users) have no access through the Corp firewall to the writeable domain controller or to the CA.  The enrollment and policy web service servers have no access to the writeable domain controller. However, the Certificate Enrollment Web Service must be allowed to connect through the firewall to the CA over DCOM.











In perimeter network deployments, certificate or username and password based authentication would most likely be used by the clients to authenticate to the Certificate Enrollment Web Services.







Return to top

Renewal-Only Mode

For the Certificate Enrollment Web Service to be able to request certificates from a CA, it needs to delegate the call to the CA while impersonating the caller. This in turn means that the Certificate Enrollment Web Service account should have delegation enabled. For internet facing Certificate Enrollment Web Service endpoints, this may not be preferred because it represents an increased level of exposure to internet based threats.

To mitigate this risk, renewal-only mode allows the Certificate Enrollment Web Service to process only certificate renewal requests without delegation enabled. The Certificate Enrollment Web Service uses the original certificate, provisioned from within the internal network, to authenticate the renewal request sent over the internet. The Certificate Enrollment Web Service will then submit the request to the CA under its own credential, and the CA will renew the certificate based on the Active Directory information of the requester of the original certificate and/or the subject information in the original certificate. In this mode, new certificate enrollment requests will be denied by the Certificate Enrollment Web Service and will never reach the CA.

From a network design perspective, this scenario combines both the internal and perimeter network models discussed previously.











Return to top

Key-based renewal

Key-based renewal mode is a feature introduced in Windows Server 2012 that allows an existing valid certificate to be used to authenticate its own renewal request. This enables computers that are not connected directly to the internal network the ability to automatically renew an existing certificate. To take advantage of this feature, the certificate client computers must be running at least Windows 8 or Windows Server 2012.







You can use key-based renewal to allow certificate client computers outside your AD DS forest to renew their certificates before they expire. This includes clients that are configured in workgroups or clients that are members of other AD DS forests. An account in the forest of the CA must be used in order to obtain the initial certificate. However, once that certificate is distributed to the client, key-based renewal does not require forest trusts in order to allow for certificate renewal. Web1 must also have the root CA certificate in the Trusted Root Certification Authorities store before requesting a certificate renewal.







For example, a certificate issued to a web server configured in a workgroup could be renewed by an Enterprise CA domain member. An example of such a configuration is shown in the following figure. Web1.treyresearch.com (Web1) is a member of a workgroup that has a certificate issued by CA1.corp.contoso.com (CA1). The certificate is valid for both Client Authentication and Server Authentication. CA1 is an Enterprise CA and member of the AD DS domain corp.contoso.com.















Web1 can utilize Certificate Enrollment Web Services to renew its certificates automatically if key-based renewal is enabled. In this scenario, an administrator of Web1 would have to ensure that the URI of the Certificate Enrollment Policy Web Service is configured on Web1. You can see a step-by-step test lab guide demonstration of a similar scenario in Test Lab Guide: Demonstrating Certificate Key-Based Renewal.







Another example configuration for key-based renewal is to allow for the automatic renewal of certificates that were provisioned across domains. For example, an initial certificate with the Client Authentication EKU from CA1.corp.contoso.com is requested by using a user account in the Corp.contoso.com domain. That certificate is then placed on Client1.cpandl.com. Client1 must also have the root CA certificate in its Trusted Root Certificate Authorities store before requesting a certificate renewal.







Client1 is a member of the Cpandl.com domain. CA1 is an Enterprise CA in the corp.contoso.com domain. CA1.corp.contoso.com and Client1.cpandl.com are members of different forests. There is not a forest trust joining the two forests. Client1 can use key-based renewal to automatically renew its certificate with CA1. The URI of the Certificate Enrollment Policy Web Service can be distributed to Client1 using Group Policy configured on Cpandl.com.















Note: The URI for the Certificate Enrollment Policy Web Service is something that you have to configure on certificate clients so they can locate the service. The URI for the service is set in the Internet Information Service (IIS) on the computer running Certificate Enrollment Policy Web Service. The URI has ADPolicyProvider_CEP as part of its name. Additional information about the URI is part of the Installation and Initial Configuration informational links in the following section.



The CES URL(s) is also published to the 



CN=Enrollment Services,CN=Public Key Services,CN=Services,CN=Configuration,DC=<domain> partition (use adsiedit.msc to view). Choose properties on the CA object there, and navigate to msPKI-Enrollment-Servers attribute, here the active URLs can be found. The same information can also be obtained executing the "certutil -enrollmentserverurl" command on the CA server. This will give a more readable overview of the different URL(s). Note that for key-based renewal to work silently the certificate CES must be installed in renewal-only mode and key-based renewal mode. This can be verified by looking at msPKI-Enrollment-Servers and checking that the certificate CES url has the number (1)81 before and a 1 at the end. The first number (181) shows the defined priority of the URL so it can be different than 1, depending on the desired configuration. For key-based renewal to work from a outside network, the firewall that is placed between the client and server must be configured to pass the client certificate to the CEP/CES server. Products like TMG does not do this if one has configured the CEP/CES as a publised web-site.  







Note: You can see a step-by-step test lab guide demonstration of a cross-forest certificate enrollment scenario in the TechNet Wiki article Test Lab Guide Mini-Module: Cross-Forest Certificate Enrollment using Certificate Enrollment Web Services







Return to top



Revoking certificates that could be used for key-based renewal

When certificates that could be used for key-based renewal must be revoked, there is a specific procedure that must be followed to ensure that the client does not attempt to renew these certificates using key-based renewal.
  1. Remove the template that has key-based renewal enabled from each CA that is issuing the template.
  2. Revoke the appropriate certificates.
  3. Publish an updated CRL for each CA that was issuing the template that had key-based renewal enabled.
  4. Invalidate the revocation information on each CA designated for issuing the template that has key-based renewal enabled by running the following command:
    • certutil -setreg chain\ChainCacheResyncFiletime @now
  5. Reissue the certificate template that has key-based renewal to the appropriate certification authorities for issuance.
Return to top



Installation and Initial Configuration

The methods and steps for the installation of Certificate Enrollment Web Services vary depending upon the operating system version on which you are implementing them. Certificate Enrollment Web Service and the Certificate Enrollment Policy Web Service running for Windows Server 2008 R2 can be installed using Server Manager only. The installation and configuration steps for these services on Windows Server 2008 R2 are described in the Certificate Enrollment Web Services in Windows Server 2008 R2 whitepaper. However, on computers running Windows Server 2012, you can install the Certificate Enrollment Web Service and Certificate Enrollment Policy Web Service using Server Manager or Windows PowerShell. The location of the installation instructions for computers running Windows Server 2012 vary depending upon the service and type of installation as follows:







Instructions for installing and initially configuring the Certificate Enrollment Web Service on Windows Server 2012

Instructions for installing and initially configuring Certificate Enrollment Policy Web Service on Windows Server 2012

Note: If you need to install Certificate Enrollment Web Services on Server Core, use Windows PowerShell.

Return to top







Client Behavior

The Windows client contacts a Certificate Enrollment Policy Web Service to get certificate policy information consisting of:

  • the certificate types the client can use for enrollment
  • the Certificate Enrollment Web Service to contact for enrollment
  • the type of authentication to use
The client must first be configured with information about which computer(s) running Certificate Enrollment Policy Web Service to contact and how to authenticate to them. 

There are two ways to configure the Certificate Enrollment Policy Web Service for users and computers: through Group Policy or locally on the client.

Once configured, applicable certificate enrollment policies will appear in the certificate enrollment wizard during interactive enrollments. The image below shows a Group Policy configured certificate enrollment policy named “Contoso Corporate Policy”.  User configured policies appear under Configured by you.







Return to top

Policy Server Configuration and Selection

When the client is asked to enroll, it will first enumerate enrollment policies that are registered on the computer. For each type of certificate (user or computer), the Group Policy configured certificate enrollment policies are enumerated first, then the user configured policies

Group policy configured policy server settings (listed under “Configured by your administrator” in the Certificate enrollment wizard) are stored under the following registry locations:

For user certificate policy

HKEY_CURRENT_USER\Software\Policies\Microsoft\Cryptography\PolicyServers\

For computer certificate policy

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Cryptography\PolicyServers\

User configured policy server settings (listed under “Configured by you” in the Certificate Enrollment wizard) are stored under the following registry locations:

For user certificate policy

HKEY_CURRENT_USER\Software\Microsoft\Cryptography\PolicyServers\

For computer certificate policy

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\PolicyServers\

In these locations, you will find a registry key for each URL. Each key is a hash of the URL. Under the registry key there are the following settings:

  • URL – URL by which the client will contact the policy server
  • Cost – policy servers with a lower value in this entry will be tried first.
  • Policy ID – Identifier of the policy to which the policy server belongs.  Many policy servers (URLs) can belong to the same policy ID.  This can be configured through Group Policy, not locally on the client, and is useful for redundancy and/or load balancing.
  • Friendly Name (optional) – This is the policy name that appears to the user in interactive enrollments, such as “Contoso Corporate Policy” in the image above.
  • Authentication type (“AuthFlags”) – This is the means by which the client must authenticate to the policy server.
  • Flags  - This is the entry in which the settings for the following two administrator configurable certificate policy properties are stored:
    • Enable for automatic enrollment and renewal –This setting is separate from the “Certificate Services Client – Auto-Enrollment” Group Policy setting and should be enabled when that setting is used.
    • Require strong validation during enrollment – This setting is enabled by default and requires the CA from which certificates are obtained to be trusted by the client.

Return to top

Client Enrollment – Cached Policy

When the Certificate Enrollment Policy Web Service is contacted, the client obtains policy and maintains a local cache. Client computers store enrollment policy for the computer computer and user in different locations:







  • Computer certificate enrollment policy is stored in %ProgramData%\Microsoft\Windows\X509Enrollment.
  • User certificate enrollment policy is stored in %USERPROFILE%\AppData\Local\Microsoft\Windows\X509Enrollment.

In the cached certificate enrollment policy file, there is an XML element called nextUpdateHours. This file determines how long the cache file is valid. After that period of time, the certificate enrollment policy must be obtained again from the server.







Return to top

Client Enrollment – Cached Credentials

When a user or computer accesses an enrollment policy server or an enrollment server, the user or computer must authenticate to the service. If the authentication method is username/password or client authentication certificate then a pop-up will appear asking for credentials.



The checkbox “Remember my credentials” can be checked to store credentials on the local system in the vault. Credentials are encrypted. Subsequent connections using the client to the same Certificate Enrollment Policy Web Services server or Certificate Enrollment Web Services server will attempt to use the credential stored in the vault.

You can browse the user vault through the user interface by going to Control Panel->User Accounts->Credential Manager. There is no user interface to browse the computer vault. However, the certutil -credstore command allows you to display the vault for the computer and user. It also will allow you to add and remove entries from either credential vault.

Storing credentials in the vault is useful when auto-enrollment is used. If auto-enrollment cannot authenticate to the service, it will skip that service and be unable to enroll/renew the certificate. Auto-enrollment will attempt to use credentials stored in the vault to authenticate to a service.

Return to top



Devices Running Windows RT

Devices running Windows RT cannot join an AD DS domain, which prevents them from being able to utilize domain-based certificate enrollment options. However, devices running Windows RT can use Certificate Enrollment Web Services to obtain and renew certificates. If Certificate Enrollment Web Services are configured to allow user name and password authentication, a user or administrator of a device running Windows RT could connect to the Certificate Enrollment Policy Web Service URI to obtain an initial certificate by supplying domain user credentials. After the initial certificate is placed on the device running Windows RT, key-based renewal can be used to renew the certificate before it expires.



For more information, see the PKI blog article: Certificate for WinRT devices and non-domain member devices.

Return to top



Troubleshooting

There multiple different issues that you may encounter when using Certificate Enrollment Web Services. The sections below discuss potential issues and resolutions.







Managing Certificate Enrollment Policy Web Service Polling for Certificate Templates

Certificate Templates are stored in AD DS, and the Certificate Enrollment Policy Web Service polls the AD DS periodically for template changes. Changes made to templates are not reflected in real time on the Certificate Enrollment Policy Web Service. When administrators duplicate or modify templates, there can be a lag between the time at which the change is made and when the new templates are available. By default, the Certificate Enrollment Policy Web Service polls the directory every 30 minutes for changes. The Certificate Enrollment Policy Web Service can be manually forced to refresh its template cache by recycling IIS using the command iisreset.







The polling interval can be configured by using the Internet Information Services (IIS) Manager console.



To configure the template polling interval



  1. Open the Internet Information Services (IIS) Management console on the computer running Certificate Enrollment Web Policy Services.
  2. Expand the web server object. Expand Sites. Expand Default Web Site. Click the virtual application that represents the Certificate Enrollment Web Policy Services connection that you want to modify (i.e. ADPolicyProvider_CEP_Certificate). The actual name depends upon whether you enabled Key-based renewal and the type of authentication that the service is configured to use.
  3. In the virtual application Home screen, double-click Application Settings.
  4. In the Actions screen, click Add.
  5. In the Add Application Setting dialog box, set the Name to RetryIntervalMs.
  6. In Value enter the number of milliseconds that you want to configure as the polling interval. For example, to set the polling interval to 15 minutes, you would enter 900000 as the value. Click OK.

Alternatively, the polling interval can be adjusted by modifying the web.config file for the application. To set a different polling interval, open the following file in a text editor, such as Notepad: %windir%\SystemData\CEP\ADPolicyProvider_CEP_<AuthenticationType>\web.config where <AuthenticationType> is replaced with whatever authentication method is used with the Certificate Enrollment Policy Web Service. In the <AppSettings> section, create a RetryIntervalMs section with the appropriate value. For example, to set the polling interval to 15 minutes (900000 milliseconds) you would add a line that reads <add key="RetryIntervalMs" value=900000" /> as shown in the following figure.















Typically, this change would typically be made only in environments with frequent changes to templates and where those changes need to be reflected immediately.  In most environments, it is recommended that the default polling interval be maintained and that administrators rely on manually restarting IIS (iisreset) when faster polling is occasionally required for troubleshooting purposes.



Return to top







Error Messages

  1. When sending renewal requests to an enrollment service in renewal-only mode, the certificate that signs the renewal request must have the same public/private key pair as the certificate being renewed:
    1. When sending a PKCS7 renewal request to an enrollment service in renewal-only mode, if the cert-based signature is from the certificate being renewed, the renewal should work properly.
      1. If the cert-based signature is not from the certificate being renewed, the enrollment service will fail with following: Error 1.
    2. When sending a CMC renewal request to an enrollment service in renewal-only mode, if the request has one cert-based signature from the certificate being renewed, the renewal should work properly.
      1. If the request has one certificate-based signature from a different certificate, the enrollment service will fail with Error 1
      2. If the request has two certificate -based signatures: one from the certificate being renewed, and one from a different certificate, the enrollment service will pass the request to the CA, but the CA will return Error 2.
      3. If the request has two certificate -based signatures, neither of which are from the certificate being renewed, the enrollment service will fail with Error1.
  2. Setup fails to add the Certificate Enrollment Policy web service account permission to the Deleted Objects container in Active Directory.
    1. Message: "Setup could not add the computer security identifier of the server hosting the Certificate Enrollment Policy Web Service to the security descriptor of the "Deleted Objects" container. The web service will not be able to get notification of any deletion of an Active Directory object. To complete Setup, a member of the Domain Admins group must manually add the computer security identifier to have List access to the security descriptor of the "Deleted Objects" container in the Active Directory Domain Services (AD DS)."
    2. Impact: the policy service may not be able to obtain policy updates from Active Directory, such as the removal of templates.
    3. Fix: manually add Read access for the security identifier (SID) of the computer on which the policy service is running to the access control list (ACL) of the Deleted Objects container in AD.  If the policy service is running on the DC, you must also add the SID of the application pool identity to the Deleted Objects container’s ACL. This is an advanced configuration and can be done using ldp.exe.
  3. Upon clicking “Validate” in the Certificate Enrollment Policy Server configuration UI:
    1. The error “The proxy could not process the request” appears in the display box under “Certificate enrollment policy server properties”.  This can mean the local area network (LAN) settings on the computer attempting to validate the policy service URI are incorrect. 
      1. If it is a user certificate enrollment URI, check the settings by opening an Internet Explorer session and selecting Options on the Tools menu, then going to the “Connections” tab and clicking “LAN Settings…”. 
      2. If it is a computer certificate enrollment URI, try changing the configuration using the tool proxycfg.exe. Note: Proxycfg.exe is not available starting with Windows Windows Vista. Instead, you can use Netsh Commands for Windows Hypertext Transfer Protocol (WINHTTP). To make configuring the proxy settings for WinHTTP-based applications easier, WinHTTP now implements the Web Proxy Auto-Discovery (WPAD) protocol, often referred to as autoproxy.
    2. The error "The certificate request could not be submitted to the certification authority" appears in the display box under “Certificate enrollment policy server properties”.  This can mean the delegation settings on the Certificate Enrollment Web Service account are not correct, or that there is another permissions problem between the enrollment service and the CA.
      1. Check the account as whom the enrollment service is running, and if the service is not in renewal-only mode, ensure that the account is configured for delegation as described under “Certificate Enrollment Web Service Account Security Settings” in the “Setup Step-By-Step” section above.
    3. GUID conflicts with existing GUID when LDAP and CEP (with same GUID) are configured by user – Error message looks like “The URI entered above has ID: "{GUID}". This ID conflicts with an existing ID.”. Follow these instructions to solve this issue:
      1. Logon to the CEP server
      2. Open IIS Manager from Server Manager->Tools Menu
      3. Expand Server Name->Sites->Default Web Site
      4. Select ADPolicyProvider_CEP_<authmethod> (Where <authmethod> is your authentication method: kerberos, username, or certificate)
      5. On ASP.NET panel, double-click Application Settings
      6. Double-click ID
      7. Change the GUID.
        • Note: You can literally just add a character or two to the end of the GUID. You can also obtain a new GUID from Visual Studio or from any online GUID generator web site or use a script like Generate a GUID. The only requirement here is that the GUID be different than the existing LDAP GUID.
      8. Reset IIS by opening an elevated Command Prompt and typing IISRESET

     

Return to top

Clearing the Policy Cache





  • If AD templates and/or ACLs have changed and the client is not seeing the new policy:
    • Update the web service policy cache by running iisreset or restarting the policy service application pool on the policy web server.
    • Clear the policy cache on the client machine by deleting any files under %ProgramData%\Microsoft\Windows\X509Enrollment\ or %USERPROFILE%\AppData\Local\Microsoft\Windows\X509Enrollment

Return to top

Change the Cost Settings





  • To change the order in which the client will try different policy servers (Enrollment Policy URIs) within the same policy, update the “cost” registry DWORD.  The default value is 0x7ffffffd. A lower value (such as 1) will cause the client to use that policy URI first.  The “Cost” registry key is found in the following locations:
    • For group policy configured policy server settings (listed under “Configured by your administrator” in the Certificate enrollment wizard):
      • For user certificate policy
      • HKEY_CURRENT_USER\Software\Policies\Microsoft\Cryptography\PolicyServers\
      • For machine certificate policy
      • HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Cryptography\PolicyServers\
    • For user configured policy server settings (listed under “Configured by you” in the Certificate Enrollment wizard):
      • For user certificate policy
      • HKEY_CURRENT_USER\Software\Microsoft\Cryptography\PolicyServers\
      • For machine certificate policy
      • HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\PolicyServers\
Return to top



Check Permissions





  • Permissions required to obtain policy from the policy web service:
    • The client will obtain policy based on the credentials used to connect to the policy web service URI. 
      • Authenticating user must have read and enroll on a template in order for that template to be retrieved as part of the policy.
      • For machine certificates, in addition to the authenticating user having read and enroll on the template, the machine must have read and enroll as well.  If the requesting machine does not have enroll, the user performing the enrollment or renewal will be able to see the policy but will fail upon the enrollment or renewal request.
      • If using renewal-only mode, user the enrollment web service is running as must have “request certificates” permission on the CA
      • If there is not at least one certificate enrollment web service configured for a CA configured to issue a template, that template will not be returned as part of the policy, regardless of permissions settings.
  • ( Renewal only mode) Check Certificate and AD Subject Name Settings.
    • If renewal requests are failing in renewal only mode, check that there is sufficient information for the CA to retrieve and verify the requester name from the original certificate. This is required for a successful renewal only mode renewal request.  A CA operating in renewal only mode verifies the subject information for the new certificate in the following manner.
      • First, it looks in the CA database for the original certificate with the same serial number and public key ,
      • If the above fails, then it uses the UPN in the Subject Alternative Name (SAN) extension of the original certificate, if one is present, to perform an AD lookup.
      • If a UPN is not present in the original certificate, it tries to perform the check using the contents of the subject name extension in the original certificate.
      • If none of the above is successful, the renewal request will fail.
Return to top



IIS Kernel Mode Authentication

Kernel mode authentication is an IIS feature added in Windows Server 2008. By default, this setting is disabled for both the enrollment service and policy service applications.  If this setting is enabled, the first Kerberos-authenticated request to the policy or enrollment service after the application pool is restarted will fail with an “access denied” message.  It is recommended that kernel mode authentication be disabled on Certificate Enrollment Policy Web Service and Certificate Enrollment Web Service servers.

Return to top

Advanced Certutil Commands

The following commands are provided as a reference for use in advanced configuration scenarios, such as disaster recovery or troubleshooting and are not required for default usage.

  • To specify the policy service endpoint: certutil –setreg ca\PolicyServers
  • To add the enrollment service URI to the CA Enrollment Services object in Active Directory: certutil –config “{cahostname.domain.com}\{caname}” –enrollmentServerURL https://{cahostname.domain.com}/{caname}_CES_{Authtype}/service.svc/CES {Authtype}



    Where {Authtype} is replaced with either Kerberos, UserName, or ClientCertificate
  • To display CA Enrollment Services object attributes (including the enrollment service URI): certutil –adca
  • To display enrollment policy data including general certificate enrollment web service configuration details: certutil –policy
  • Steps for manually configuring renewal-only mode on AD CA enrollment services object:
    • Use the command “certutil –enrollmentserverURL” to update the msPKI-EnrollmentServer attribute of CA object in the Enrollment Services container with the ROBO flag. This must be done by deleting the existing entry and recreating it as a renewal-only enrollment server URI:
      • Display existing enrollment server URI’s:

certutil –config “{CA Config String}” –enrollmentServerURL

  • The output will show each configured enrollment server url with its authentication type and whether it is in renewal only mode or not, for example:

Enrollment Server URL[0]:  Priority 1

 

Authentication  4

Username – 4

 

AllowRenewalsOnly    0

https://enrollmentserver.contoso.com/CA1_CES_UsernamePassword/service.svc/CES

 

  • Delete existing enrollment server URL:

certutil –config “{CA Config String}” –enrollmentServerURL https://enrollmentserver.contoso.com/CA1_CES_UsernamePassword/service.svc/CES delete

  • Re-create enrollment server URL as renewal-only:

certutil –config “{CA Config String}” –enrollmentServerURL https://enrollmentserver.contoso.com/CA1_CES_UsernamePassword/service.svc/CES {AuthType} {Priority} {AllowRenewalsOnly}

where:

AuthType = either “UserName” or “ClientCertificate”

Priority = 1

AllowRenewalsOnly = 1

Return to top



Configuring Advanced Server Diagnostics

There are multiple types of logging that you can enable to help in diagnosing issues with Certificate Enrollment Web Services. The following sections discuss these types of logging.







Return to top

Event Log Level

Certificate Enrollment Policy Web Service and Certificate Enrollment Web Service utilize the Windows Eventing infrastructure for logging.  Event Viewer can be used to view and manage their logs, by drilling down into the following locations:

Applications And Services Logs\Microsoft\Windows\EnrollmentPolicyWebService

Applications And Services Logs\Microsoft\Windows\EnrollmentWebService

Locations of web.config files:

 for Certificate Enrollment Policy Web Service: <%windir%>\systemdata\CEP\ADPolicyProvider_CEP_<Authentication Type>\web.config

for Certificate Enrollment Web Service:

 <%windir%>\systemdata\CES\<CA Name>_CEP_<Authentication Type>\web.config

The event log level can be changed by adding a new key/value to the web.config file under the <AppSettings> section at the end of the file:

For the Enrollment Policy Server

 <add key="LogLevel" value="4" />

For the Enrollment Server

 <add key="EventLogLevel" value="4" />

 

Event Log level values available:

Description         Value

Off                         0             

Error                      1

Warning               2

Info                        3

Verbose              4







Return to top

WCF Logging

When Event Logging does not help to investigate an Enrollment Policy Server or Enrollment Server issue, tracing can be enabled to show any exceptions or communication problems at the Windows Communication Foundation layer.

Certificate enrollment web services are web applications. To configure them to trace run time logs, open the web.config file and follow the steps below.

1. Find the following section in the web.config  file:

<system.diagnostics>

    <sources>

      <source name="System.ServiceModel" switchValue="Off" propagateActivity="true">

2. Change the value "Off" can be changed to any of the following Debug Level Tracing values : Critical, Error, Warning, Information, Verbose, ActivityTracing, All.

Trace Log File Locations:

Enrollment Policy Server 

Location:

<%windir%>\systemdata\CEP\ADPolicyProvider_CEP_<Authentication Type>\Traces\

 

Files:

Traces-ADPolicyProvider.xml

Traces-PolicyServer.xml

Traces-ServiceModel-PolicyServer.xml

 

Enrollment Server

Location:

<%windir%>\systemdata\CES\<CA Name>_CES_<Authentication Type>\Traces\

 

Files:

Traces-EnrollmentServer.xml

Traces-ServiceModel-EnrollmentServer.xml

If the Tracing directory does not exist, create the directory and give read and write permissions to the application pool credentials the Certificate Enrollment Web Service or Certificate Enrollment Policy Web Service uses. If necessary, open the web.config in service configuration editor and modify trace settings appropriately.





Return to top



  1. Get tracelog.exe and tracefmt.exe tools
    1. http://www.microsoft.com/whdc/devtools/WDK/default.mspx
  2. Download and install public symbols package:
    1. http://www.microsoft.com/whdc/devtools/debugging/symbolpkg.mspx
  3. Enable logging:

tracelog.exe -rt -start schannel -guid #37D2C3CD-C5D4-4587-8531-4696C44244C8 -f .\schannel.etl -flags 0x4000ffff -ft 1

  1. Reproduce the issue.
  2. Stop the logging:

tracelog -stop schannel

tracefmt -p <symbols location>\traceformat  schannel.etl -o schannel.out

  1. Read schannel.out for the log information.

Certsrv Logging

Certsrv logging is useful to help determine why a request from Enrollment Server to the Certification Authority has failed.

To enable CA debug logging, enter the following command on the CA machine :

  certutil –setreg ca\debug 0xffffffe3

The log file is in the following location: %windir%\certsrv.log

Return to top



CertEnroll Logging on the Enrollment Policy Server

The enrollment policy service uses the CertEnroll client to read templates.  Any failure in this process may be captured by the CertEnroll debug log on the policy server.

To enable debug logging for the CertEnroll client, execute the following command:

Certutil –setreg enroll\debug 0xffffffe3

The log file is in the following location by default: %windir%\CertEnroll.log

On the computer running the Certificate Enrollment Web Policy Service, the log file may be located in the profile directory for the identity of the policy service application pool (WSEnrollPolicyWebServer): %Systemroot%\Users\WsEnrollmentPolicyServer

Return to top



Logging LDAP Traffic Between the Certificate Enrollment Policy Web Service and AD

LDAP tracing can be useful to troubleshoot communications between the certificate enrollment policy service and Active Directory.

Steps to enable LDAP Tracing ( using the Enrollment Policy Server w3wp.exe as an example )

  1. Create the registry key HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ldap\Tracing\w3wp.exe
  2. Run the command iisreset at the command line on the computer running the Certificate Enrollment Web Policy Service.
  3. Start the tracing by running the following command: 
    • tracelog.exe -start ldaptrace -guid #099614a5-5dd7-4788-8bc9-e29f43db28fc -f .\ldap.etl -flag 0x80000
  4. After this command has started, DEBUG_BIND tracing messages will be written to .\ldap.etl.
  5. Send a request to the policy service or reproduce the unexpected behavior.
  6. Shut down the tracing session by executing the following command: tracelog.exe -stop ldaptrace
  7. Delete the registry key HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ldap\Tracing\w3wp.exe
  8. Generate the report by running the following command: tracerpt.exe .\ldap.etl -o -report

For more information on LDAP tracing, see the following MSDN article: http://msdn.microsoft.com/en-us/library/aa366152(VS.85).aspx

Return to top



Logging DCOM Traffic Between the Certificate Enrollment Web Service and the CA

In cases where requests seem to make it to Certificate Enrollment Web Service but are not properly received by the CA, it can be useful to log DCOM traffic between the enrollment service and the CA.  This method provides more application specific protocol data than a network trace and is typically easier to parse.  Note that Certificate Enrollment Web Service automatically sends the URI used in requests to the CA for diagnostic usage.

  1. Open the Registry Editor.
  2. Locate the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Ole registry subkey.
  3. Right-click the Ole value, point to New, and then click DWORD Value.
  4. Type ActivationFailureLoggingLevel, and then press ENTER. Double-click ActivationFailureLoggingLevel, type 1 in the Value data box, and then click OK.
  5. Right-click the Ole value, point to New, and then click DWORD Value.
  6. Type CallFailureLoggingLevel, and then press ENTER. Double-click CallFailureLoggingLevel, type 1 in the Value data box, and then click OK.
  7. Restart the DCOM program, and then examine the System log and the Application log for DCOM errors.
Return to top



Configuring Advanced Client Logging

The client consists of many Windows components working together, each with its own logging:



CertEnroll / CryptoAPI

Web Services client (WebServices.dll)

WinHTTP / SOAP

SSL / Kerberos

  • CertEnroll and Cryptography API (CAPI2) are the Windows components that perform certificate enrollment and cryptographic operations, such as key generation and signing.
  • The web services client creates the http requests to send to the web services.
  • WinHTTP and SOAP are protocols by which the http requests are sent to the web services.
  • SSL and Kerberos are authentication protocols used to connect to the web services.
Return to top



CertEnroll Logging





To enable debug logging for the native Windows CertEnroll client, execute the following command:



Certutil –setreg enroll\debug 0xffffffe3



The log file is in the following location: %windir%\CertEnroll.log







Return to top



CAPI2 Logging

To enable advanced logging for the CAPI2 layer, perform the following steps:



1.    Open EventVwr.msc



2.    In the Event Viewer, open Applications and Services Logs -> Microsoft -> Windows -> CAPI2.



3.    Right-click on "Operational" and select “Enable Log”. This will enable CAPI2 Diagnostics logging.



4.    To save the log to a file, right click on "Operational" and select the “Save Events as” option. You can save the log file in the .evtx format (which can be opened through the Event Viewer) or in the standard XML format.



If there is data present in the logs before you reproduce the problem, it is recommended that you clear the logs before the repro. This allows only the data relevant to the problem scenario to be collected from the saved logs. To clear the logs, right click on "Operational" and select the “Clear Log” option.



The default size for the event log is 1 MB. For CAPI2 Diagnostics, the logs tend to grow in size quickly and it is recommended to increase the log size to at least 4 MB to capture relevant events. To increase the log size, Right-click on “Operational” and select the “Properties” option. In the log properties, increase the maximum log size.







Return to top



Logging for Web Services Client (webservices.dll) - Event Logging





To view the complete SOAP request and response, enable WebServices.dll Event logging as follows:



1.    Open EventVwr.msc



2.    In the Actions pane at right, click View and select “Show Analytic and Debug Logs”



3.    In the Event Viewer left pane, open Applications and Services Logs -> Microsoft -> Windows->WebServices



4.    Right-click on "Tracing" and select “Enable Log”.



5.    Reproduce the issue



a.    Request the templates from the Certificate Enrollment Policy Web Service.



b.    Enroll for a certificate through Certificate Enrollment Web Service.



c.    When you refresh the event viewer page, you should start seeing the WWSAPI tracing entries.



6.    When finished gathering tracing data, right-Click on Tracing, and choose Disable log.



7.    In Actions Panel, “Choose Filter Current Log…”



8.    Filter with ID 13, 14 (Request and Response), as shown in the figure below.



9.    Look at the General Tab content of each event for the original SOAP message.



a.    Large messages will be split across multiple events.







Return to top



Logging for Web Services Client (webservices.dll) - Webservices.dll Tracing

1.    Get wstrace.bat script from the SDK



a.    http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx



2.    Open the SDK command prompt as administrator.



3.    Create trace log



wstrace.bat create verbose



4.    Enable tracing wstrace.bat on



5.    Start dumping of tracing messages to a file wstrace.bat dump > temp.csv



6.    Switch to your application and reproduce the scenario.



7.    Switch to the command prompt and press Ctrl+C. This should stop tracing and wstrace batch file.



8.    Turn off tracing wstrace.bat off



9.    Delete tracing log wstrace.bat delete







Return to top



WinHTTP Logging

To see all HTTP requests the web services client sends to the policy and enrollment service, enable WINHTTP logging.

Use the following command:

netsh winhttp set tracing trace-file-prefix="d:\temp\winhttplog" level=verbose format=hex state=enabled

The file is located in %systemdrive%\temp\

The filename starts with “winhttplog*”.

Return to top



Schannel Logging

  1. Get tracelog.exe and tracefmt.exe tools
  2. http://www.microsoft.com/whdc/devtools/WDK/default.mspx
  3. Download and install public symbols package: http://www.microsoft.com/whdc/devtools/debugging/symbolpkg.mspx
  4. Enable logging:
    • tracelog.exe -rt -start schannel -guid #37D2C3CD-C5D4-4587-8531-4696C44244C8 -f .\schannel.etl -flags 0x4000ffff -ft 1
  5. Reproduce the issue.
  6. Stop the logging:

tracelog -stop schannel

tracefmt -p <symbols location>\traceformat  schannel.etl -o schannel.out

Read schannel.out for the log information.







Return to top