To connect Smart ID Identity Manager to Active Directory Certificate Services (ADCS), one component needs to be set up - the ADCS Connector - and one component needs to 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.
The following prerequisites apply for the ADCS connector:
- 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 needs to be issued to enable HTTPS on the ISS service for the ADCS connector. Certificate can be either issued via the internal request functionality on IIS or provided as PKCS#12 Softtoken. CN and SAN needs to 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 needs to 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.
The internal version number of the connector is shown as file- and product version of MSCAConnector.dll.
Since Smart ID 21.04 the MSCAConnector is released in sync with Identity Manager builds, which was not the case previously, so you can now always 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.
A service account needs to be created in ADCS, for example
PRIME_ADCS. This account is needed when the ADCS connector connects to the ADCS, and also 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_USRSon the IIS Server
- Needs to have the following access in the ADCS CA, see the picture below
- Issue and Manage Certificates
- Request Certificates
- Needs to have the following access in the Certificate Templates that Identity Manager will use, see the picture below
- 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.
- Issue a web server certificate with server authentication. This is needed since the ADCS connector must have SSL/TLS enabled.
- 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.
- Export the Identity Manager VRO certificate and the key to a .PFX file.
Open the ADCS connector SSL/TLS port on the Identity Manager server:
On the Identity Manager server, set up access to the ADCS connector SSL/TLS port, by default
ADCS Connector (IIS)
Treat an update as a re-installation, that is:
- Stop the connector in IIS.
- Make a full backup of the existing connector, including all configuration files.
- Remove all DLLs from the bin sub-folder of the connector folder.
- Install the new files, overwriting any existing files.
- Reconfigure the new Web.config (since 21.04.2 you can remove the loglevel entry from this file, as log4net is now used)
- Reconfigure the new MSCAConnector.dll.log4net.dll (since 21.04.2), especially set the absolute path to the log file.
- Fully review the configuration of IIS, especially regarding the required .net runtime version (see sections below).
- 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):
- Unzip the installation package for the ADCS connector, for example in C:\Nexus\connector_adcs:
- Create a folder temp in the installation folder of the ADCS connector.
- Copy the Identity Manager VRO certificate (not the key) into the folder cert.
Open the file Web.config and edit the following part. Make sure to type the absolute path to the
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.
The following items 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 126.96.36.199:
Choose the revocation reason to use for the Identity Manager certificate states inactive and locked, which is supported starting with version 188.8.131.52:
By default these Identity Manager states are mapped to unspecified, also supported are:
certificateHold is used for temporary revocation only, thus not recommended here, as locked/inactive are normally used to indicate permanent revocation.
To configure the IIS:
- 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.
- Edit the binding of the site and add the HTTPS port
444and select the corresponding SSL/TLS certificate. If it not listed, you may have to import the certificate to the computer certificate store.
- Select the site and select SSL Settings. Enable Require SSL, select Require, and click Apply.
- Go to Application Pools, select the ADCS Connector application pool, and click on Advanced settings in the right pane.
- Set .NET Framework version to 4.0 (this version is used since connector version 184.108.40.206).
- Change Identity to the service account that you have created.
- Click OK.
- Restart the IIS service.
To test the ADCS connector:
- Import the Identity Manager VRO certificate in the personal truststore in Windows.
- Open a browser and browse to https://<yourhost>:444/MSCAConnectorImpl.svc.
- Authenticate with the certificate.
- You should see this page:
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)
OU (org. unit)
Set up the ADCS CA connector in Identity Manager
To configure the PKI web service interface used for the chip encoding module:
- Log in to Identity Manager Admin.
- Go to Home > Certification Authorities (CA).
- Click +New to create a new certificate authority for ADCS.
Do the following updates:
Select Connection type 'CA proxy'
In CA Host, enter the machine name, followed by a backslash and the CA name, in this form: <CA host name>\<CA name>.
Set Webservice URL to the hostname or IP of the server hosting the MSCA Connector IIS application.
Enter Signing password and Recovery password.
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.
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.
Each PKI provides predefined certificate types. In Microsoft ADCS, they are called Certificate Templates.
To import the certificate types:
- Go to Details.
- Click to display the certificate types in ADCS.
- 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.