Certificate management


Certificate management

The certificate management endpoints provides an implementation that supports FIPS 140-2 Level 1 compliant security algorithms to generate key pairs. The service manages:

  • Customer-provided certificates
  • Customer-provided signing/encryption keys
  • Ping-generated certificates (PKI).
  • Ping-generated signing/encryption keys.

The certificate management service listens for the “create organization” event, and when the organization is created, the certificate management service creates a default key and certificate for the organization resource. The default organization certificate includes the following details:

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

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 details:

Property Value
version V3 (2)
serialNumber Secure Random generated
algorithmID sha256WithRSAEncryption

The default environment key includes the following details:

Property Value
algorithm RSA
validity period 1 year
key length 2048

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.

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

Certificate management API operations

The certificate management endpoints support the following operations:

For hands-on experience with the certificate management API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Certificate management data model

Property Description
algorithm A string that specifies the key algorithm. Options are RSA, EC, and UNKNOWN.
createdAt The time the resource was created.
defaultKey A string that specifies the default key type. Options are SIGNING, ENCRYPTION, and NONE.
environment.id A string that specifies the environment resource’s unique identifier.
expiresAt The time the key resource expires.
id A string that specifies the resource’s unique identifier.
issuerDN A string that specifies the distinguished name of the certificate issuer.
keyLength An integer that specifies the key length. For RSA keys, options are 2048, 3072, and 7680. For elliptical curve (EC) keys, options are 224, 256, and 384.
name A string that specifies the resource name.
org.id A string that specifies the organization resource’s unique identifier.
serialNumber An integer that specifies the serial number of the key.
signatureAlgorithm A string that specifies the signature algorithm of the key. Options are SHA256withRSA and SHA512withRSA.
startsAt The time the validity period starts.
status A string that specifies the status of the key. Options are VALID, EXPIRED, NOT_YET_VALID, and REVOKED.
subjectDN A string that specifies the distinguished name of the subject being secured.
validityPeriod An integer that specifies the number of days the key is valid.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request was invalid.
404 The specified object doesn’t exist.
409 Uniqueness constraint violation (for example, duplicate name).

Endpoint examples

Get certificates

The GET /environments/{environmentId}/certificates endpoint returns a list of all certificate resources for the specified environment.

The following sample returns the complete list of certificate resources associated with the environment ID specified in the request URL:

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/certificates" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
  "_embedded": {},
  "_links": {
    ...
    }
  },
  "algorithm": "RSA",
  "createdAt": "2018-11-28T21:38:31.819Z",
  "expiresAt": "2018-11-28T21:38:31.819Z",
  "id": "string",
  "issuerDN": "string",
  "keyLength": 0,
  "name": "string",
  "serialNumber": 0,
  "signatureAlgorithm": "SHA256withRSA",
  "startsAt": "2018-11-28T21:38:31.819Z",
  "status": "VALID",
  "subjectDN": "string",
  "validityPeriod": 0
}

Get one certificate

To get data for a specific environment certificate, the GET /environments/{environmentId}/certificates/{certificateId} operation returns data for the certificate resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/certificates/{certificateId}" \
-H "Content-type: application/x-pkcs7-certificates" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
  "algorithm": "RSA",
  "createdAt": "2018-11-28T21:38:31.819Z",
  "expiresAt": "2018-11-28T21:38:31.819Z",
  "id": "string",
  "issuerDN": "string",
  "keyLength": 0,
  "name": "string",
  "serialNumber": 0,
  "signatureAlgorithm": "SHA256withRSA",
  "startsAt": "2018-11-28T21:38:31.819Z",
  "status": "VALID",
  "subjectDN": "string",
  "validityPeriod": 0
}

Create certificates

The POST /environments/{environmentId}/certificates operation creates a new environment certificate resource for the specified environment. It creates a certificate from an upload of a pkcs7 file with public and trust certificates. Properties returned in the response are parsed from the uploaded file.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/certificates" \
-H 'Accept: application/x-pkcs7-certificates \
-H 'Authorization: Bearer jwtToken' \
-d '{
  "<filename>"
}'

The response returns a 202 Accepted message and shows the certificate data parsed from the uploaded certificate file.

Create an organization signing key

The POST /organizations/{organizationId}/keys operation creates an organization’s signing key that is used to sign all environment certificates.

curl -X "POST" "https://api.pingone.com/v1/organizations/{organizationId}/keys" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
  "name": "string"
}'

The response data looks like this:

{
  "_embedded": {},
  "_links": {
    ...
    }
  },
  "algorithm": "RSA",
  "createdAt": "2018-11-28T23:44:54.553Z",
  "defaultKey": "SIGNING",
  "environment": {
    "id": "string",
    "name": "string",
    "organization": {
      "id": "string",
      "name": "string"
    }
  },
  "expiresAt": "2018-11-28T23:44:54.553Z",
  "id": "string",
  "issuerDN": "string",
  "keyLength": 0,
  "name": "string",
  "organization": {
    "id": "string",
    "name": "string"
  },
  "serialNumber": 0,
  "signatureAlgorithm": "SHA256withRSA",
  "startsAt": "2018-11-28T23:44:54.553Z",
  "status": "VALID",
  "subjectDN": "string",
  "validityPeriod": 0
}

Get JWKS keys

The GET /environments/{environmentId}/jwks endpoint returns a list of all JWKS key resources for the specified environment.

curl -X "GET" "https://api.pingone.com/environments/{environmentId}/jwks" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this.

{
    "keys": [
        {
            "kty": "RSA",
            "e": "AQAB",
            "use": "sig",
            "kid": "40e6c099-20dd-4763-be84-a5d9fd30f3ba",
            "n": "41S8F4ht16MQp51XiK-fogVx0xD8yywtLKdD438pJD4SdCQBd1_7RrEMS7691AY4uzm8fkaweYALWb8qgNgj5hkBizEKBO1wVnz0bBpUd8W5qCPxSLgEzxKNCZ7gOVftUJRM27A14yC5KFMi7-cmHEOAkdzsnAa3KUwZ6zm8JcpF6dw71MQXbAnXHP2dy4N7NH5I5Cb7z8hkpjY5uKzME5_EjZbvuMCi6nZvzyXxT-phK5BKc-Rq50QQERf2VpYZcZ9o8HoXBmiTbpsyhug4lek0NyhL_qkrEfQZrUcfoeeBNegAN4Oz4JQ2I5HxbaNYXPGqkvJ-eNL7HUQqf0vbhQ"
                }
    ]
}

Get keys

The GET /environments/{environmentId}/keys endpoint returns a list of all key resources for the specified environment.

The following sample returns the complete list of key resources associated with the environment ID specified in the request URL:

curl -X "GET" "https://api.pingone.com/environments/{environmentId}/keys" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

Get one key

To get data for a specific environment key, the GET /environments/{environmentId}/keys/{keyId} operation returns data for the key resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/keys/{keyId}" \
-H "Content-type: application/pks7-mime" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/e3493291-6c8c-491d-beb5-dfa098f48c5a/keys/e3dcdb60-b68b-46b4-a067-1fffee8d7b10"
        }
    },
    "id": "e3dcdb60-b68b-46b4-a067-1fffee8d7b10",
    "name": "test cert",
    "serialNumber": 1543524111490,
    "issuerDN": "CN=org_name, OU=Ping Identity, O=Ping Identity, C=US",
    "subjectDN": "CN=org_name, OU=Ping Identity, O=Ping Identity, C=US",
    "algorithm": "RSA",
    "keyLength": 2048,
    "createdAt": "2018-11-29T20:41:51.490Z",
    "expiresAt": "2019-11-29T20:41:51.490Z",
    "startsAt": "2018-11-29T20:41:51.490Z",
    "validityPeriod": 365,
    "signatureAlgorithm": "SHA256withRSA",
    "defaultKey": "SIGNING",
    "status": "VALID",
    "organization": {
        "id": "f3493291-6c8c-491d-beb5-dfa098f48c5a"
    },
    "environment": {
        "id": "e3493291-6c8c-491d-beb5-dfa098f48c5a"
    }
}

Create keys

The POST /environments/{environmentId}/keys operation creates a new environment key resource for the specified environment.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/keys" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "name": "test cert",
  "serialNumber": 1541164068511,
  "issuerDN": "CN=Ping Identity, OU=Ping Identity, O=Ping Identity, C=US",
  "subjectDN": "CN=org_name, OU=Ping Identity, O=Ping Identity, C=US",
  "algorithm": "RSA",
  "keyLength": 2048,
  "startsAt": "2018-11-02T13:07:48.511Z",
  "validityPeriod": 365,
  "signatureAlgorithm": "SHA256withRSA",
  "defaultKey": "SIGNING",
  "status": "VALID"
}'

For the subjectDN attribute, a valid DN must contain commonName, organization, organizationUnit, city, state, and country (CN=commonName, O=organization, OU=organizationUnit, C=country, ST=state, L=city).

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/e3493291-6c8c-491d-beb5-dfa098f48c5a/keys/e3dcdb60-b68b-46b4-a067-1fffee8d7b10"
        }
    },
    "id": "e3dcdb60-b68b-46b4-a067-1fffee8d7b10",
    "name": "test cert",
    "serialNumber": 1543524111490,
    "issuerDN": "CN=org_name, OU=Ping Identity, O=Ping Identity, C=US",
    "subjectDN": "CN=org_name, OU=Ping Identity, O=Ping Identity, C=US",
    "algorithm": "RSA",
    "keyLength": 2048,
    "createdAt": "2018-11-29T20:41:51.490Z",
    "expiresAt": "2019-11-29T20:41:51.490Z",
    "startsAt": "2018-11-29T20:41:51.490Z",
    "validityPeriod": 365,
    "signatureAlgorithm": "SHA256withRSA",
    "defaultKey": "SIGNING",
    "status": "VALID",
    "organization": {
        "id": "f3493291-6c8c-491d-beb5-dfa098f48c5a"
    },
    "environment": {
        "id": "e3493291-6c8c-491d-beb5-dfa098f48c5a"
    }
}

Note: Instead of posting the key attributes in the request body, this operation also supports the application/x-pkcs12-certificates media type to upload a pkcs12 file.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/keys" \
-H 'Accept: application/x-pkcs12-certificates \
-H 'Authorization: Bearer jwtToken' \
-d '{
  "<filename>"
}'

Update keys

The PUT /environments/{environmentId}/keys/{keyId} operation updates the current key to be the default signing or encryption key for an environment.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/keys/{keyId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "defaultKey": "ENCRYPTION"
}'

The response data shows the update to the defaultKey property.

{
    "id": "e3dcdb60-b68b-46b4-a067-1fffee8d7b10",
    "name": "test cert",
    "serialNumber": 1543524111490,
    "issuerDN": "CN=org_name, OU=Ping Identity, O=Ping Identity, C=US",
    "subjectDN": "CN=org_name, OU=Ping Identity, O=Ping Identity, C=US",
    "algorithm": "RSA",
    "keyLength": 2048,
    "createdAt": "2018-11-29T20:41:51.490Z",
    "expiresAt": "2019-11-29T20:41:51.490Z",
    "startsAt": "2018-11-29T20:41:51.490Z",
    "validityPeriod": 365,
    "signatureAlgorithm": "SHA256withRSA",
    "defaultKey": "ENCRYPTION",
    "status": "VALID",
    "organization": {
        "id": "f3493291-6c8c-491d-beb5-dfa098f48c5a"
    },
    "environment": {
        "id": "e3493291-6c8c-491d-beb5-dfa098f48c5a"
    }
}