Advanced Identity Cloud

Certificate Validation node

The Certificate Validation node validates a digital X.509 certificate collected by the Certificate Collector node.

Certificate validation rules

  • If you add this node to a journey, you must configure it. With no configuration, the node returns True as the outcome by default, regardless of the validity of the certificate provided in the journey.

  • This node validates the first certificate in a certificate chain (the user certificate) and ignores the remaining certificates in the chain.

  • If the collected user certificate is a self-signed certificate (test environments only), the self-signed user certificate must be present in the truststore for certificate validation to succeed.

  • If the collected user certificate is signed by a valid issuer, the issuing certificates (intermediate, or intermediate and root) must be present in the truststore for certificate validation to succeed.

  • If the user certificate is signed by a valid issuer and the issuing certificate (intermediate certificate) is not present in the truststore, certificate validation fails.

  • The node uses the intermediate and user certificates to verify certificate revocation status.

Compatibility

Product Compatible?

Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

This node requires an X509Certificate property in the incoming node state.

Implement the Certificate Collector node as input to the Certificate Validation node.

Configuration

Property Usage

Match Certificate in LDAP

When enabled, PingOne Advanced Identity Cloud matches the collected certificate with a certificate stored in the identity store.

Set the Subject DN Attribute Used to Search LDAP for Certificates to specify which LDAP property to search for certificate information.

Default: Disabled

Check Certificate Expiration

When enabled, PingOne Advanced Identity Cloud checks if the collected certificate has expired.

Default: Disabled

Subject DN Attribute Used to Search LDAP for Certificates

The attribute PingOne Advanced Identity Cloud uses to search the identity store for the certificate. The search filter is based on this attribute and the value of the Subject DN as it appears in the certificate.

Default: CN

Match Certificate to CRL

When enabled, PingOne Advanced Identity Cloud checks if the collected certificate has been revoked according to a Certificate Revocation List (CRL) in the identity store.

Define related CRL properties later in the node configuration.

Default: Disabled.

Issuer DN Attribute(s) Used to Search LDAP for CRLs

The name of the attribute or attributes in the issuer certificate that PingOne Advanced Identity Cloud uses to locate the CRL in the identity store.

  • If you specify only one attribute here, the LDAP search filter used is (attr-name=attr-value-in-subject-DN).

    For example, if the subject DN of the issuer certificate is C=US, CN=Some CA, serialNumber=123456, and the attribute specified is CN, PingOne Advanced Identity Cloud uses a search filter of (CN=Some CA) to locate the CRL.

  • Specify several CRLs for the same CA issuer in a comma-separated list (,) where the names are in the same order in which they appear in the subject DN.

    In this case, the LDAP search filter used is (attr1=attr1-value-in-subject-DN,attr2=attr2-value-in-subject-DN,…​), and so on.

    For example, if the subject DN of the issuer certificate is C=US, CN=Some CA, serialNumber=123456, and the attributes specified are CN,serialNumber, the LDAP search filter used to find the CRL is (CN=Some CA,serialNumber=123456).

Default: CN

HTTP Parameters for CRL Update

Parameters PingOne Advanced Identity Cloud includes in any HTTP CRL call to the CA that issued the certificate.

If the client or CA certificate includes the IssuingDistributionPoint extension, PingOne Advanced Identity Cloud uses this information to retrieve the CRL from the distribution point.

Add the parameters as key-value pairs in a comma-separated list (,). For example, param1=value1,param2=value2.

Cache CRLs in Memory

When enabled, PingOne Advanced Identity Cloud caches CRLs in memory.

If this option is enabled, Update CA CRLs from CRLDistributionPoint must also be enabled.

Default: Enabled

Update CA CRLs from CRLDistributionPoint

When enabled, AM fetches new CA CRLs from the CRL Distribution Point and updates them in the identity store. If the CA certificate includes either the IssuingDistributionPoint or the CRLDistributionPoint extensions, PingOne Advanced Identity Cloud attempts to update the CRLs when they’re out of date.

Default: Enabled

OCSP Validation

When enabled, PingOne Advanced Identity Cloud checks the validity of certificates using the Online Certificate Status Protocol (OCSP).

PingAM If you enable this option, the AM instance must be able to connect to the internet. You must also configure OCSP for AM under Configure > Server Defaults > Security > Online Certificate Status Protocol Check.

Default: Disabled

Certificate Identity Store

PingAM Select the identity store (configured for the realm) that AM must search for certificates. If you select an identity store here, AM uses the connection details defined for that identity store and ignores all the server settings below this field.

Advanced Identity Cloud Select the default identity store (OpenDJ) from the list. You must select this identity store to let PingOne Advanced Identity Cloud search for the certificate. PingOne Advanced Identity Cloud ignores all LDAP server settings below this field.

PingAM LDAP Server Where Certificates are Stored

The LDAP server that holds certificates. Enter the server details in the format ldap-server:port .

To associate multiple AM servers in a site with corresponding LDAP servers, use the format am_server|ldapserver:_port_. For example, am.example.com|ldap1.example.com:636.

PingAM LDAP Search Start or Base DN

Valid base DN for the LDAP search, such as dc=example,dc=com. To associate AM servers with different search base DNs, use the format am_server|base_dn. For example, am.example.com|dc=example,dc=com openam1.test.com|dc=test,dc=com.

PingAM LDAP Server Authentication User and LDAP Server Authentication Password

The credentials used to connect to the LDAP directory that holds the certificates.

If you enable mTLS, the node ignores these credentials.

Default Authentication User: cn=Directory Manager

PingAM mTLS Enabled

Enables mTLS (mutual TLS) between AM and the directory server.

When mTLS is enabled, the node ignores the values for LDAP Server Authentication User and LDAP Server Authentication Password.

If you enable this property, you must:

  • Enable Use SSL/TLS for LDAP Access.

  • Provide an mTLS Secret Label Identifier.

Default: Disabled

PingAM mTLS Secret Label Identifier

An identifier used to create a secret label for mapping to the mTLS certificate in the secret store. AM uses this identifier to create a specific secret label for this node. The secret label takes the form am.authentication.nodes.certificate.validation.mtls.identifier.cert , where identifier is the value of mTLS Secret Label Identifier. The label can only contain alphanumeric characters (a-z, A-Z, 0-9) and periods (.). It can’t start or end with a period.

For greater security, you should rotate certificates periodically. When you rotate a certificate, update the corresponding mapping in the realm secret store configuration to reflect this identifier. When you rotate a certificate, AM closes any existing connections using the old certificate. A new connection is selected from the connection pool and no server restart is required.

PingAM Use SSL/TLS for LDAP Access

When enabled, AM uses SSL/TLS to access the LDAP directory. Make sure that AM trusts the certificate from the LDAP server when enabling this option.

Default: Disabled

Outputs

This node doesn’t put anything into the shared state.

Outcomes

True

The node could validate the certificate.

When the outcome is True, add a Certificate User Extractor node to extract the values of the certificate.

False

The node couldn’t validate the certificate. The journey follows this path when the node can’t validate the certificate and no more specific outcome is available.

Not found

The Match Certificate in LDAP property is enabled, but the certificate wasn’t found in the LDAP store.

Expired

The Check Certificate Expiration property is enabled, and the certificate has expired.

Path Validation Failed

The Match Certificate to CRL property is enabled, and the certificate path is invalid.

Revoked

The OCSP Validation property is enabled, and the certificate has been revoked.

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.