Integrate Identity Manager with Microsoft ADCS

This article includes updates for Smart ID 23.10.5.

To connect Smart ID Identity Manager to Active Directory Certificate Services (ADCS), one component must be set up - the ADCS Connector - and one component must be configured - Identity Manager with a CA Proxy configuration. This article describes how to configure both components. 

For more information about the components, see About the Identity Manager ADCS integration. 

Set up the ADCS connector

The ADCS connector is needed for Identity Manager to issue certificates from an ADCS.

Prerequisites

• A Windows 2012 R1/R2, Windows 2016, or Windows 2019 server that is a member of the domain that the Enterprise CA is running on.

• The .NET common language runtime (CLR) version 4 must be installed.

• The Role IIS needs to be installed on the server.

• The following IIS features must be installed:

  • WCF Services

  • ISAPI Extensions

  • ISAPI Filters

• At least 1 CPU, 4 GB ram, and 5 Gb HD free disk space is needed.

• Installation package for the ADCS connector must be available.

• The public part of all issuing CA certificates that are related to the Smart ID use cases are needed in a file in the Identity Manager application server (for example, .cer or .crt  in X.509 format).

• To use Smart ID with ADCS, the certificate templates in ADCS must be modified as follows:

  • Activate "supply subject name" in request.

  • Make sure that no user interaction in Microsoft UIs is required.

  • Deactivate "CA manager approval".

  • Disable any additional officer signatures.

• A TLS certificate server certificate must be issued to enable HTTPS on the ISS service for the ADCS connector. A certificate can be either issued via the internal request functionality on IIS or provided as PKCS#12 Softtoken. CN and SAN must match the hostname in the URL that is used to call the ADCS connector.

• A TLS Client certificate with both certificate and key (.pfx, .p12) for Identity Manager is required. It is used to authenticate from Identity Manager to the ADCS Connector. The certificate must have Client Authentication as Extended Key Usage.

• RSASSA-PSS must not be used as the signature algorithm. This can be verified in a certificate, by checking the signature algorithm. SHA256 is the preferred signature algorithm, and SHA1 is also supported.

Versions

The internal version number of the connector is shown as file- and product version of MSCAConnector.dll.

In Smart ID 21.04, the MSCAConnector was released in sync with Identity Manager builds and you can deploy a matching version of the connector for your Identity Manager. Current connector versions can also be used with older Identity Manager releases. If any new release should break backwards-compatibility, it will be noted here.

Set up service account

A service account must be created in ADCS, for example PRIME_ADCS. This account is needed when the ADCS connector connects to the ADCS and when making a certificate request to a certain certificate template. 

Do the following:

Set up a service account according to these requirements:

• Needs to be a Domain User

• Needs to be member of the local group IIS_USRS on the IIS Server

• Needs to have the following access in the ADCS CA, see the screenshot below.

  • Read

  • Issue and Manage Certificates

  • Request Certificates

• Needs to have the following access in the Certificate Templates that Identity Manager will use, see the screenshot below.

  • Read

  • Enroll

Prepare certificates

1. Export CA certificates: Export all the CA chain certificates to file, either encoded as DER or Base64. For example, export the Root CA, Intermediate, and Issuing CA. These certificates are needed for later purpose.

2. Issue a web server certificate with server authentication. This is needed since the ADCS connector must have SSL/TLS enabled.

3. Issue a Identity Manager Virtual Registration Officer (VRO) certificate: This is needed since when Identity Manager requests a certificate it will authenticate to the connector using a certificate. Set Extended key usage to Client Authentication. If needed, create a certificate template in ADCS for this purpose. In the certificate template, set that the Private Key may be exported.

4. Export the Identity Manager VRO certificate and the key to a .PFX file.

Configure port

Open the ADCS connector SSL/TLS port on the Identity Manager server and on the Identity Manager server, set up access to the ADCS connector SSL/TLS port, by default 444.

Install connector for IIS

Treat an update as a re-installation, that is:

1. Stop the connector in IIS.

2. Make a full backup of the existing connector, including all configuration files.

3. Remove all DLLs from the bin sub-folder of the connector folder.

4. Install the new files, overwriting any existing files.

5. Reconfigure the new Web.config.
   Starting from 21.04.2, you can remove the loglevel entry from this file as log4net is now used.

6. Reconfigure the new MSCAConnector.dll.log4net.dll (since 21.04.2), especially set the absolute path to the log file.

7. Fully review the configuration of IIS, especially regarding the required .net runtime version. For more information, see the sections below.

8. Start the connector in IIS once the configuration is done.

 Otherwise you might end up in an inconsistent state with outdated leftover DLLs or a Web.config that does not match your .net version.

To install the connector for Internet Information Services (IIS):

1. Unzip the installation package for the ADCS connector, for example in C:\Nexus\connector_adcs:
   

   

2. Create a temp folder in the installation folder of the ADCS connector.

3. Copy the Identity Manager VRO certificate (not the key) into the folder cert.

4. Open the file Web.config and edit the following part. Make sure to type the absolute path to the ClientcertFile.

   Example: web.config

   XML

   <appSettings>
       <add key="TempDir" value="C:\Nexus\connector_ADCS\temp\" />
       <!-- the loglevel entry is obsolete since IDM 21.04.2 -->
       <add key="ClientcertFile" value="C:\Nexus\connector_ADCS\cert\prime_officer1_adcs.cer" />
       <add key="KraDir" value="C:\Nexus\connector_ADCS\cert\" />
   	<!-- further settings go here -->
   </appSettings>

5. Open the file MSCAConnector.dll.log4net.xml and edit it. It uses standard log4net syntax. Make sure you set the absolute path to the log-file, which has to be writable by the connector/IIS.

   MSCAConnector.dll.log4net.xml example

   XML

   <?xml version="1.0" encoding="utf-8" ?>
   <log4net debug="false">
     
     <appender name="LogFileAppender" type="log4net.Appender.FileAppender" >
       <file value="c:\inetpub\ADCSConnector\logs\MSCAConnector.log" />
       <appendToFile value="true" />
       <layout type="log4net.Layout.PatternLayout">
         <conversionPattern value="(%d) %-5p [%t] (%logger) : %m%n" />
       </layout>
     </appender>
       
     <root>
       <level value="DEBUG" />
       <appender-ref ref="LogFileAppender" />  
     </root>
   </log4net>

Optional connector configuration

The following item can optionally be configured in the <appSettings>-section of Web.config:

Disable FIPS-compliant key generation, which is otherwise used by default, starting with version 1.0.0.188:

<add key="FipsKeyGen" value="false" />

Configure IIS

To configure the IIS:

1. Create a new site called ADCS Connector and point the root to the folder where you unzipped the connector, for example C:\Nexus\connector_adcs.

2. Edit the binding of the site and add the HTTPS port 444 and select the corresponding SSL/TLS certificate. If it not listed, you may have to import the certificate to the computer certificate store. 

On Windows Server 2022 and later, you must disable TLS 1.3 over TCP on the binding to avoid connection failures.

3. Select the site and select SSL Settings. Enable Require SSL, select Require, and click Apply.

4. Go to Application Pools, select the ADCS Connector application pool, and click on Advanced settings in the right pane.

   1. Set .NET Framework version to 4.0 (this version is used since connector version 1.0.0.188).

   2. Change Identity to the service account that you have created.

   3. Click OK.

5. Restart the IIS service.

Test the ADCS Connector

1. Import the Identity Manager VRO certificate in the personal trust store in Windows.

2. Open a browser and browse to https://<yourhost>:444/MSCAConnectorImpl.svc.

3. Authenticate with the certificate.

You should see this page:

Limitations

Supported DN attributes

ADCS might ignore certain DN attributes contained in a certificate request, causing them to be missing from the issued certificate.

For example, in Windows Server 2016 it only supports the following set of attributes:

• CN (common name)

• E (email)

• O (organization)

• OU (org. unit)

• L (locality)

• ST (state)

• C (country)

Set up the ADCS CA connector in Identity Manager

Set up ADCS connector in PRIME

To configure the PKI web service interface used for the chip encoding module:

1. Log in to Identity Manager Admin.

2. Go to Home > Certification Authorities (CA).

3. Click +New to create a new certificate authority for ADCS.

4. Do the following updates:

   1. Select Connection type 'CA proxy'

   2. In CA Host, enter the machine name, followed by a backslash and the CA name, in this form: <CA host name>\<CA name>.
      Example: CA Host
      10.x.x.x\ConsultingMSCA2012

   3. Set Webservice URL to the hostname or IP of the server hosting the MSCA Connector IIS application.
      Example: Webservice URL
      https://<caconnectorhost>:444/MSCAConnectorImpl.svc/

   4. Enter Signing password and Recovery password.

   5. In Client Certificate, select the SSL client certificate (in .pfx or .p12 format) used for the 2-way authentication on the Webservice URL. It must fit to the client certificate configured on IIS-side.

   6. In Server Certificate, select the .cer file of the SSL IIS server certificate, which is used under the Webservice URL. It is used to validate the connection.

It is highly recommended to configure the Webservice URL as an https connection with client authentication.

Make sure that the setup is correct. If some of the following parameters are not correct the card production will fail because the connection to the web service will be rejected:

• The hostname in the URL must fit the Common Name in the SSL server certificate.

• The certificates must be valid and not revoked.

• The CRLs must be available for verification.

• CA and ADCS CA connector must be either in the same machine or the same domain.

Import certificate types

Each PKI provides predefined certificate types. In Microsoft ADCS, they are called Certificate Templates.

To import the certificate types:

1. Go to Details.

2. Click the magnifier icon to display the certificate types in ADCS.

3. Click Apply to import the certificate types. The imported certificate types are now listed in Certificate Types.

When you create a certificate template in Identity Manager Admin, then the imported certificate types are available to choose from.

Create elliptic curve keys

The usage of elliptic curve key is controlled through the key size of the certificate. The key size can be configured in the attributes of the certificate in Identity Manager Admin and can be overridden within encoding descriptions.

Supported curves

Additional information

• About the Identity Manager ADCS integration

• Integrate Identity Manager with certificate authority (CA)

• Smart ID Identity Manager