Table of Contents

AdcsRequestCertificateValve

This valve can be used to send a CSR towards an ADCS server in order to issue a certificate. The CSR must have been created previously, for example with the CSRGeneratorValve

Remarks

Per item

This will execute once per item - you must have at least one item inte the flow before executing this valve. You can create an item if needed, for example with the ItemCreateValve or ItemCreateFromRequestValve (place the valve that creates the item before this valve in the pipe).

Properties

Name Description Default value Mandatory Supports property expansion
httpSocketTimeoutMs The low level socket timeout for connecting to the server in milliseconds. 2000 Yes
httpConnectTimeoutMs The timeout for connecting HTTP in milliseconds. 4000 Yes
httpRequestTimeoutMs The timeout for the request to finish in milliseconds. 8000 Yes
tlsVersion The allowed TLS version(s) TLSv1.3 Yes
tlsKeystoreId If client certificate authentication should be used: id of the keystore to use for client certificate for mTLS (also make sure that IIS is configured to actually try to negotiate client certificates.) Yes
tlsTruststoreId Id of the keystore to use for certificate verification of the TLS server. If not configured, the default trust store is used. Yes
tlsTrustAll If no verification of the TLS server's certificate should be done.
Please note, this is dangerous to enable since it might make MitM attacks possible		 false Yes
authUsername If username and password authentication should be used: the username Yes
authPassword If username and password authentication should be used: the password Yes
serviceAddress The full address of the web service, ex: https://win-r2uflohjv30.forest.phenixid.local/forest-WIN-R2UFLOHJV30-CA_CES_UsernamePassword/service.svc/CES or https://build-windows-adcs-test-target.phenixid.se/adcs-test-BUILD-WINDOWS-A-CA_CES_Certificate/service.svc/CES Yes Yes
adcsCertificateTemplate The certificate template that ADCS should use to issue the certificate. Will get embedded into the generated CSR. Yes Yes
csr The CSR to send to ADCS. PEM-encoded. Yes Yes
targetCertificatePropertyName Name of the property in the item where the generated certificate shall be written as a PEM-encoded X.509 certificate
targetCertificateChainPropertyName Name of the property in the item where the entire certificate chain shall be written as a PEM-encoded PKCS#7

Example configuration

{      
  "name": "AdcsRequestCertificateValve",
  "enabled": "true",
  "config": {
    "serviceAddress": "https://build-windows-adcs-test-target.phenixid.se/adcs-test-BUILD-WINDOWS-A-CA_CES_Certificate/service.svc/CES",
    "adcsCertificateTemplate": "MyCertificateTemplate",
    "csr": "{{item.csr}}",
    "tlsTruststoreId": "TruststoreForTheCA",
    "tlsKeystoreId": "KeystoreForADUser",
    "targetCertificatePropertyName": "myCertificate"
  }
}

In the example above, we will make a request towards ADCS where we authenticate using a certificate. The CSR has been generated previously and can be found in the property csr in the item(s). The generated certificate will be stored in the property myCertificate in each item.

Requirements

  • The ADCS server must have been configured previously.
    • Setup custom certificate templates where the subject is provided in the request.
  • The Certificate Enrollment Service must be configured.
    • Both certificate based (mTLS) and plaintext authentication using username and password is supported.
      • For certificate based authentication, ensure that IIS is configured to negotiate client certificate authentication for TLS. The certificate used must be issued for a user in the AD with correct permissions for the certificate template(s) to issue
      • For username and password based authentication, the user must have correct permissions for the certificate template(s) to issue.
  • The ADCS server must be running in enterprise mode.
    • The Certificate Enrollment Service requires that ADCS is running in enterprise mode.
    • Certificate templates are only supported when ADCS is running in enterprise mode.
    • It is possible to let the ADCS server also be a domain controller for a small AD, acting as an intermediate CA to some other CA in order to achieve this - the only requirement is that ADCS and CES (Certificate Enrollment Service) are members of the same AD. This is achieved if both AD, ADCS and CES are deployed on the same server.
  • The CSR must have been generated previously
Valve X509 (Certificates)