diff --git a/.github/mdl.config.json b/.github/mdl.config.json index c0d5255d..6bf862ba 100644 --- a/.github/mdl.config.json +++ b/.github/mdl.config.json @@ -40,7 +40,7 @@ "pattern": "^https://www.gnu.org" }, { - "pattern": "^https://freedesktop.org" + "pattern": "^https://.*freedesktop.org" }, { "pattern": "^https://www.hashicorp.com" diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml index 334ce50a..ca655599 100644 --- a/.github/workflows/link-check.yml +++ b/.github/workflows/link-check.yml @@ -27,7 +27,7 @@ jobs: - name: Check changed files only (PR) if: github.event_name == 'pull_request' run: | - CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- '*.mdx') + CHANGED_FILES=$(git diff --name-only --diff-filter=ACMR origin/${{ github.base_ref }}...HEAD -- '*.mdx') if [ -z "$CHANGED_FILES" ]; then echo "No .mdx files changed" exit 0 diff --git a/.vale.ini b/.vale.ini index 3aac3f97..3f2c11d7 100644 --- a/.vale.ini +++ b/.vale.ini @@ -43,6 +43,13 @@ Google.Exclamation = NO # Slang like "TL;DR" is acceptable in developer-focused technical documentation Google.Slang = NO +# "There is/There are" constructions are acceptable in technical documentation +write-good.ThereIs = NO + +# DateFormat matches version numbers like "10.0.15063" incorrectly +Google.DateFormat = NO + + TokenIgnores = (@smallstep/[a-zA-Z0-9-]+), \ (_[a-zA-Z0-9_]+_), \ ([a-zA-Z]+_[a-zA-Z_]+) diff --git a/.vale/styles/Smallstep/Branding.yml b/.vale/styles/Smallstep/Branding.yml index effae17b..4436a0b6 100644 --- a/.vale/styles/Smallstep/Branding.yml +++ b/.vale/styles/Smallstep/Branding.yml @@ -3,7 +3,6 @@ message: "Use '%s' instead of '%s' for consistent branding." level: error ignorecase: false swap: - smallstep: Smallstep Small Step: Smallstep stepca: step-ca Step-CA: step-ca diff --git a/.vale/styles/config/vocabularies/Smallstep/accept.txt b/.vale/styles/config/vocabularies/Smallstep/accept.txt index 315aea9f..5d9fc161 100644 --- a/.vale/styles/config/vocabularies/Smallstep/accept.txt +++ b/.vale/styles/config/vocabularies/Smallstep/accept.txt @@ -772,7 +772,6 @@ attestationRoots clientId complexify customappsso -Emojivoto encryptedKey excludeIntermediate failover @@ -948,3 +947,4 @@ organizationalUnit publicKey serialNumber testuser +disallow diff --git a/agent.md b/agent.md index 0d981edb..32f3b28e 100644 --- a/agent.md +++ b/agent.md @@ -1,4 +1,8 @@ -Use vale for docs linting, ignoring auto-generated files in step-cli/reference +Use vale for docs linting. +When running vale, always ignore auto-generated files in step-cli/reference: + +vale --no-wrap --glob='!step-cli/reference/**' + DO NOT modify any auto-generated files inside step-cli/reference Use markdown-link-check to check links To preview the docs in a web browser, run `pnpm dev` inside the `smallstep.com` repo, which you may find in the parent directory. A server will open on https://localhost:5050 diff --git a/certificate-manager/acme-old.mdx b/certificate-manager/acme-old.mdx index 4daf53d7..08d8330b 100644 --- a/certificate-manager/acme-old.mdx +++ b/certificate-manager/acme-old.mdx @@ -22,7 +22,7 @@ Automatically manage certificates on internal websites, servers, and the entire ### About ACME At a high level, ACME is pretty simple. An ACME client creates an account with an ACME server and submits a certificate order. The server responds with a set of challenges for the client to complete to prove control over identifiers (domain names) in the certificate. Once the client successfully completes these challenges, it submits a certificate signing request (CSR) and the server issues a certificate. -The most interesting part of all of this is the challenge – where the client proves control over an identifier. No single standard way exists to "prove control" over an "identifier", so the core ACME specification makes this an extension point. Smallstep supports all the popular ACME challenges including DNS, HTTP, ALPN, IP, and EAB configurations. +The most interesting part of all of this is the challenge—where the client proves control over an identifier. No single standard way exists to "prove control" over an "identifier", so the core ACME specification makes this an extension point. Smallstep supports all the popular ACME challenges including DNS, HTTP, ALPN, IP, and EAB configurations. ### ACME challenge verification When public ACME Certificate Authorities (CA) like Let's Encrypt issue certificates to clients in the Web PKI, the CA depends heavily on public DNS for client verification. To get a certificate, a client must prove to the CA that it either directly controls the public DNS records for a domain (for the DNS-01 challenge type) or controls the IP address pointed to by public DNS records (for the HTTP-01 and TLS-ALPN-01 challenge types). diff --git a/certificate-manager/basic-ops.mdx b/certificate-manager/basic-ops.mdx index 043d9f6a..8c277261 100644 --- a/certificate-manager/basic-ops.mdx +++ b/certificate-manager/basic-ops.mdx @@ -23,7 +23,7 @@ This tutorial covers: ### Before you begin This tutorial assumes you have created a Smallstep Team and a Certificate Manager Authority using the steps in [Getting Started](./getting-started.mdx). -### Step 1 - Create a test certificate +### 1.Create a test certificate With an Authority created and your local client configured, you can create a test certificate by running the `step ca certificate` command. @@ -43,7 +43,7 @@ In this command, we are asking the CA to create a certificate with the following When you run this command, it will envoke the `authority-admin` provisioner and start a single sign-on flow via the Smallstep console. After a successful sign-in, the authority will issue the certificate. -### Step 2 - Inspect a test certificate +### 2. Inspect a test certificate You can inspect your certificate by running: @@ -63,7 +63,7 @@ X.509v3 TLS Certificate (ECDSA P-256) [Serial: 2441...2018] to: 2021-10-05T21:31:12Z ``` -### Step 3 - Renew a certificate +### 3. Renew a certificate Certificates expire. Certificate Manager makes renewing a certificate ahead of expiration easy. Renewals are authenticated using your existing certificate and produce an identical certificate with a new serial number and extended lifetime. @@ -92,7 +92,7 @@ X.509v3 TLS Certificate (ECDSA P-256) [Serial: 2441...2018] -### Step 4 - Revoke a certificate +### 4. Revoke a certificate Certificate Manager DevOps Authorities use passive revocation and short-lived certificates by default. To passively revoke a certificate means to block its renewal at the CA. diff --git a/certificate-manager/core-concepts.mdx b/certificate-manager/core-concepts.mdx index 4c42197d..9c980a3b 100644 --- a/certificate-manager/core-concepts.mdx +++ b/certificate-manager/core-concepts.mdx @@ -9,11 +9,11 @@ The Smallstep Platform is powered by a number of components that can be combined The components include: -- **[Authorities]()**— Certificate or registration authorities powered by `step-ca` -- **[Provisioners]()**— Machinery for securely automating certificate issuance -- **[Inventories]()**— Catalogs of entities like hosts, services, and people for use with templates and provisioners -- **[Templates]()**— Customization of x.509 or SSH certificates for any use case -- **[Events]()**— Observability and alerting for certificate lifecycle activities +- **[Authorities]()**: Certificate or registration authorities powered by `step-ca` +- **[Provisioners]()**: Machinery for securely automating certificate issuance +- **[Inventories]()**: Catalogs of entities like hosts, services, and people for use with templates and provisioners +- **[Templates]()**: Customization of x.509 or SSH certificates for any use case +- **[Events]()**: Observability and alerting for certificate lifecycle activities # Authorities diff --git a/certificate-manager/how-it-works.mdx b/certificate-manager/how-it-works.mdx index 9c908c68..a9477ca6 100644 --- a/certificate-manager/how-it-works.mdx +++ b/certificate-manager/how-it-works.mdx @@ -157,7 +157,7 @@ default for the `OIDC` provisioner). * This is an Advanced Authority feature Some use cases demand an option to renew expired certificates. -For example, intermittently-connected devices may not be able to reach the CA in time for a renewal. +For example, intermittently connected devices may not be able to reach the CA in time for a renewal. The ability to renew expired certificates can be enabled on a per-provisioner basis. Enable it in the Smallstep console when you create a new provisioner, or on the command line for an existing provisioner. diff --git a/certificate-manager/kubernetes-tls/kubernetes-step-issuer.mdx b/certificate-manager/kubernetes-tls/kubernetes-step-issuer.mdx index 0867bcc7..9a580ebd 100644 --- a/certificate-manager/kubernetes-tls/kubernetes-step-issuer.mdx +++ b/certificate-manager/kubernetes-tls/kubernetes-step-issuer.mdx @@ -44,7 +44,7 @@ You'll need it for later steps. Upon success, you will see the provisioner’s configuration returned as a successful response. -Run the [following command](https://smallstep.com/docs/step-cli/reference/ca/provisioner/list), and make a note of the new provisioner’s `“kid”` field (the *5th line listed*; it will be required in later steps): +Run the [following command](https://smallstep.com/docs/step-cli/reference/ca/provisioner/list), and make a note of the new provisioner's `"kid"` field (the *fifth line listed*; it will be required in later steps): -Installers for macOS, Windows and Linux can be also be downloaded from [GitHub releases](https://github.com/smallstep/smallstep-desktop/releases). Releases are signed with, and can be verified, by cosign. - -| Platform | Release | -|:--|:--| -| macOS | Latest Version | -| Linux (Flatpak) | Latest Version | -| Linux (.deb) | Latest Version | -| Linux (.rpm) | Latest Version | -| Windows | Latest Version | +Installers for macOS, Windows and Linux can be downloaded from [GitHub releases](https://github.com/smallstep/step-agent-plugin/releases). Releases are signed with, and can be verified, by cosign. ## System requirements @@ -38,7 +30,7 @@ Installers for macOS, Windows and Linux can be also be downloaded from [GitHub r ### Linux -- Flatpak, or Debian 12+, Ubuntu 22.04+, Fedora 38+ +- Debian 12+, Ubuntu 22.04+, Fedora 38+ - `systemd`-based service manager - Trusted Platform Module (TPM 2.0) - p11-kit diff --git a/ssh/acls.mdx b/ssh/acls.mdx index 116342be..acb9a9ce 100644 --- a/ssh/acls.mdx +++ b/ssh/acls.mdx @@ -33,7 +33,7 @@ Let's look at an example: * The `data` group will have access to `myserver #2` and `myserver #3`. * The `ops` group will have `sudo` access to `myserver #2` and `myserver #3`. -Of course, hosts and groups can have as many tag combinations as you like. Take a minute to think about how you'd like to use Host Tags in your environment. +Of course, hosts, and groups can have as many tag combinations as you like. Take a minute to think about how you'd like to use Host Tags in your environment. ### Step 1: Determine host tag combination diff --git a/ssh/hosts-step-by-step.mdx b/ssh/hosts-step-by-step.mdx index f06f94c4..5d48f3af 100644 --- a/ssh/hosts-step-by-step.mdx +++ b/ssh/hosts-step-by-step.mdx @@ -71,7 +71,7 @@ step ssh certificate $hostname /etc/ssh/ssh_host_ecdsa_key.pub \ #### If a host has multiple hostnames... -> **Note:** When a host has multiple hostnames, your users will only be able to `ssh` to the canonical `$hostname`, as shown by the `step ssh hosts` command. +> **Note:** When a host has multiple hostnames, your users can only `ssh` to the canonical `$hostname`, as shown by the `step ssh hosts` command. If you need multiple hostnames in your host certificate (for example, public and private hostnames, or a hostname and an IP address), you can pass each of them to `step ssh certificate` via the `--principal` flag: diff --git a/ssh/hosts.mdx b/ssh/hosts.mdx index 8ac48bf9..c652d59e 100644 --- a/ssh/hosts.mdx +++ b/ssh/hosts.mdx @@ -148,7 +148,9 @@ This script will: ## Optional hardening -Now that you're using certificates, you may wish to explicitly disallow the use of `authorized_keys` files on the host. +Now that you're using certificates, +you may wish to explicitly block the +use of `authorized_keys` files on the host. You can do this by setting `AuthorizedKeysFile none` in `sshd_config`. You may want to allow `authorized_keys` for an emergency access account, however. A configuration for this might look like: diff --git a/step-ca/README.mdx b/step-ca/README.mdx index b4585ebc..2c07b2d5 100644 --- a/step-ca/README.mdx +++ b/step-ca/README.mdx @@ -70,7 +70,7 @@ For example, you can have your CA issue certificates in exchange for: - ID tokens from Okta, Google Workspace, Microsoft Entra ID and Auth0 - ID tokens from an OAuth OIDC service you host, like [Keycloak](https://www.keycloak.org/) or [Dex](https://github.com/dexidp/dex) - [Cloud instance identity documents](https://smallstep.com/blog/embarrassingly-easy-certificates-on-aws-azure-gcp/) for VMs on AWS, GCP, and Azure -- [Single-use, short-lived JWK tokens](./provisioners.mdx#jwk), for example, issued by your CD tool — Puppet, Chef, Ansible, Terraform, etc. +- [Single-use, short-lived JWK tokens](./provisioners.mdx#jwk), for example, issued by your CD tool—Puppet, Chef, Ansible, Terraform, etc. ### Templates diff --git a/step-ca/certificate-authority-server-production.mdx b/step-ca/certificate-authority-server-production.mdx index e58038e3..c329c28f 100644 --- a/step-ca/certificate-authority-server-production.mdx +++ b/step-ca/certificate-authority-server-production.mdx @@ -770,7 +770,7 @@ Root rotation is out of scope for this document. ### Rotating an intermediate CA -Creating a new Intermediate CA will not affect previously-issued leaf certificates. +Creating a new Intermediate CA will not affect previously issued leaf certificates. When they were issued, these certificates were bundled with the old intermediate CA. When an old certificate is renewed, the entire PEM bundle is replaced. diff --git a/step-ca/renewal.mdx b/step-ca/renewal.mdx index 17d6f3fe..6d61cb01 100644 --- a/step-ca/renewal.mdx +++ b/step-ca/renewal.mdx @@ -409,7 +409,7 @@ Unfortunately, it also lets an attacker with the private key do the same thing. To prevent this, you need to explicitly tell `step-ca` to revoke a retired certificate. See the [certificate revocation section](./revocation.mdx) for details. -#### Renewal after expiry: For intermittently-connected devices +#### Renewal after expiry: For intermittently connected devices You can configure a provisioner to allow certificates to be renewed after they expire. This is not the default behavior, diff --git a/step-ca/templates.mdx b/step-ca/templates.mdx index 14aa8602..994ba513 100644 --- a/step-ca/templates.mdx +++ b/step-ca/templates.mdx @@ -219,37 +219,35 @@ See [the complete list of fields supported in `step-ca` templates](https://githu Here are some variables available in X.509 certificate templates: -- **.Subject**: +- `.Subject`: The subject that was passed in to `step certificate` or `step ca certificate`. Specifically, `.Subject.CommonName` contains the Common Name for the certificate. By default, a passed-in subject value must match a value from a trusted source in order to be added to the certificate. -- **.SANs**: +- `.SANs`: Subject Alternative Names. This is a list of maps containing SANs for the certificate. Unless SANs are specified (using the `--san` flag, for example), the `.Subject.CommonName` is the default SAN. By default, a passed-in subject value must match a value from a trusted source in order to be added to the certificate. -- **.Token**: - If a signed token was used to obtain the certificate - —for example, with the JWK provisioner— - this property contains the payload of that token. +- `.Token`: + If a signed token was used to obtain the certificate—for example, with the JWK provisioner—this property contains the payload of that token. -- **.AuthorizationCrt**: +- `.AuthorizationCrt`: For provisioners that use certificates to authorize requests (eg. the X5C provisioner), this is the certificate used to authorize the current certificate request with the CA. The client has proven posession of this certificate's private key. For an X.509 authorization certificate, the `.AuthorizationCrt` is a [`crypto/x509` Certificate](https://pkg.go.dev/crypto/x509#Certificate). -- **.AuthorizationChain**: +- `.AuthorizationChain`: For provisioners that use certificates to authorize requests (eg. the X5C provisioner), this is an array of the certificate chain from the request. This chain connects the authorization certificate to the root CA configured in the provisioner. -- **.Insecure** These variables are marked insecure because they contain client-supplied data that is not signed by a trusted party. +- `.Insecure`: These variables are marked insecure because they contain client-supplied data that is not signed by a trusted party. -- **.Insecure.CR**: ☠️ +- `.Insecure.CR`: ☠️ This holds the Certificate Request (CSR) received from the client. `.Insecure.CR` is a [`crypto/x509` CertificateRequest](https://pkg.go.dev/crypto/x509#CertificateRequest). How `step-ca` handles a Certificate Request depends on the provisioner. @@ -260,41 +258,41 @@ Here are some variables available in X.509 certificate templates: and the validated SANs from ACME orders. For ACME, step-ca validates that the CSR's subject and SANs only contain values that are in the validated ACME order. -- **.Insecure.CR.DNSNames**: +- `.Insecure.CR.DNSNames`: The DNS Name Subject Alternative Names (SANs) provided in the CSR -- **.Insecure.CR.IPAddresses**: +- `.Insecure.CR.IPAddresses`: The IP Address SANs provided in the CSR -- **.Insecure.CR.URIs**: +- `.Insecure.CR.URIs`: The URI SANs provided in the CSR -- **.Insecure.CR.EmailAddresses**: +- `.Insecure.CR.EmailAddresses`: The Email Address SANs provided in the CSR -- **.Insecure.CR.Subject**: +- `.Insecure.CR.Subject`: The CSR subject field. -- **.Insecure.CR.Subject.CommonName**: +- `.Insecure.CR.Subject.CommonName`: The Common Name (CN) from the CSR subject -- **.Insecure.CR.Subject.ExtraNames**: +- `.Insecure.CR.Subject.ExtraNames`: The Extra Names from the CSR subject. This is an array of all subject distinguished names (DNs) in the CSR. Each contains an OID (`type`) and a value (`value`). -- **.Insecure.CR.RawSubject**: +- `.Insecure.CR.RawSubject`: The original subject asn.1 value from the CSR. Use this if your application requires that the certificate subject and CSR subject match exactly. (Because `step-ca` may re-encode the CSR subject when creating the certificate subject, these values may not match byte-for-byte) -- **.Insecure.CR.PublicKey**: +- `.Insecure.CR.PublicKey`: The public key provided in the certificate request. You can check the request's key type with a conditional, like `{{- if typeIs "*rsa.PublicKey" .Insecure.CR.PublicKey }}`. You can check the request's key size with a conditional, like `{{- if lt .Insecure.CR.PublicKey.Size 384 }}`. -- **.Insecure.User**: +- `.Insecure.User`: This property holds user-supplied data from the certificate request. Users can supply arbitrary values using `--set` or `--set-file` flags in `step ca certificate`. @@ -443,15 +441,15 @@ See [the complete list of fields supported by `step-ca` SSH template](https://gi ### SSH template variables Here are the most relevant parameters available in SSH certificate template: -- **.Token**: +- `.Token`: This property offers the best opportunity for injecting signed, secure data into the certificate. - If a token was used to obtain the certificate, + If a token was used to obtain the certificate, this property contains token payload used in the certificate request. For example, when using an OAuth ID token, `.Token.email` will contain the user's email address. To add custom data to `.Token`, you could use custom OAuth claims, or sign your own JWTs. - -- **.Extensions**: is a map containing extensions. + +- `.Extensions`: is a map containing extensions. The default value for `Extensions` is: ```go @@ -464,39 +462,39 @@ Here are the most relevant parameters available in SSH certificate template: } ``` -- **.CriticalOptions**: is a map containing critical options. +- `.CriticalOptions`: is a map containing critical options. It is empty by default. -- **.Principals**: For users, this value is derived from the OIDC token +- `.Principals`: For users, this value is derived from the OIDC token (when using the [OIDC provisioner](provisioners.mdx#oauthoidc-single-sign-on)). For hosts, it is derived from the Instance Identity Document (when using the [Cloud provisioners](provisioners.mdx#cloud-provisioners)). -- **.KeyID**: +- `.KeyID`: The key ID being requested. -- **.Type**: +- `.Type`: The type of SSH certificate being requested. This will be `user` or `host`. -- **.Insecure.CR**: +- `.Insecure.CR`: SSH certificate requests to `step-ca` are not CSRs in the X.509 sense. Instead, `step-ca` creates a virtual certificate request, and that's what this variable represents. -- **.Insecure.CR.Principals**: If you trust a host to register its own custom SANs +- `.Insecure.CR.Principals`: If you trust a host to register its own custom SANs (for example, when using the IID provisioner), then the host can pass several `--principal` values to [`step ssh certificate`](../step-cli/reference/ssh/certificate) when registering the host, and use `.Insecure.CR.Principals` to access those from a template. -- **.Insecure.CR.Type**: +- `.Insecure.CR.Type`: The type of SSH certificate being requested. This will be `user` or `host`. -- **.Insecure.CR.KeyID**: +- `.Insecure.CR.KeyID`: The key ID being requested. -- **.Insecure.User**: This property holds user-supplied data from the certificate request. +- `.Insecure.User`: This property holds user-supplied data from the certificate request. Users can supply arbitrary values using `--set` or `--set-file` flags in [`step ssh certificate`](../step-cli/reference/ssh/certificate). You can also import parameter values diff --git a/tutorials/connect-intune-to-smallstep.mdx b/tutorials/connect-intune-to-smallstep.mdx index a52d33dd..51dfbde1 100644 --- a/tutorials/connect-intune-to-smallstep.mdx +++ b/tutorials/connect-intune-to-smallstep.mdx @@ -203,7 +203,7 @@ In this step, we’ll tie everything together by creating Windows policy to enro - Name: **Smallstep Agents Authority Intermediate** - In Configuration Settings - Certificate file: (upload the Intermediate certificate you downloaded earlier) - - Destination store: Computer Certificate Store — Root + - Destination store: Computer Certificate Store—Root For legacy reasons, even though we are uploading an Intermediate CA here, we want to store it in the Root store, *not* the Intermediate store. diff --git a/tutorials/connect-workspace-one-to-smallstep.mdx b/tutorials/connect-workspace-one-to-smallstep.mdx index acb1f279..ffea24ae 100644 --- a/tutorials/connect-workspace-one-to-smallstep.mdx +++ b/tutorials/connect-workspace-one-to-smallstep.mdx @@ -111,7 +111,7 @@ In this step, we’ll add the Smallstep Agent to Workspace One UEM for distribut - For Minimum OS, select Windows 10 (10.0.15063) 3. In the Add Application panel’s **Deployment Options** tab, - Set Install Context to **Device** -4. FInally, choose **Save & Assign** +4. Finally, choose **Save & Assign**
diff --git a/tutorials/intermediate-ca-new-ca.mdx b/tutorials/intermediate-ca-new-ca.mdx index f06e4b45..b43db85b 100644 --- a/tutorials/intermediate-ca-new-ca.mdx +++ b/tutorials/intermediate-ca-new-ca.mdx @@ -89,7 +89,7 @@ When you run [`step ca init`](../step-cli/reference/ca/init), it creates artifac - `$STEPPATH/certs/intermediate_ca.crt` the intermediate CA cert - `$STEPPATH/secrets/intermediate_ca_key` the intermediate signing key used by step-ca -`step-ca` does not actually need the root CA signing key. So you can remove that file: +`step-ca` does not actually need the root CA signing key, so you can remove that file: ```shell $ shred -u $(step path)/secrets/root_ca_key @@ -138,7 +138,7 @@ When you run [`step ca init`](../step-cli/reference/ca/init), it creates artifac - `$STEPPATH/secrets/intermediate_ca_key` the intermediate signing key used by step-ca -`step-ca` does not actually need the root CA signing key. So you can remove that file: +`step-ca` does not actually need the root CA signing key, so you can remove that file: ```shell $ shred -u $(step path)/secrets/root_ca_key @@ -273,9 +273,9 @@ That's it! You should now be able to start `step-ca` and generate X.509 certific that can be validated and authenticated by any software that trusts your root certificate. -## Faqs +## FAQs -### Can I have multiple intermediate CAs?? +### Can I have multiple intermediate CAs? Sure. Let's say you have a longer path of intermediate CAs: diff --git a/tutorials/intune-mdm-setup-guide.mdx b/tutorials/intune-mdm-setup-guide.mdx index 78fb56ac..1aea777b 100644 --- a/tutorials/intune-mdm-setup-guide.mdx +++ b/tutorials/intune-mdm-setup-guide.mdx @@ -177,7 +177,7 @@ These instructions may vary depending on your enrollment method. We assume you’ve enabled Automatic Enrollment in Intune’s [Windows enrollment blade](https://intune.microsoft.com/#view/Microsoft_Intune_DeviceSettings/DevicesEnrollmentMenu/~/windowsEnrollment). - For a new device: Go to **Windows Settings → Accounts → Access work or school**. Then , under **Add a work or school account**, choose **Connect** to sign in to your tenant. -- For a previously-enrolled device: Go to **Windows Settings → Accounts → Access work or school**. Expand the box for the signed-in account and select **Info**. Select **Sync**. +- For a previously enrolled device: Go to **Windows Settings → Accounts → Access work or school**. Expand the box for the signed-in account and select **Info**. Select **Sync**. After the sync completes, it may take a minute for the certificate to appear in your Windows trust store. diff --git a/tutorials/mutual-tls-aws.mdx b/tutorials/mutual-tls-aws.mdx deleted file mode 100644 index ba16fbff..00000000 --- a/tutorials/mutual-tls-aws.mdx +++ /dev/null @@ -1,360 +0,0 @@ ---- -updated_at: February 03, 2026 -title: "Mutual TLS advanced example: Use AWS to deploy a private certificate authority and secure microservices" -html_title: Deploy mTLS on AWS for Microservices Tutorial -description: Deploy private CA on AWS for microservice security. Implement mutual TLS between services in cloud environments for Zero Trust architectures. ---- - - -The following example uses [smallstep](https://smallstep.com) open-source -products to securely deploy [Emojivoto](https://github.com/buoyantio/emojivoto) -microservice to AWS using mutual TLS. - -## About this tutorial - -- Learn how to use mutual TLS to connect microservices on AWS securely. -- Examples include copy/paste code blocks and Terraform templates for quick setup. -- When complete, you will have an end-to-end mutual TLS deployment. -- Estimated effort: Reading time ~15 mins, Lab time ~30 to 90 mins. - - -
- If you run into any issues please let us know in GitHub Discussions. -
- - -## Requirements - -- [`step`](../step-cli) -- [`step-ca`](../step-ca) -- [`step-sds`](https://github.com/smallstep/step-sds) -- [`step-aws-emojivoto`](https://github.com/smallstep/step-aws-emojivoto) -- [`aws`](https://aws.amazon.com/) -- [`puppet`](https://puppet.com/) for machine-level provisioning. -- [`terraform`](https://www.terraform.io/) to configure the infrastructure. -- [`envoy`](https://www.envoyproxy.io/) - -## Overview - -- [Microservices deployment architecture](#microservices-deployment-architecture) -- [Step-by-Step Instructions](#step-by-step-instructions) -- [Explore Emojivoto on AWS](#explore-emojivoto-on-aws) - -## Microservices deployment architecture - -This example will use automation to provision an instance of Emojivoto. - -``` - +--------------+ - | BROWSER | - +------|-------+ - | - |TLS - | - +------|-------+ - | ENVOY | - | | | +------------+ - | WEB | | | - | | | TLS+mTLS | CA | - | ENVOY--SDS+-----------------+ | - +------|-------+ +-----|------+ - | | - | | - | |TLS+mTLS - mTLS | mTLS | - +----------|----------+ | - | | | - | | | -+-----|-------+ +-----|--------+ | -| ENVOY | | ENVOY | | -| | | | | | -| EMOJI--SDS| | VOTING--SDS+-----------+ -+-----------|-+ +--------------+ | - | | - | | - | | - +------------------------------------+ -``` - -- Emojivoto does not support (m)TLS -- Every service in the diagram above will run on its own dedicated VM (EC2 instance) in AWS. -- An Envoy sidecar proxy (ingress and egress) per service will handle mutual TLS (authentication and encryption). -- Envoy sidecars obtain X.509 certificates through the secret discovery service (SDS) exposed via a local UNIX domain socket. -- `step-sds` will fetch a certificate and the trust bundle (root certificate) from the internal certificate authority on behalf of each service/sidecar pair. -- `step-sds` will handle renewals for X.509 certificates that are nearing the end of their lifetimes. - -## Step-by-step instructions - -This AWS example integration will use full automation to provision infrastructure, machines, and services from scratch. While there are many tools available, in this exercise, we chose to use Terraform and Puppet for provisioning. - -Before getting started with the provisioning process, you need to configure AWS (account credentials and permissions), SSH, and Terraform. - -### 1. Clone `step-aws-emojivoto` - -Clone the repository that has puppet and terraform files that you will use later: - -```shell -git clone https://github.com/smallstep/step-aws-emojivoto.git -``` - - -### 2. Set up AWS CLI - -Install and configure the AWS CLI. AWS has instructions for installing the CLI on various platforms at: [https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) - -Once installed, get your AWS credentials from your account or AWS IAM depending on what you're using and follow the interactive steps of the `aws configure` command. The [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) has detailed instructions on how to get AWS credentials. - -Make sure the credentials granted from the IAM policies include _AmazonEC2FullAccess_, _AmazonVPCFullAccess_, and _AmazonRoute53FullAccess_ (broad permissions) or at the minimum permissions as per the [policy file included in the repo](https://github.com/smallstep/step-aws-emojivoto/blob/master/policy.json). - -```shell-session nocopy -$ aws configure -AWS Access Key ID []: ****************UJ7U -AWS Secret Access Key []: ****************rUg8 -Default region name []: us-west-1 -Default output format []: json - -$ aws s3 ls -# Should list S3 buckets if the account has any -2017-10-26 13:50:39 smallstep-not-a-real-bucket -2017-10-26 15:43:20 smallstep-fake-bucket -2018-04-09 17:25:18 smallstep-nobody-home -``` - -### 3. Generate a SSH key pair - -Terraform requires a key pair to be used for provisioning EC2 machine instances. Any key pair available in the respective region will work as long as the local Terraform/Puppet process has access to the key pair's private key. Please see the [AWS EC2 Key Pairs documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) for details on how to manage key pairs in AWS. - -The EC2 key pair will likely be available as a single file in _PEM_ format. Use the following commands to convert the _PEM_ and place the resulting files in locations where Terraform and Puppet can locate them. - -```shell-session nocopy -$ chmod 400 aws-e2e-howto.pem -# We will need the public key in terraform config -$ ssh-keygen -f aws-e2e-howto.pem -y > ~/.ssh/terraform.pub -# The private key is already in the correct format -$ cp aws-e2e-howto.pem ~/.ssh/terraform -# New files only readable by owner (not encrypted on disk!) -$ chmod 400 ~/.ssh/terraform* -``` - -**Note**: it's not required to use key pairs generated by AWS. `ssh-keygen` or `step` will work if you are familiar with or prefer local key generation. - -### 4. Run Terraform - -Terraform uses a backend hosted by [HashiCorp](https://app.terraform.io/session) to store state information about managed infrastructure as well as manage concurrency locks to allow only one team member to perform changes at a time. The CLI needs a user configuration as outlined below. Create a user account and organization at [app.terraform.io](https://app.terraform.io/session) and get a user token. For more details, see [HashiCorp's Terraform CLI docs](https://www.terraform.io/docs/commands/cli-config.html). - -**Note**: terraform won't strictly require a backend when being used by a single developer/operator - -```shell-session nocopy -$ cat ~/.terraformrc -credentials "app.terraform.io" { - token = "" -} -``` - -Once the _~/.terraformrc_ is in place, the Terraform backend needs to be initialized. Before running `terraform init`, Terraform needs to be configured with the proper workplace, organization, and SSH public key. - -```shell-session nocopy -diff --git a/aws-emojivoto/emojivoto.tf b/aws-emojivoto/emojivoto.tf -index b510dcb..33ff92d 100644 ---- a/aws-emojivoto/emojivoto.tf -+++ b/aws-emojivoto/emojivoto.tf -@@ -1,9 +1,9 @@ - terraform { - backend "remote" { -- organization = "Smallstep" -+ organization = ""\n - workspaces { -- name = "Emojivoto" -+ name = "" - } - } - } -@@ -17,7 +17,7 @@ provider "aws" { - # Create an SSH key pair to connect to our instances - resource "aws_key_pair" "terraform" { - key_name = "terraform-key" -- public_key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCVEhUwiAivgdFuu5rOv8ArAMqTA6N56yd5RA+uHdaC0e4MM3TYhUOwox0fV+opE3OKLYdG2+mF/6Z4k8PgsBxLpJxdQ9XHut3A9WoqCEANVfZ7dQ0mgJs1MijIAbVg1kXgYTg/2iFN6FCO74ewAJAL2e8GqBDRkwIueKbphmO5U0mK3d/nnLK0QSFYgQGFGFHvXkeQKus+625IHifat/GTZZmhCxZBcAKzaAWB8dSaZGslaKsixy3EGiY5Gqdi5tQvt+obxZ59o4Jk352YlxhlUSxoxpeOyCiBZkexZgm+0MbeBrDuOMwg/tpcUiJ0/lVomx+dQuIX6ciKIuwnvDhx" -+ public_key = "" - } - - variable "ami" { -``` - -Once the AWS CLI, Terraform CLI, and definitions are in place, you can initialize the workspace on the Terraform backend: - -```shell-session nocopy -$ terraform init - -Initializing the backend... - -Successfully configured the backend "remote"! Terraform will automatically -use this backend unless the backend configuration changes. - -Initializing provider plugins... -- Finding latest version of hashicorp/aws... -- Installing hashicorp/aws v3.3.0... -- Installed hashicorp/aws v3.3.0 (signed by HashiCorp) - -The following providers do not have any version constraints in configuration, -so the latest version was installed. - -To prevent automatic upgrades to new major versions that may contain breaking -changes, we recommend adding version constraints in a required_providers block -in your configuration, with the constraint strings suggested below. - -* hashicorp/aws: version = "~> 3.3.0" - -Terraform has been successfully initialized! -[...] -``` - -Now Terraform is ready to go. The `terraform apply` command will print out a long execution plan of all the infrastructure that will be created. Terraform will prompt for a confirmation before executing on the plan. The completion of this process can take some time. - -```shell-session nocopy -$ terraform apply - -An execution plan has been generated and is shown below. -Resource actions are indicated with the following symbols: - + create - -Terraform will perform the following actions: - - # aws_instance.ca will be created - + resource "aws_instance" "ca" { - + ami = "ami-068670db424b01e9a" - + arn = (known after apply) - + associate_public_ip_address = true - + availability_zone = (known after apply) - + cpu_core_count = (known after apply) - + cpu_threads_per_core = (known after apply) - + get_password_data = false - + host_id = (known after apply) - + id = (known after apply) - + instance_state = (known after apply) - + instance_type = "t2.micro" - + ipv6_address_count = (known after apply) - + ipv6_addresses = (known after apply) - + key_name = "terraform-key" - + outpost_arn = (known after apply) - + password_data = (known after apply) - + placement_group = (known after apply) - + primary_network_interface_id = (known after apply) - + private_dns = (known after apply) - + private_ip = (known after apply) - + public_dns = (known after apply) - + public_ip = (known after apply) - + secondary_private_ips = (known after apply) - + security_groups = (known after apply) - + source_dest_check = true - + subnet_id = (known after apply) - + tags = { - + "Name" = "emojivoto-ca" - } -[...] -Plan: 25 to add, 0 to change, 0 to destroy. - -Changes to Outputs: - + ca_ip = (known after apply) - + emoji_ip = (known after apply) - + puppet_ip = (known after apply) - + voting_ip = (known after apply) - + web_ip = (known after apply) - -Do you want to perform these actions? - Terraform will perform the actions described above. - Only 'yes' will be accepted to approve. - - Enter a value: yes -``` - -After some wait time, Terraform will confirm the successful completion and print out details about the newly created infrastructure: - -```shell-session nocopy -[...] -Apply complete! Resources: 25 added, 0 changed, 0 destroyed. - -Outputs: - -ca_ip = 54.215.253.52 -emoji_ip = 18.144.15.156 -puppet_ip = 3.101.105.64 -voting_ip = 3.101.28.150 -web_ip = 54.176.66.184 -``` - -## Explore emojivoto on AWS - -AWS Emojivoto uses internal DNS records to resolve hosts for inter-service communication. All TLS certificates are issued for the respective DNS name, like _web.emojivoto.local_ or _voting.emojivoto.local_ (see [dns.tf](https://github.com/smallstep/step-aws-emojivoto/blob/master/dns.tf) for details). - -For this to work on machines without managed external DNS, the hostname/IP -address mapping needs to be added to _/etc/hosts_ so that hostnames can be -verified against server X.509 certificates. - -```shell-session nocopy -$ cat /etc/hosts -127.0.0.1 localhost -::1 localhost - -54.176.66.184 web.emojivoto.local -``` - -**Using step** - -```shell-session nocopy -$ step certificate inspect --roots root_ca.crt --short https://web.emojivoto.local -X.509v3 TLS Certificate (ECDSA P-256) [Serial: 1969...9717] - Subject: web.emojivoto.local - Issuer: Smallstep Test Intermediate CA - Provisioner: step-sds [ID: Z2S-...gK6U] - Valid from: 2020-08-27T01:51:26Z - to: 2020-08-28T01:51:26Z -``` - -**Using cURL** - -```shell-session nocopy -$ curl -I --cacert root_ca.crt https://web.emojivoto.local -HTTP/1.1 200 OK -content-type: text/html -date: Thu, 27 Aug 2020 01:54:55 GMT -content-length: 560 -x-envoy-upstream-service-time: 0 -server: envoy - -# Without --cacert specifying the root cert it will fail (expected) -$ curl -I https://web.emojivoto.local -curl: (60) SSL certificate problem: unable to get local issuer certificate -More details here: https://curl.haxx.se/docs/sslcerts.html - -curl failed to verify the legitimacy of the server and therefore could not -establish a secure connection to it. To learn more about this situation and -how to fix it, please visit the web page mentioned above. -``` - -**Using a browser** - -Navigating a browser to _https://web.emojivoto.local/_ will result in a big alert warning that `Your connection is not private`. The reason for the alert is `NET::ERR_CERT_AUTHORITY_INVALID` which a TLS error code. The error code means that the certificate path validation could not be verified against the locally known root certificates in the trust store. - -Since the TLS cert for AWS Emojivoto's web service is not using _Public Web PKI_ this is expected. Beware of these warnings in production settings. In this particular case where you're using an internal CA, it's safe to click `Proceed to web.emojivoto.local` under the _Advanced_ menu. - -It is possible to avoid the TLS warning by installing the internal CA's root certificate into your local trust store, `step` has a command to do that: - -```shell-session nocopy -$ sudo step certificate install root_ca.crt -Certificate root_ca.crt has been installed. -X.509v3 Root CA Certificate (ECDSA P-256) [Serial: 1038...4951] - Subject: Smallstep Test Root CA - Issuer: Smallstep Test Root CA - Valid from: 2019-07-12T22:14:14Z - to: 2029-07-09T22:14:14Z -# Navigate browser to https://web.emojivoto.local without warning. - -$ step certificate uninstall root_ca.crt -Certificate root_ca.crt has been removed. -X.509v3 Root CA Certificate (ECDSA P-256) [Serial: 1038...4951] - Subject: Smallstep Test Root CA - Issuer: Smallstep Test Root CA - Valid from: 2019-07-12T22:14:14Z - to: 2029-07-09T22:14:14Z -# Remove root cert from local trust store. warning will reappear. -``` diff --git a/tutorials/user-authentication.mdx b/tutorials/user-authentication.mdx index b16f3dfa..239652f8 100644 --- a/tutorials/user-authentication.mdx +++ b/tutorials/user-authentication.mdx @@ -6,7 +6,7 @@ description: Connect identity providers to issue X.509 certificates. Bridge user --- -Smallstep makes running your own private CA and managing certificates for internal services easy. Open source `step-ca` also supports OAuth for provisioning X.509 certificates for user authentication. We make it easy for developers to obtain a certificate via single sign-on using your existing identity provider (Google, Okta, Active Directory, ...). Issued certificates are signed by the CA and trusted by all your workloads and services so you can use mTLS everywhere. +Smallstep makes running your own private CA and managing certificates for internal services easy. Open source `step-ca` also supports OAuth for provisioning X.509 certificates for user authentication. We make it easy for developers to obtain a certificate via single sign-on using your existing identity provider (Google, Okta, Active Directory, ...). Issued certificates are signed by the CA and trusted by all your workloads and services so you can use mTLS everywhere.
diff --git a/tutorials/wifi-setup-guide.mdx b/tutorials/wifi-setup-guide.mdx index fbd39a10..9e3e1640 100644 --- a/tutorials/wifi-setup-guide.mdx +++ b/tutorials/wifi-setup-guide.mdx @@ -28,21 +28,21 @@ For MDM enrollment, we have integrations and tutorials for [Jamf](https://smalls
-## On this page, you'll find: +## On this page, you'll find: -- [Protect a Wi-Fi Resource in Smallstep](#protect-a-Wi-Fi-resource-in-smallstep) +- [Protect a Wi-Fi Resource in Smallstep](#protect-a-wi-fi-resource-in-smallstep) - [Configure 802.1x EAP-TLS on any Access Point](#general-instructions-for-configuring-8021x-eap-tls-on-any-access-point) - Instructions for specific Access Points: - - [Ubiquiti Unifi](#configure-8021x-eap-tls-wpa-enterprise-Wi-Fi-on-ubiquiti-unifi) - - [Aerohive](#configure-8021x-eap-tls-wpa-enterprise-Wi-Fi-on-aerohive) - - [Aruba](#configure-8021x-eap-tls-wpa-enterprise-Wi-Fi-on-aruba) - - [Asus](#configure-8021x-eap-tls-wpa-enterprise-Wi-Fi-on-asus) - - [Cisco Wireless LAN Controller](#configure-8021x-eap-tls-wpa-enterprise-Wi-Fi-on-cisco-wireless-lan-controller) - - [Extreme Networks](#configure-8021x-eap-tls-wpa-enterprise-Wi-Fi-on-extreme) - - [Juniper Mist](#configure-8021x-eap-tls-wpa-enterprise-Wi-Fi-on-juniper-mist) - - [Meraki](#configure-8021x-eap-tls-wpa-enterprise-Wi-Fi-on-meraki) - - [MikroTik](#configure-8021x-eap-tls-wpa-enterprise-Wi-Fi-on-mikrotik) - - [Sophos UTM](#configure-8021x-eap-tls-wpa-enterprise-Wi-Fi-on-sophos-utm) + - [Ubiquiti Unifi](#configure-8021x-eap-tls-wpa-enterprise-wi-fi-on-ubiquiti-unifi) + - [Aerohive](#configure-8021x-eap-tls-wpa-enterprise-wi-fi-on-aerohive) + - [Aruba](#configure-8021x-eap-tls-wpa-enterprise-wi-fi-on-aruba) + - [Asus](#configure-8021x-eap-tls-wpa-enterprise-wi-fi-on-asus) + - [Cisco Wireless LAN Controller](#configure-8021x-eap-tls-wpa-enterprise-wi-fi-on-cisco-wireless-lan-controller) + - [Extreme Networks](#configure-8021x-eap-tls-wpa-enterprise-wi-fi-on-extreme) + - [Juniper Mist](#configure-8021x-eap-tls-wpa-enterprise-wi-fi-on-juniper-mist) + - [Meraki](#configure-8021x-eap-tls-wpa-enterprise-wi-fi-on-meraki) + - [MikroTik](#configure-8021x-eap-tls-wpa-enterprise-wi-fi-on-mikrotik) + - [Sophos UTM](#configure-8021x-eap-tls-wpa-enterprise-wi-fi-on-sophos-utm) ## Protect a Wi-Fi resource in Smallstep @@ -213,7 +213,7 @@ Your new 802.1x EAP-TLS WPA-Enterprise Wi-Fi network is ready for use. ![Meraki EAP-TLS Wi-Fi setup](/graphics/meraki.png) 5. Set the **Association requirements** to **Enterprise with my RADIUS server** -6. Scroll to **RADIUS servers** to add your Smallstep RADIUS server. Enter the RADIUS server IP address, port, and shared secret, you received from Smallstep into their respective fields +6. Scroll to **RADIUS servers** to add your Smallstep RADIUS server. Enter the RADIUS server IP address, port, and shared secret you received from Smallstep into their respective fields 7. Click **Save** Your new 802.1x EAP-TLS WPA-Enterprise Wi-Fi network is ready for use.