--- title: Certificate Management description: 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: component: pingone-api page_id: pingone-api:platform:certificate-management canonical_url: https://developer.pingidentity.com/pingone-api/platform/certificate-management.html section_ids: default-organization-and-environment-certificates: Default organization and environment certificates default-organization-certificate: Default organization certificate default-environment-certificate: Default environment certificate default-environment-key: Default environment key assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service certificate-management-data-model: Certificate management data model certificates-and-keystore-events-generated: Certificates and keystore events generated response-codes: Response codes --- # 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](certificate-management/key-rotation-policies.html) 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 | ## Assigning admin roles and permissions to this service Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to [PingOne Permissions by Service](reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions. You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources. Admin assignments to roles are set by: * [Automatic assignment for some roles](roles/predefined-roles.html#automatic-role-assignment). * [Group Role Assignments](group-role-assignments/group-role-assignments.html). * [User Role Assignments](users/user-role-assignments.html). Refer to [Roles Management](roles.html) for more information. ## 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](custom-domains.html) 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](reference/audit-reporting-events.html) 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. |