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
|
to issue "provisioning tokens". Provisioning tokens are single-use tokens that
|
||||||
can be used to authenticate with the CA and get a certificate.
|
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
|
## Claims
|
||||||
|
|
||||||
Each provisioner can define an optional `claims` attribute. The settings in this
|
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
|
provisioner has a slightly different scope of authorization. Below is a table
|
||||||
detailing the authorization capabilities of each provisioner.
|
detailing the authorization capabilities of each provisioner.
|
||||||
|
|
||||||
Provisioner | Authorization Capabilities
|
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 | * x509-sign, x509-renew, x509-revoke <br/> * ssh-sign, ssh-revoke
|
JWK | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫
|
||||||
OIDC | * x509-sign, x509-renew, x509-revoke <br/> * ssh-sign, ssh-revoke
|
OIDC | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ <sup id="a1">[1](#f1)</sup> | 𝗫 | 𝗫 | ✔️ | 𝗫
|
||||||
X5C | * x509-sign, x509-renew, x509-revoke <br/> * ssh-sign
|
X5C | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫
|
||||||
K8sSA | * x509-sign, x509-renew, x509-revoke <br/> * ssh-sign
|
K8sSA | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫
|
||||||
ACME | * x509-sign, x509-renew
|
ACME | ✔️ | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫
|
||||||
SSHPOP | * ssh-renew, ssh-revoke, ssh-rekey
|
SSHPOP | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | 𝗫 | ✔️ | ✔️ | ✔️
|
||||||
AWS | * x509-sign, x509-renew <br/> * ssh-sign
|
AWS | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫
|
||||||
Azure | * x509-sign, x509-renew <br/> * ssh-sign
|
Azure | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫
|
||||||
GCP | * x509-sign, x509-renew <br/> * ssh-sign
|
GCP | ✔️ | ✔️ | 𝗫 | 𝗫 | ✔️ | 𝗫 | 𝗫 | 𝗫 | 𝗫
|
||||||
|
|
||||||
|
<b id="f1">1</b> Admin OIDC users can generate Host SSH Certificates. Admins can be configured in the OIDC provisioner. [↩](#a1)
|
||||||
|
|
||||||
### JWK
|
### JWK
|
||||||
|
|
||||||
|
|
@ -127,13 +137,13 @@ In the ca.json configuration file, a complete JWK provisioner example looks like
|
||||||
"minTLSCertDuration": "5m",
|
"minTLSCertDuration": "5m",
|
||||||
"maxTLSCertDuration": "24h",
|
"maxTLSCertDuration": "24h",
|
||||||
"defaultTLSCertDuration": "24h",
|
"defaultTLSCertDuration": "24h",
|
||||||
"disableRenewal": false
|
"disableRenewal": false,
|
||||||
"minHostSSHCertDuration": "5m",
|
"minHostSSHCertDuration": "5m",
|
||||||
"maxHostSSHCertDuration": "1680h",
|
"maxHostSSHCertDuration": "1680h",
|
||||||
"minUserSSHCertDuration": "5m",
|
"minUserSSHCertDuration": "5m",
|
||||||
"maxUserSSHCertDuration": "24h",
|
"maxUserSSHCertDuration": "24h",
|
||||||
"maxTLSCertDuration": "16h",
|
"maxTLSCertDuration": "16h",
|
||||||
"enableSSHCA": true,
|
"enableSSHCA": true
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
@ -233,6 +243,166 @@ is G-Suite.
|
||||||
* `claims` (optional): overwrites the default claims set in the authority, see
|
* `claims` (optional): overwrites the default claims set in the authority, see
|
||||||
the [top](#provisioners) section for all the options.
|
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
|
### Provisioners for Cloud Identities
|
||||||
|
|
||||||
[Step certificates](https://github.com/smallstep/certificates) can grant
|
[Step certificates](https://github.com/smallstep/certificates) can grant
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue