Authentication nodes

Certificate Collector node

The Certificate Collector node collects a chain of X.509 digital 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.

Advanced Identity Cloud accepts certificates in PEM and DER format.

Version 1.0 of this node collects only the first certificate in a certificate chain (the user certificate) and ignores the remaining certificates in the chain. To collect all certificates in the chain, upgrade to v2.0 of the node.

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 chain from the request body or the header.

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

  3. The Certificate User Extractor node extracts the user ID from the certificates 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 Advanced Identity Software (self-managed)

Yes

Inputs

This node reads the 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 Availability

Certificate Collection Method

How the node should collect the 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

All node versions

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

All node versions

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

All node versions

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

The node can log the following errors:

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

    No certificates are provided in the configured location (either header or request).

  • CertificateFromParameter decode failed, possibly invalid Base64 input

    There’s a problem with the certificates provided in the header or in the request.

Changelog

Version Changes

2.0 RAPID only

Security hardening