PingOne Platform APIs

Certificate Management

The certificate management service manages two types of records, keys and certificates. Keys represent a key pair that consists of a private key and a public key. A certificate represents the electronic document used to verify the owner of the public key. This service supports FIPS 140-2 Level 1 compliant security algorithms to generate key pairs, and manages:

  • Customer-provided certificates

  • Customer-provided signing and encryption keys

  • PingOne-generated certificates (PKI)

  • PingOne-generated signing and encryption keys

  • Key rotation policies

The certificate management service also manages encryption and decryption operations, as well as signing and validation operations.

To use any of the PingOne signing and encryption features, you’ll need to either provide a certificate you’ve generated, or configure the options for a PingOne-signed certificate. When uploading certificates, the certificate must be valid at the time of upload. You cannot upload a certificate before its validity period begins (the certificate’s NotBefore date), or after it expires (the certificate’s NotAfter date). The private key must be unencrypted. You cannot upload a private key that is protected by a password or passphrase. The certificate, private key, and certificate chain must all be PEM-encoded unless uploading a PKCS12 file format.

For endpoints that return binary data, it is recommended that clients use the Accept request header to specify that the client can also receive an application/json response (for example, Accept: application/x-x509-ca-cert, application/json). This addition to the Accept header prevents 404 NOT_FOUND errors that can be returned by the API gateway as 500 UNEXPECTED_ERROR messages.

Default organization and environment certificates

The certificate management service creates default certificates for PingOne organization, and environment resources.

Default organization certificate

The certificate management service listens for the "create organization" event, and when the organization is created, the certificate management service creates a default intermediate CA signing certificate for the organization resource. This default org certificate is used to sign all environment certificates.

The default organization certificate includes the following values:

Property Value

version

V3 (2)

serialNumber

Secure Random generated

algorithmID

sha256WithRSAEncryption

issuer

commonName: Ping Identity v2; organizationalUnit: www.pingidentity.com; organization: Ping Identity Corporation; country: US

subject

commonName: value; Organization Name: value; organizationalUnit: value; organization: value; country: value

validity

not before: current date, not after: 1 year from current date

extensions

none

Default environment certificate

The service also listens for "create environment" events and creates the default key and certificate for the environment resource. The default organization certificate signs all environment certificates.

The default environment certificate includes the following values:

Property Value

version

V3 (2)

serialNumber

Secure Random generated

algorithmID

sha256WithRSAEncryption

Default environment key

The default environment key includes the following values:

Property Value

algorithm

RSA

validity period

1 year

key length

2048

Certificate management data model

Property Type Required? Mutable? Description

algorithm

String

Required

Immutable

The key algorithm. Options are RSA, EC, and UNKNOWN.

createdAt

Date

N/A

Read-only

The time the resource was created.

default

Boolean

Required

Mutable

Indicates whether this is the default key for the specified environment.

environment.id

String

Required

Immutable

Specifies the environment resource’s unique identifier.

expiresAt

Date

N/A

Read-only

The time the key resource expires.

id

String

Required

Immutable

The resource’s unique identifier.

issuerDN

String

Required

Mutable

The distinguished name (DN) of the certificate issuer.

keyLength

Integer

Required

Immutable

The key length. For RSA keys, options are 2048, 3072, 4096, and 7680. For elliptical curve (EC) keys, options are 224, 256, 384, and 521.

name

String

Optional

Mutable

The resource name.

organization.id

String

Required

Immutable

The organization resource’s unique identifier.

serialNumber

Integer

Required

Immutable

The serial number of the key or certificate.

signatureAlgorithm

String

Required

Immutable

The signature algorithm of the key. Options are SHA256withRSA and SHA512withRSA.

startsAt

Date

Required

Immutable

The time the validity period starts.

status

String

N/A

Read-only

The status of the key. Options are VALID, EXPIRED, NOT_YET_VALID, and REVOKED. If the current time is within 2 weeks of the expiration date, the status is EXPIRING.

subjectDN

String

Required

Immutable

The DN of the subject being secured.

trustChain

String[]

Optional

Mutable

An array of PEM-encoded X509 Certificates that are in the trust chain of the key’s chain of trust.

usageType

String

Required

Mutable

Specifies how the certificate is used. Options are ENCRYPTION, SIGNING, ISSUANCE, SSL_TLS, and OUTBOUND_MTLS. ISSUANCE keys are used as part of another key’s trust chain, and are used to sign other keys. Certificate Revocation Lists (CRL) are published against these keys. SSL_TLS keys are used to protect internet protocol domains (such as, a Custom Domain you’ve configured in PingOne). OUTBOUND_MTLS keys are used to enable mutual TLS (mTLS) authentication with a subscription service.

validityPeriod

Integer

Required

Immutable

The number of days the key is valid.

Certificates and keystore events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

404

The requested resource was not found.