# 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](https://developers.google.com/chrome/management/reference/rest/Shared.Types/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](https://developers.google.com/chrome/management/guides/certprovisioning_api#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](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses/get) method.
- Multiple Adapter instances can run in parallel and can try to claim the the same certificate provisioning process simultaneously, see [claim](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses/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](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses/signData) method. This method returns a long-running [Operation](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses.operations).
- The Certificate Provisioning Adapter periodically gets the state of the long-running operation, see [get](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses.operations/get) method.
- The Certificate Provisioning Adapter uploads a certificate for the certificate provisioning process, see [uploadCertificate](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses/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](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses/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}`

| Description | Relative URL | Http method |
|---|---|---|
| Get a certificate provisioning process | [/certificateProvisioningProcess/{certificate_provisioning_process_id}](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses/get) | GET |
| Claim a certificate provisioning process | [/certificateProvisioningProcess/{certificate_provisioning_process_id}:claim](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses/claim) | POST |
| Request a cryptographic signature | [/certificateProvisioningProcess/{certificate_provisioning_process_id}:signData](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses/signData) | POST |
| Upload a certificate | [/certificateProvisioningProcess/{certificate_provisioning_process_id}:uploadCertificate](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses/uploadCertificate) | POST |
| Mark the certificate provisioning process as failed | [/certificateProvisioningProcess/{certificate_provisioning_process_id}:setFailure](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses/setFailure) | POST |
| Get sign data long-running operation | [/certificateProvisioningProcess/{certificate_provisioning_process_id}/operations/{operation_id}](https://developers.google.com/chrome/management/reference/rest/v1/customers.certificateProvisioningProcesses.operations/get) | GET |

See [code samples](https://developers.google.com/chrome/management/guides/samples_certprovisioningapi) 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](https://cloud.google.com/docs/authentication/).