smallstep / docs Goto Github PK

Especially important for those circumstances where users choose a reduced lifetime (default is 10yr). The step certificate inspect command does not return root certificates, so it can be difficult to understand which certificate has expired when users receive an invalid certificate error.

smallstep/cli#518

Update SSH host docs starting from this section:

https://smallstep.com/docs/ssh/hosts-step-by-step#step-3-install-the-step-ssh-utilities

This is blocked by having the ability to specify values from the X5C certificate in certificate templates -- smallstep/certificates#433.

• Set up a password flow to get a certificate
• CLI: create provisioned with a template for custom certificate
• login to your smallstep account - default OIDC flow
• Provide password for encrypted private key stored by CA
• inspect cert

Just noticed this on https://smallstep.com/docs/platform/events

Hello! Located under this section https://smallstep.com/docs/step-ca/provisioners#provisioner-management under "Modify a provisioner"
It has:

step ca provisioner update acme
--x509-min-dir=20m
--x509-max-dir=72h
--x509-default-dur=36h

It should be "dur" instead of "dir".

Description

Add docs on how to configure an OIDC provisioner on different OAuth 2.0/OpenID Connect providers:

• Google
• Microsoft
• Okta
• Auth0
• Keycloak
• ...

Add to https://smallstep.com/docs/step-ca/integrations#oidc

• Community members should be able to preview docs independently.
• Add instructions for previewing docs
• "Edit this file in GitHub" links from docs site

Description

Perhaps because of Tiny CA blog post there has been discussions github about the use of SSH certificates, for windows and posix-like OSes. I've been describing more or less how step ssh config works, how step ssh proxycommand works and how to configure it to use your oidc provider, ...

For windows users I've been pointing to microsoft docs on how to install OpenSSH and active the ssh-agent.
Our current turorials on smallstep.com/docs are focussed on X.509 rather than SSH. We need to add some docs there describing all the steps required, and how you can configure a client and a host properly.

And also add docs on how to configure the host if you don't have access to sshd_config. A user wants to use TinyCA to generate SSH certificatets, with help, his managed to generate SSH keys in yubikey and have that sign certificates, he wants to connect to HPC clusters with those certificates. Mike also helped with this.

See for example:

• smallstep/certificates#443
• smallstep/certificates#444

These new features are included in our latest release (version 18.1).

New behavior includes:
Running step ssh login without any positional argument (without an email or username) will produce a certificate with your default posix username and email address as principals, as determined by the CA. In other words, it should just "do the right thing".

We've also added a --principal flag to step ssh login if you want to explicitly specify the principal(s) to include in a certificate.
Running step ssh logout without any positional arguments will automatically remove all certificates signed by your SSH CA (and associated keys) from your SSH Agent. Again, it should just "do the right thing".
I think what this means for you is that your UI tool can be simplified to just a "login" and "logout" button that exec step ssh login and step ssh logout, respectively. You could get fancier than that, but I think that would be sufficient.

• update host config docs with pointer
• Put artifacts on files.smallstep.com
• update notion FAQ

This tutorial is out of date:

https://smallstep.com/docs/registration-authorities/acme-for-certificate-manager#run-a-registration-authority-on-kubernetes

The proper process should be:

https://github.com/smallstep/helm-charts/tree/master/step-certificates#tldr
https://github.com/smallstep/helm-charts/tree/master/step-certificates/examples#registration-authority-connected-to-smallstep-certificate-manager-hosted-certificate-authority

More context in the Discord:

https://discord.com/channels/837031272227930163/841249977699401759/1037518365301940244

Replace docs that cover step-pkcs11-init with instructions for using step-kms-plugin

Related: smallstep/certificates#1044

And the first one is empty.

Basically what the title says. There doesn't seem to be a way to generate an SSH-specific CSR for my root to sign. Would be nice if you could make the SSH equivalent to the tutorial here. Having instructions on the following:

1. How to generate CSR's for SSH CA intermediate authority use, both for user and host types.
2. How to get SSHCA working if you didn't use the step ca init --ssh function.

As it is, it would seem the only way to get an SSHCA up and running is to run step ca init --ssh, implying that it cannot be done after step ca init.

This is probably two different use-cases, but the story is similar.
Please advise. Thanks!

I think our main content block in the docs is too narrow.
The biggest issue is that the current width makes code blocks hard to read and hard to use.
I also think the overall line lengths could be 20-40 characters wider without negatively impacting readability.

I think we could get back about 150-300+ pixels of main content block width with a few tweaks:

• At the widest CSS width breakpoint, increase the main content block width from 630px to 750px

• Reduce left nav column width to give back 150-175px of width in the content block:

  • Reduce font size of product name headings so that whole column can be a bit narrower
  • Move anchor option () to the right side of headers and tighten up the left margin
  • Consider removing docs nav item logos (eg. ) even though they are very nice
  • Tighten up left margin on the sub-page nav items

It ended up being a time sink to try to get full paths to CLI reference docs in Algolia search results. We should follow up and fix the hack/workarond.

step-ca supports SSHAgentKMS (for SSH keys only; not for X.509), but we don't have a section in the Configuration docs for it. Here's the previous documentation, which needs to be fleshed out:

SSHAgentKMS

SSHAgentKMS is a KMS that wraps a ssh-agent which has access to the keys to
sign ssh certificates. This was primarily written to be able to use gpg-agent
to provide the keys stored in a YubiKeys openpgp interface.

{
    "kms": {
        "type": "sshagentkms"
    },
    "ssh": {
        "hostKey": "sshagentkms:cardno:000123456789",
        "userKey": "sshagentkms:cardno:000123456789",
    },
    ...
}

This KMS requires that "root", "crt" and "key" are stored in plain files, as for
SoftKMS.

The resource linked to in the 'Further reading' section of the readme does not seem to exist anymore.

X5C explainer. And custom integration docs. How do we envision people use X5c tokens? Give a small example.

If you look at https://smallstep.com/docs/step-ca/provisioners, the part options*: see the [options](https://smallstep.com/docs/step-ca/provisioners/#options) section for more details. in the acme-section seems to imply, that there is an anchor object at #options, which provides more information, Since this anchor does not exist, I assume, that this is residue content from refactoring this documentation section.

I propose, that these references should be rephrased and point towards the given example configuration above, e.g. "see the example configuration".

Using a Managed Identity for a Virtual Machine may be preferable to Service Principals as the secret does not have to be directly managed and exposed to the environment (https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication-managed-identity?tabs=azure-cli)

I've tested step ca and cli using Managed Identity to provision a standalone CA and run step-ca as a daemon with key vault with no issues and configuration can be reduced to:

• configure a managed identity (either system/user assigned) and assign the necessary RBAC/access policy rights to Key Vault.
• in the guest OS, configure the AZURE_CLIENT_ID to the client id of the Managed Identity. AZURE_TENANT_ID is optional.

see https://github.com/rjfmachado/step-ca-azure, values are replaced by the template deployment.

• using AZURE_CLIENT_ID=[AZURE_CLIENT_ID] in /etc/environment for the cli part
• using Environment=AZURE_CLIENT_ID=[AZURE_CLIENT_ID] in /etc/systemd/system/step-ca.service for the daemon.

The Azure SDK for go will use the managed identity if the secret is not presented.
https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/default_azure_credential.go#L31

We don't really need the full capacity of step ca bootstrap which requires the fingerprint. And many devices don't have the ability to run a terminal command. How should those devices get and install root certificates?

https://smallstep.com/docs/ssh/hosts-step-by-step#step-3-install-the-step-ssh-utilities

We have to think twice, thrice before plugging a binary blob into our core infrastructure (we don't even have its GPG signature)

https://smallstep.com/docs/step-ca/certificate-authority-server-production/#high-availability

markdoc/markdoc

Some benefits:

• overall better syntax (no {``}, supports markdown inside component blocks eg. within the body of a tag)
• header ID annotations
• auto table of contents
• stripe is actively adding features (search is coming soon :D :D)
• sounds like the renderer is faster than MDX
• If most of the work here would involve converting a bunch of search and replace, I may be willing to shave those yaks.

Once there's a good search function, it could really make this worth the effort

Ideas for updates to our systemd certificate management units:

• more env variables that can be overridden (contexts)
• don't try reload/restart in the main systemd unit. just don't.
• add a one-shot bootstrapping unit — ref it in after and wants of the renewer unit
• add a one-shot enrollment unit
• suggest using systemd credentials

Some inspiration can come from Joe's setup

docs updates for this:

• update Production Considerations doc to reflect the new units
• update Practical Zero Trust systemd examples to be compatible with the new units

Description

The provisioner docs at https://smallstep.com/docs/step-ca/provisioners do not include docs for the nebula provisioner.

The nebula provisioner SANs or principals are always validated against the nebula certificate name and/or IPs, and it cannot issue SSH-user certificates.

The current document doesn't spell out clearly how the certificate renew process is done from the perspective of a client. The document stated that it uses mTLS or token. But no mention of what key pairs it uses for mTLS. And it does not specify in what context it would use token for the renewing. Quoted from the discussion from discord:

question , answer, another answer

We'll leverage existing docs for X509 renewal, plus @darix's new cert renewer units

We used to have a list of all the tutorials on the index page (/docs/tutorials). This needs to be resurrected.

In the Kubernetes instructions, we show how to install cert-manager with helm, but not step-issuer.

This link:
https://smallstep.com/docs/step-ca/installation#docker

Should point to:
https://hub.docker.com/r/smallstep/step-ca

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to document this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Affected area/feature

Following through with the docker Getting Started and ACME Basics pages, when running step-ca in a docker container and running step-cli outside of the container, you will encounter the following error when attempting to add the provisioner:

step ca provisioner add acme --type ACME
No admin credentials found. You must login to execute admin commands.
✔ Please enter admin name/subject (e.g., [email protected]): admin
✔ Provisioner: admin (JWK) [kid: tSqHR-XrFV6k1Zr7Ejv0AMNC2YluOwb99aAlRfuYoZI]
Please enter the password to decrypt the provisioner key: ...
json: cannot unmarshal number into Go value of type ca.AdminClientError

This has been cleared up in a discord message from @dopey but would be beneficial to have in the sections referencing add provisioner commands that it must be ran where the step-ca server is running (as noted on the provisioners page), i.e., using docker exec instead.

An issue regarding improved console error messages from the CLI relates to this as well, linked in the discord recently: smallstep/cli#684

https://discord.com/channels/837031272227930163/841249977699401759/982701928989458492

...this indicates that the cli is trying to use the Remote Configuration Management API to perform the provisioner add action.

By default your CA will be configured not to allow remote configuration management - which means the provisioners will be stored in the ca.json file and the only way to update the provisioners is to run commands locally (wherever step-ca is being run).

So, assuming you have not intentionally enabled Remote Confguration [sic] Management, the cli is attempting to use remote provisioner management because it does not know where to find your ca.json file. You must run step ca provisioner add ... from the same server where step-ca is running, so that the ca.json can be edited. The default location for the ca.json is $(step path)/config/ca.json. You can also use --ca-config to point directly to the ca.json file, if it is not in the default location. If the ca.json file cannot be found (either in the default location or as directed by --ca-config) then the CLI will attempt to use remote config management. Which is why you see the ca.AdminClientError popping up. (remote configuration management uses the AdminClient).

• In SSH template examples, show how to add a custom OIDC claim on 1 or more IdPs
• Expand from the Okta example to 1-2 other popular IdPs

If step accepts an HTTPS_PROXY env variable, we should note it on this page

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to document this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Affected area/feature

When running in a Docker environment, you can't do all that much without enabling remote management.

From what I read on Discord, this seems to be a common issue for people starting out with the CA on Docker, so I suggest to add a note in the Docker info.

Something like:

To enable remote management, include "enableAdmin": true in the authority object of ca.json.

Hat tip to @hslatman for explaining this to me.

If you select ACME, it switches to the Built-In tab by default. But, if you're using a technology that doesn't have built-in ACME, no tab is selected.

https://github.com/smallstep/docs/blob/8e55a9dceae431b0483fe5e15910f43d29b9111a/src/pages/docs/step-ca/installation.mdx#linux-other just goes to the top of the form. There's no anchor with that name.

I went there looking for Enterprise Linux RPM packages, as I like the supply-chain validation.

See also: Getting Started UI workflow (smallstep/planning#126)

Next steps for docs...

14 Day Priority (July 5th)

• Reshuffling docs to break apart Provisioner/Template sections - Kevin
• Instructions on how to move config (add one flag to json, then how to move ca.json to db) - Max

Structural changes to accommodate CM

• Discuss & align on docs structure
• How do we not reinvent the wheel given that a lot of features are documented in open source?
  • Link to open source docs, or duplicate / import them into CM docs?
  • Split out sections of open source docs into their own pages for easier reference:
    • Provisioners
    • Templates
    • Renewal
    • Revocation
    • Cryptographic Protection (eg hsms)
    • RA Mode
    • High Availability
    • Proxying & Load Balancing step-ca
• Start a Knowledge Base section in Notion for CM (questions like: How do I bring my own root?)

Document features open source doesn't have

• Webhooks & events -- inline documentation in the UI?
• Configuration guide? ??? (do we need docs for the config UI?)
• Supported systems / requirements (same as SSH product)
• Linked CA HOWTO — advanced flow — for Hunter / KCF

Document new features in both open source and CM

• document cli docs for -h output
• remote template management

Blocked

• Document CLI admin functionality (add/remove/update admin as a superadmin) - Kevin
• RA flow — part of "ACME for CM" docs — ask Eng how this will work?
• remote provisioner management (blocked - waiting for v1)
• update blog post for provisioner changes

Identity Provider OIDC-only apps

A Smallstep Certificate Manager app in the IdP App Stores

• add IdP-specific docs for the OIDC provisioner (see #69)
• get an Okta OIDC app
• Azure OIDC app
• Google OIDC app
• Howto: Certificate renewals in different contexts

It seems that the step-ca supports ssh ca federation or rotating ssh ca in the source code, but there are no related documents nor examples. So we need more detail information about the operations, configs about how to rotate or federate multiple ssh ca.

Note more clearly that the redis-cli tool needs CA root passed in explicitly via --cacert flag.

The Redis command-line client & server are somewhat unusual in that they do not trust certificates in your system trust store. We pass the flag correctly in our systemd unit, and this is mentioned in research notes, but it also seems worth mentioning in the root distribution section (like, just a sentence or two). I think this might be tricky though since this is common content that's shared between pages (I think).

It should also be clear that the Redis SDKs appear to use standard library TLS stacks and do appear to use the system trust store.

The kubernetes.io/tls link on the Kubernetes TLS page redirects to a 404 page.

Hugo may have a way to do this that we just aren't using

The following is cribbed from @mmalone:

Having the OAuth credentials in the /provisioners API response is secure / conforms to best practice. That doesn’t mean that there aren’t security considerations, but that’s always true. Our OAuth implementation conforms to best current practices for OAuth for Native Apps (published as IETF BCP212 / RFC8252). Other CLI tools use the same technique that we use here, including the gcloud CLI for GCP (they embed the OAuth client secret in their source code).
The reason this is secure is because the OAuth Authorization Code flow requires the callback URL to be hard-coded as part of the client configuration. A properly configured client for use with step / step-ca should only redirect to 127.0.0.1 (or localhost), which makes the flow resistant to passive/active network attacks. The attacker would need to already have local access to your machine to compromise the flow. OAuth, in general, is not very resistant to a local attacker on your device, so the threat model for our OAuth implementation is not significantly different than any other OAuth flow. It’s also worth noting that, if you have a local attacker on your device it’s unlikely that this attack is your biggest threat.
One more point: technically BCP212 recommends that OAuth providers / IdPs have a special OAuth client type that doesn’t have a client secret at all. In practice, Azure AD is the only provider I’m aware of that does this, so we didn’t bother supporting it. Functionally, having no secret is identical to having a public “secret”, except that it’s clear to end-users that the client is secure (these “secretless” clients are restricted to only supporting native app flows). But, that’s just one more data point for this flow being widely vetted and considered secure.

The blog mentions an HSM called called the Thales nShield Connect 6000 for $39,000.

The nShield Connect 6000 is now an old model that is no longer sold. The $39,000 model is now called the nShield Connect XC High. nShield was also bought by Entrust, so this should say "Entrust nShield Connect XC High."

We need to fill in all default content for the renewal section, except for 01-builtin.mdx and the systemd 02-override.mdx files, which can remain blank.

See this doc for the content that needs to be filled in.

(see https://www.markdownguide.org/extended-syntax#heading-ids)

If we support and supply custom heading IDs in our docs, our permalinks won't change when we change a heading's title.