Document the ACME, SSHPOP, X5C, and K8sSA provisioners.

- Fixes #266, #293, #294
This commit is contained in:
max furman 2020-06-25 17:27:17 -07:00
parent b200e84967
commit 5752408618

View file

@ -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 <br/> * ssh-sign, ssh-revoke
OIDC | * x509-sign, x509-renew, x509-revoke <br/> * ssh-sign, ssh-revoke
X5C | * x509-sign, x509-renew, x509-revoke <br/> * ssh-sign
K8sSA | * x509-sign, x509-renew, x509-revoke <br/> * ssh-sign
ACME | * x509-sign, x509-renew
SSHPOP | * ssh-renew, ssh-revoke, ssh-rekey
AWS | * x509-sign, x509-renew <br/> * ssh-sign
Azure | * x509-sign, x509-renew <br/> * ssh-sign
GCP | * x509-sign, x509-renew <br/> * 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 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ <sup id="a1">[1](#f1)</sup> | 𝗫 | 𝗫 | ✔️ | 𝗫
X5C | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫
K8sSA | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫
ACME | ✔️ | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫
SSHPOP | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | ✔️ | ✔️ | ✔️
AWS | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫
Azure | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫
GCP | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫
<b id="f1">1</b> 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