Certificate Request Process

Last updated on September 9, 2021.

Document Status: Document Developer Quality Complete.

Introduction

The goal of this article is to describe the workflow to request and retrieve certificates from a Certification Authority (CA) using RPS. It is a data-driven process that uses RPS CMDB to take the existing certificate resource items and generate certificate signing requests (CSRs) and then retrieve the certificates from the CA. Throughout the process, the CMDB is updated with the responses from the CA.

The RPS certificate request process pairs with Certificate Rolling and should be performed prior to certificate rolling in order to roll with CA signed certificates. See Certificate Rolling for more details on rolling certificates.

Prerequisites

In order for the Certificate Request Process to work, the following prerequisites must be in place. Please see RPS Certificate Management Technical Design for additional details on RPS Certificate Management architecture.

• RPS Web API host running on a node, for example NOSC, (see DSC Configuration ContentStore\Dsc\PartialConfigurations\RpsWebApi.ps1), with the following plugins present under ContentStore\RpsWebApi\Plugins:
  • .\Rps.Api.Rest.RpsPlugin
  • .\Rps.CertificateManager.RpsPlugin
• RPS Web API host running on a server with the following:
  • Network access to the intended Active Directory Certificate Services (AD CS) Certification Authority (CA).
  • See Certificate Request Plugin Configuration for details on Rps.CertificateRequest.RpsPlugin configuration.
• Active Directory Certificate Services Certification Authority installed and configured, for example DCA.
• AD CS CA certificate templates created for the supporting RPS certificates. See the Generic Role Templates section in Certificate Usage for details on template requirements.

CA Enabled Certificate Resource Items

The RPS Certificate Request process will take action on ResourceItems of Type Certificate and have a property SigningType = 'CaSigned'. RPS Certificate Manager will take appropriate action based on the RequestStatus property value of each ResourceItem, as described in the table below. RPS Certificate Manager will set the values to Pending and Complete when appropriate, but new ResourceItems with SigningType = 'CaSigned' should have their RequestStatus = 'NotRequested'.

RequestStatus	Action	Description
NotRequested	Create a CSR.	This should be the initial value.
Pending	Retrieve the certificate public key from the CA.	This value will be set after a CSR has been successfully submitted to the CA.
Complete	No action taken.	Once the public key has been successfully retrieved from the CA, this value will be set.

New-RpsCASignedResource

The recommended method to create the CA Enabled Certificate ResourceItems is using the New-RpsCASignedResource function from Rps-Encryption module. The function will use from existing certificate ResourceItems to generate a CA Enabled certificate ResourceItem that will be signed by a certificate authority. The created resource item will be based on an existing certificate resource item properties that would be needed to create a CSR to fulfill an appropriate certificate for the respective role.

Example

The following example would take all Certificate ResourceItems that are not CASigned or have the role RpsRoot and generated the necessary CA Enabled Certificate ResourceItems:

$certificates = Get-RpsResourceItem -Type $Rps.ResourceTypes.Certificate | Where-Object -FilterScript {$_.SigningType -ne 'CASigned' -band $_.Role -ne 'RpsRoot'}
$certificates | New-RpsCASignedResource

Process Certificates REST Endpoint

The certificate request process is initiated by using a REST client to invoke the ProcessCertificates endpoint on the RPS Certificate Manager plugin. Any REST client can be used, but this article will be using the PowerShell cmdlet Invoke-RestMethod to make the REST request.

REST Parameters

Name	Type	Description
NodeId	Guid	The node ID to request certificates for.
CaName	String	The Certification Authority name to submit requests to. Example format of a CA Name would be AD.unit.domain\TPKI-LAB-DCA-CA.

Example

The following example shows how to request certificates from the NOSC for a child node like TCN.

$node = Get-RpsNode -Name NOSC
$childNode = Get-RpsNode -Name TCN

# Get the active client authentication certificate for the NOSC CertManager REST Endpoint
$targetItem = Get-RpsTargetItem -Type VirtualMachine -Name nosc.rps.local
$clientAuthCertificate = Get-RpsResourceItem -Type Certificate -Role 'CertManager' -TargetItem $targetItem -IsActive $true

$processCertificatesParameters = @{
    # The URI and parameters for the certificate manager endpoint.
    Uri = "https://nosc.rps.local:777/CertManager/v1.0/CertificateManager/ProcessCertificates/?nodeId=$($childNode.Id)&caname=$($node.CertificateAuthorityName)"
    # The certificate for this corresponding thumbprint must be installed in either the Computer or User MY cert store.
    CertificateThumbprint = $clientAuthCertificate.thumbprint
}

# Use Invoke-RestMethod cmdlet to initiate the certificate request process
Invoke-RestMethod @processCertificatesParameters