Authentication nodes

Certificate Collector node

The Certificate Collector node collects an X.509 digital certificate or a chain of certificates from the incoming request. The journey can then use the collected certificates as authentication credentials for a user or an OAuth 2.0 client.

By default, Advanced Identity Cloud collects the first certificate in a certificate chain (the user certificate).

RAPID only Create an ESV variable named esv-am-nodes-certificatechain-validation-enforced and set its value to true to collect the chain of certificates.

Advanced Identity Cloud accepts certificates in PEM and DER format.

You can’t use this node in isolation because it only collects certificates from the request. It doesn’t extract or validate the certificate’s content. Use a Certificate Validation node to validate certificates and a Certificate User Extractor node to extract the user details from the certificate.

Example

This example shows an authentication journey using a certificate as credentials.

journey certificate auth

  1. The Certificate Collector node attempts to collect the certificate from the request body or the header.

  2. The Certificate Validation node attempts to validate the certificate based on the configuration of that node.

  3. The Certificate User Extractor node extracts the user ID from the certificate and attempts to find a match in the identity store.

    • If the username can be extracted and a matching user is found in the identity store, the journey increments the login count and authenticates the user.

    • If the username can’t be extracted or no matching user is found in the identity store, the journey proceeds to the Failure node.

Availability

Product Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

This node reads the certificate or chain of certificates from the request payload or request header. It doesn’t read anything from the shared state.

Dependencies

This node has no dependencies.

Configuration

Property Usage

Certificate Collection Method

How the node should collect the certificate or chain of certificates from the request. Possible values are:

Request

The node locates the certificates in the request. Use this option if TLS termination happens at Advanced Identity Cloud.

Header

The node locates the certificates in an HTTP header. Specify the header name in the HTTP Header Name for the Client Certificate property. Use this option if TLS termination happens in a proxy or load balancer outside Advanced Identity Cloud.

Either

The node attempts to locate the certificates in the request. If there are no certificates in the request, the node attempts to locate the certificates in the HTTP header specified in HTTP Header Name for the Client Certificate.

Default: Either

HTTP Header Name for the Client Certificate

The name of the HTTP header that contains the certificates. If you set the Certificate Collection Method to Header or Either, you must set a value here.

Default: No value

Trusted Remote Hosts

A list of IP addresses trusted to supply certificates on behalf of the authenticating client, such as load balancers doing TLS termination.

If you don’t set a value here, Advanced Identity Cloud rejects certificates supplied by remote hosts. If you set a value of any, Advanced Identity Cloud trusts certificates supplied by any remote host, on behalf of the authenticating client.

Default: No value

Outputs

The node outputs the X.509 certificate or chain of certificates to the transient state to be consumed by the Certificate Validation node.

Callbacks

This node doesn’t send any callbacks.

Outcomes

Collected

The node was able to collect the certificates.

Not Collected

The node was unable to collect the certificates.

Errors

  • If no certificates are provided in the configured location (either header or request), the node logs the following error:

    Certificate was not successfully collected based on node configuration and client request

  • If there’s a problem with the certificates provided in the header or in the request, the node logs the following error:

    CertificateFromParameter decode failed, possibly invalid Base64 input