Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updates for Smart ID 21.04.2

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

Expandall

Set up the ADCS connector

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

Anchor
ADCSConnectorPrereq
ADCSConnectorPrereq
Prerequisites

Expand
titlePrerequisites

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.


Expand
titleVersions

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

Image Modified

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.

Step-by-step instruction

Expand
titleSet up service account

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:

  1. 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 picture 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 picture below
      • Read
      • Enroll



Expand
titlePrepare certificates

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.


Expand
titleConfigure port

Open the ADCS connector SSL/TLS port on the Identity Manager server:

  1. On the Identity Manager server, set up access to the ADCS connector SSL/TLS port, by default 444.

    From

    To

    Port

    Identity Manager-SERVER

    ADCS Connector (IIS)

    444



Expand
titleInstall connector for IIS


Note

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 overwritten new Web.config (since 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 (see 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 folder temp 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.

    Code Block
    languagexml
    titleExample: web.config
    <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="loglevelKraDir" value="99" />
        <add key="KraDir" value="C:\Nexus\connector_ADCS\cert\" />
    	<!-- further settings go here -->
    </appSettings>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.

    Code Block
    languagexml
    titleMSCAConnector.dll.log4net.xml example
    <?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>
    
    



Expand
titleDo optional connector configuration

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

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

    Code Block
    languagexml
    <add key="FipsKeyGen" value="false" />


  2. Choose the revocation reason to use for the Identity Manager certificate states inactive and locked, which is supported starting with version 1.0.0.191:

    Code Block
    languagexml
    <add key="rfc5280ReasonForInactiveAndLocked" value="unspecified"/>

    By default these Identity Manager states are mapped to unspecified, also supported are:

    1. keyCompromise

    2. caCompromise

    3. affiliationChanged

    4. superseded

    5. cessationOfOperation

    6. certificateHold

      Note

      certificateHold is used for temporary revocation only, thus not recommended here, as locked/inactive are normally used to indicate permanent revocation.



Expand
titleConfigure 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.
  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.


Expand
titleTest the ADCS Connector

To test the ADCS connector:

  1. Import the Identity Manager VRO certificate in the personal truststore in Windows.
  2. Open a browser and browse to https://<yourhost>:444/MSCAConnectorImpl.svc.
  3. Authenticate with the certificate.
  4. You should see this page:
    Image Modified


Expand
titleLimitations

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

Step-by-step instruction

Expand
titleSet 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>.

      Panel
      titleExample: 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.

      Panel
      titleExample: 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.

Note

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.



Expand
titleImport 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 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.
Info

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



This article is valid for Smart ID 21.04.2 and later.

Related information