Certificate Provisioning API

The Certificate Provisioning API allows integrating Certificate Authorities with ChromeOS client certificate provisioning.

ChromeOS Administrators can configure their ChromeOS devices or ChromeOS users to request client certificates from an external Certificate Authority. The Certificate Authority interacts with the Certificate Provisioning API through Certificate Provisioning Adapters (e.g., the Google Cloud Certificate Connector (GCCC)). Each Certificate Provisioning Adapter receives notifications about new certificate provisioning requests through Pub/Sub and then uses the Certificate Provisioning API to interact with the ChromeOS device or ChromeOS user requesting a certificate.

This service works with the following main concepts:

• A client certificate is a X.509 digital certificate issued for a ChromeOS device or ChromeOS user. The key pair is generated on the device and the private key never leaves the device.
• A certificate provisioning process (represented by the resource CertificateProvisioningProcess) describes the process of provisioning a client certificate. The client requesting a certificate is either a ChromeOS device or ChromeOS user.
• A certificate provisioning profile describes the administrator's configuration for a client certificate. Clients are provisioned with a certificate for each profile that applies to them.

General flow of a certificate provisioning process:

• After a client fetches a client certificate profile, it launches a certificate provisioning process which is tied to a certificate provisioning resource.
• Each Certificate Provisioning Adapter which is subscribed to the relevant Pub/Sub topic gets notified about a new certificate provisioning process. The Pub/Sub notification contains a CertificateProvisioningPubsubNotification proto message conveying the unique ID of the certificate provisioning process.
• Each Certificate Provisioning Adapter can access the certificate provisioning process resource, see get method.
• Multiple Adapter instances can run in parallel and can try to claim the the same certificate provisioning process simultaneously, see claim method. However, the claim method will only succeed for a single Adapter instance which must then also handle the remaining steps of the certificate provisioning process.
• The Certificate Provisioning Adapter can request a cryptographic signature generated using the client's private key, see signData method. This method returns a long-running Operation.
• The Certificate Provisioning Adapter periodically gets the state of the long-running operation, see get method.
• The Certificate Provisioning Adapter uploads a certificate for the certificate provisioning process, see uploadCertificate method. This certificate is imported by the ChromeOS client.
• Throughout the entire certificate provisioning process the Adapter can mark the certificate provisioning process as failed, see setFailure method. The certificates setting page on the ChromeOS client shows the provided error message. The client retries the certificate provisioning process at certain occasions, e.g., after 24 hours or after rebooting the device.

Initial Pub/Sub message format

The initial Pub/Sub message that is sent to Certificate Provisioning Adapters to notify them about a new certificate provisioning process adheres to the following format:

message CertificateProvisioningProcessCreatedEventData {
  // Unique ID of the certificate provisioning process.
  string certificate_provisioning_process_id = 1;

  // The customer ID to which the client of the certificate provisioning process
  // belongs.
  string customer_id = 2;
}

// Content of the pubsub message that is sent to the adapter to notify it about
// a new event that should be handled.
message CertificateProvisioningPubsubNotification {
  oneof event {
    // Event data of the certificate provisioning process that was created.
    CertificateProvisioningProcessCreatedEventData
        certificate_provisioning_process_created_event_data = 1;
  }
}

Quick overview of API methods

URLs are relative to https://chromemanagement.googleapis.com/v1/customers/{customer_id}

See code samples for example requests and responses.

API scopes

Chrome Management API requires the following OAuth scope:

https://www.googleapis.com/auth/chrome.management.certprov.provisioningprocess

For more information, see the Authentication Overview.