diff --git a/docs/provisioners.md b/docs/provisioners.md index 9f578381..d4b73c30 100644 --- a/docs/provisioners.md +++ b/docs/provisioners.md @@ -4,6 +4,14 @@ Provisioners are people or code that are registered with the CA and authorized to issue "provisioning tokens". Provisioning tokens are single-use tokens that can be used to authenticate with the CA and get a certificate. +See `step ca provisioner add --help` for documentation and examples on adding +provisioners. + +> Attn: We strongly recommend using the `step ca provisioner add ...` +> utility to generate provisioners in your `ca.json` configuration. We often +> encode fields differently in the JSON than you might expect. And you can +> always come in and modify the configuration manually after using the utility. + ## Claims Each provisioner can define an optional `claims` attribute. The settings in this @@ -85,17 +93,19 @@ Provisioners are used to authenticate certificate signing requests, and every provisioner has a slightly different scope of authorization. Below is a table detailing the authorization capabilities of each provisioner. -Provisioner | Authorization Capabilities ------------ | -------------------------- -JWK | * x509-sign, x509-renew, x509-revoke
* ssh-sign, ssh-revoke -OIDC | * x509-sign, x509-renew, x509-revoke
* ssh-sign, ssh-revoke -X5C | * x509-sign, x509-renew, x509-revoke
* ssh-sign -K8sSA | * x509-sign, x509-renew, x509-revoke
* ssh-sign -ACME | * x509-sign, x509-renew -SSHPOP | * ssh-renew, ssh-revoke, ssh-rekey -AWS | * x509-sign, x509-renew
* ssh-sign -Azure | * x509-sign, x509-renew
* ssh-sign -GCP | * x509-sign, x509-renew
* ssh-sign +Provisioner Capabilities| x509-sign | x509-renew | x509-revoke | ssh-user-cert-sign | ssh-host-cert-sign | ssh-user-cert-renew | ssh-host-cert-renew | ssh-revoke | ssh-rekey +----------- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: +JWK | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 +OIDC | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ [1](#f1) | 𝗫 | 𝗫 | ✔️ | 𝗫 +X5C | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫 +K8sSA | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫 +ACME | ✔️ | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 +SSHPOP | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | ✔️ | ✔️ | ✔️ +AWS | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫 +Azure | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫 +GCP | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫 + +1 Admin OIDC users can generate Host SSH Certificates. Admins can be configured in the OIDC provisioner. [↩](#a1) ### JWK @@ -127,13 +137,13 @@ In the ca.json configuration file, a complete JWK provisioner example looks like "minTLSCertDuration": "5m", "maxTLSCertDuration": "24h", "defaultTLSCertDuration": "24h", - "disableRenewal": false + "disableRenewal": false, "minHostSSHCertDuration": "5m", "maxHostSSHCertDuration": "1680h", "minUserSSHCertDuration": "5m", "maxUserSSHCertDuration": "24h", "maxTLSCertDuration": "16h", - "enableSSHCA": true, + "enableSSHCA": true } } ``` @@ -233,6 +243,166 @@ is G-Suite. * `claims` (optional): overwrites the default claims set in the authority, see the [top](#provisioners) section for all the options. +### X5C + +An X5C provisioner allows a client to get an x509 or SSH certificate using +an existing x509 certificate that is trusted by the X5C provisioner. + +An X5C provisioner is configured with a root certificate, supplied by the user, +at the time the provisioner is created. The X5C provisioner can authenticate +X5C tokens. + +An X5C token is a JWT, signed by the certificate private key, with an `x5c` +header that contains the chain. + +If you would like any certificate signed by `step-ca` to become a provisioner, +you can configure the X5C provisioner using the root certificate used by +`step-ca`, like so: + +``` +step ca provisioner add x5c-smallstep --type X5C --x5c-root $(step path)/certs/root_ca.crt +``` + +Or you can configure the X5C provisioner with an outside root, giving provisioner +capabilities to a completely separate PKI. + +Below is an example of an X5C provisioner in the `ca.json`: + +```json +... +{ + "type": "X5C", + "name": "x5c", + "roots": "LS0tLS1 ... Q0FURS0tLS0tCg==", + "claims": { + "maxTLSCertDuration": "8h", + "defaultTLSCertDuration": "2h", + "disableRenewal": true + } +} +``` + +* `type` (mandatory): indicates the provisioner type and must be `OIDC`. + +* `name` (mandatory): a string used to identify the provider when the CLI is + used. + +* `roots` (mandatory): a base64 encoded list of root certificates used for + validating X5C tokens. + +* `claims` (optional): overwrites the default claims set in the authority, see + the [top](#provisioners) section for all the options. + +### SSHPOP + +An SSHPOP provisioner allows a client to renew, revoke, or rekey an SSH +certificate using that certificate for authentication with the CA. +The renew and rekey methods can only be used on SSH host certificates. + +An SSHPOP provisioner is configured with the user and host root ssh certificates +from the `ca.json`. The SSHPOP provisioner can only authenticate SSHPOP tokens +generated using SSH certificates created by `step-ca`. + +An SSHPOP token is a JWT, signed by the certificate private key, with an `sshpop` +header that contains the SSH certificate. + +Below is an example of an SSHPOP provisioner in the `ca.json`: + +```json +... +{ + "type": "SSHPOP", + "name": "sshpop-smallstep", + "claims": { + "enableSSHCA": true + } +} +``` + +* `type` (mandatory): indicates the provisioner type and must be `OIDC`. + +* `name` (mandatory): a string used to identify the provider when the CLI is + used. + +* `claims` (optional): overwrites the default claims set in the authority, see + the [top](#provisioners) section for all the options. + +### ACME + +An ACME provisioner allows a client to request a certificate from the server +using the [https://tools.ietf.org/html/rfc8555](ACME Protocol). The ACME +provisioner can only request X509 certificates. All authentication of the CSR +is managed by the ACME protocol. + +Below is an example of an ACME provisioner in the `ca.json`: + +```json +... +{ + "type": "ACME", + "name": "my-acme-provisioner", + "claims": { + "maxTLSCertDuration": "8h", + "defaultTLSCertDuration": "2h", + } +} +``` + +* `type` (mandatory): indicates the provisioner type and must be `OIDC`. + +* `name` (mandatory): a string used to identify the provider when the CLI is + used. + +* `claims` (optional): overwrites the default claims set in the authority, see + the [top](#provisioners) section for all the options. + +See our [`step-ca` ACME tutorial](https://app.smallstep.com/docs/[product]/tutorials/acme-provisioners) +for more guidance on configuring and using the ACME protocol with `step-ca`. + +### K8sSA - Kubernetes Service Account + +A K8sSA provisioner allows a client to request a certificate from the server +using a Kubernetes Service Account Token. + +As of the time when this provisioner was coded, the Kubernetes Service Account +API for retrieving the token from a running instance was still in beta. Therefore, +our K8sSA provisioner must be configured with the public key that will be used +to validate K8sSA tokens. + +K8sSA tokens are very minimal. There is no place for SANs, or other details that +a user may want validated in a CSR. It is essentially a bearer token. Therefore, +at this time a K8sSA token can be used to sign a CSR with any SANs. Said +differently, the **K8sSA provisioner does little to no validation on the CSR +before signing it**. You should only configure and use this provisioner if you +know what you are doing. If a malicious user obtains the private key they will +be able to create certificates with any SANs and Subject. + +Below is an example of a K8sSA provisioner in the `ca.json`: + +```json +... +{ + "type": "K8sSA", + "name": "my-kube-provisioner", + "publicKeys": "LS0tLS1...LS0tCg==", + "claims": { + "maxTLSCertDuration": "8h", + "defaultTLSCertDuration": "2h", + } +} +``` + +* `type` (mandatory): indicates the provisioner type and must be `OIDC`. + +* `name` (mandatory): a string used to identify the provider when the CLI is + used. + +* `publicKeys` (mandatory): a base64 encoded list of public keys used to validate + K8sSA tokens. + +* `claims` (optional): overwrites the default claims set in the authority, see + the [top](#provisioners) section for all the options. + ### Provisioners for Cloud Identities [Step certificates](https://github.com/smallstep/certificates) can grant