forked from TrueCloudLab/certificates
Document the ACME, SSHPOP, X5C, and K8sSA provisioners.
- Fixes #266, #293, #294
This commit is contained in:
max furman
parent
b200e84967
commit
5752408618
1 changed files with 183 additions and 13 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue