diff --git a/.github/mdl.config.json b/.github/mdl.config.json index 854430f5..c0d5255d 100644 --- a/.github/mdl.config.json +++ b/.github/mdl.config.json @@ -29,6 +29,30 @@ }, { "pattern": "^https://www.arubanetworks.com" + }, + { + "pattern": "^https://admin.google.com" + }, + { + "pattern": "^https://azure.microsoft.com" + }, + { + "pattern": "^https://www.gnu.org" + }, + { + "pattern": "^https://freedesktop.org" + }, + { + "pattern": "^https://www.hashicorp.com" + }, + { + "pattern": "^https://github.com/Neilpang/acme.sh/issues/2422" + }, + { + "pattern": "^https://arubanetworking.hpe.com" + }, + { + "pattern": "^https://www.w3.org" } ], "replacementPatterns": [ diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml index 4a1c6ea6..334ce50a 100644 --- a/.github/workflows/link-check.yml +++ b/.github/workflows/link-check.yml @@ -1,9 +1,10 @@ -name: Check Markdown links in merges +name: Check Markdown links on: push: branches: - main + pull_request: jobs: markdown-link-check: @@ -11,8 +12,26 @@ jobs: timeout-minutes: 60 steps: - uses: actions/checkout@v4 - - uses: gaurav-nelson/github-action-markdown-link-check@v1 with: - file-extension: '.mdx' - use-quiet-mode: 'yes' - config-file: '.github/mdl.config.json' + fetch-depth: 0 + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: '20' + - name: Install markdown-link-check + run: npm install -g markdown-link-check + - name: Check all links (push to main) + if: github.event_name == 'push' + run: | + find . -name '*.mdx' -print0 | xargs -0 -n1 markdown-link-check --config .github/mdl.config.json -q + - 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') + if [ -z "$CHANGED_FILES" ]; then + echo "No .mdx files changed" + exit 0 + fi + echo "Checking changed files:" + echo "$CHANGED_FILES" + echo "$CHANGED_FILES" | xargs -n1 markdown-link-check --config .github/mdl.config.json -q diff --git a/certificate-manager/getting-started.mdx b/certificate-manager/getting-started.mdx index 5237e24f..805f6f2c 100644 --- a/certificate-manager/getting-started.mdx +++ b/certificate-manager/getting-started.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 06, 2025 +updated_at: January 20, 2026 title: Smallstep Certificate Manager Getting Started html_title: Get Started with Certificate Manager Guide description: Get started with Certificate Manager in minutes. Quick setup guide for enterprise certificate automation and PKI management with best practices. @@ -52,7 +52,7 @@ storing the private keys into [Google's Cloud KMS](https://cloud.google.com/secu
You can bring your own root CA to Smallstep. To enable this feature on your account, - please [Create a Support Ticket](https://support.smallstep.com/kb-tickets/new). + please [Create a Support Ticket](https://support.smallstep.com/en/contact-us). Be sure to include your team name. This feature requires an Advanced Authority.
diff --git a/certificate-manager/how-it-works.mdx b/certificate-manager/how-it-works.mdx index 771f3588..cedf90cd 100644 --- a/certificate-manager/how-it-works.mdx +++ b/certificate-manager/how-it-works.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 06, 2025 +updated_at: January 20, 2026 title: Smallstep Certificate Manager How It Works html_title: Certificate Manager Architecture Guide description: Technical architecture of Certificate Manager. Understand components, workflows, and security model for enterprise PKI deployment planning. @@ -220,7 +220,7 @@ authority, provisioner, and other certificate details. The Smallstep API can be used to manage your authorities programmatically. The API is currently an alpha release with limited availability. -Request access to this API for your account by [creating a support ticket](https://support.smallstep.com/kb-tickets/new) for our Customer Engineering team. Be sure to include your team name in your request. +Request access to this API for your account by [creating a support ticket](https://support.smallstep.com/en/contact-us) for our Customer Engineering team. Be sure to include your team name in your request. # Certificate Manager in Action diff --git a/ssh/how-it-works.mdx b/ssh/how-it-works.mdx index b8993b7c..fec6c944 100644 --- a/ssh/how-it-works.mdx +++ b/ssh/how-it-works.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 06, 2025 +updated_at: January 20, 2026 title: Smallstep SSH How It Works html_title: How SSH Certificates Work - Technical Guide description: Technical overview of SSH certificate authentication. Learn how certificates replace keys for better security and management in modern SSH. @@ -93,7 +93,7 @@ Smallstep SSH is designed for environments that are continually changing. We aut The Smallstep API can be used to read and manage your host access control settings programmatically. The API is currently an alpha release with limited availability. -Request access to this API for your account by [creating a support ticket](https://support.smallstep.com/kb-tickets/new) for our Customer Engineering team. Be sure to include your team name in your request. +Request access to this API for your account by [creating a support ticket](https://support.smallstep.com/en/contact-us) for our Customer Engineering team. Be sure to include your team name in your request. ## Secure and Highly Available diff --git a/step-ca/certificate-authority-core-concepts.mdx b/step-ca/certificate-authority-core-concepts.mdx index 0fa77193..6cea8425 100644 --- a/step-ca/certificate-authority-core-concepts.mdx +++ b/step-ca/certificate-authority-core-concepts.mdx @@ -1,5 +1,5 @@ --- -updated_at: September 17, 2025 +updated_at: January 20, 2026 title: Certificate Authority Core Concepts html_title: Core CA Concepts and Architecture Explained description: Essential concepts for running a certificate authority. Understand CA architecture, trust models, and security considerations. @@ -105,7 +105,7 @@ When in RA mode, `step-ca` can peer with three kinds of upstream CA: - Another `step-ca` server ("StepCAS" mode) - A [Google CloudCAS](https://cloud.google.com/certificate-authority-service/) CA -- A [Hashicorp Vault](https://www.hashicorp.com/products/vault) CA +- A [Hashicorp Vault](https://www.hashicorp.com/en/products/vault) CA ![Example PKI topology with StepCAS RA Mode](/graphics/stepcas-ra-mode.png) diff --git a/step-ca/certificate-authority-server-production.mdx b/step-ca/certificate-authority-server-production.mdx index 7995da08..42e96223 100644 --- a/step-ca/certificate-authority-server-production.mdx +++ b/step-ca/certificate-authority-server-production.mdx @@ -2,7 +2,7 @@ title: Production considerations when running a certificate authority server html_title: Certificate authority server production considerations description: Learn about the important production considerations and sane cryptographic defaults that operators should know about when running a certificate authority server -updated_at: July 07, 2025 +updated_at: January 20, 2026 --- @@ -70,7 +70,7 @@ See [Cryptographic Protection](./cryptographic-protection.mdx) to learn more abo ### Use Strong Passwords and Store Them Well -When you [initialize your PKI](./getting-started.mdx#initialize-your-certificate-authority), +When you [initialize your PKI](./getting-started.mdx#initialize-your-certificate-authority-ca), the root and intermediate private keys will be encrypted with the same password. Use a password manager to generate random passwords, @@ -138,7 +138,7 @@ See our blog [How to Handle Secrets on the Command Line](https://smallstep.com/b ### Replace Your Default Provisioner -When you [initialize your PKI](./getting-started.mdx#initialize-your-certificate-authority), +When you [initialize your PKI](./getting-started.mdx#initialize-your-certificate-authority-ca), a default `JWK` provisioner will be created. If you're not going to use this provisioner, we recommend deleting it. diff --git a/step-ca/getting-started.mdx b/step-ca/getting-started.mdx index e1e69fc8..77edd94d 100644 --- a/step-ca/getting-started.mdx +++ b/step-ca/getting-started.mdx @@ -1,5 +1,5 @@ --- -updated_at: September 18, 2025 +updated_at: January 20, 2026 title: Getting Started html_title: Getting Started with step-ca Installation description: Get started with step-ca certificate authority. Complete guide to installing and running your first private PKI infrastructure from scratch. @@ -11,7 +11,7 @@ You could write several telephone books about the innards of X.509, asn.1, and t In this guide, you will: -- [Initialize your certificate authority](#initialize-your-certificate-authority) +- [Initialize your certificate authority](#initialize-your-certificate-authority-ca) - [Run your certificate authority](#run-your-certificate-authority) - [Example: Run A Local Web Server Using TLS](#example-run-a-local-web-server-using-tls) diff --git a/step-ca/provisioners.mdx b/step-ca/provisioners.mdx index 2e2134d7..5f100776 100644 --- a/step-ca/provisioners.mdx +++ b/step-ca/provisioners.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 12, 2025 +updated_at: January 20, 2026 title: Configuring step-ca Provisioners html_title: Configure Certificate Provisioners in step-ca description: Master step-ca provisioners for flexible certificate issuance. Support multiple authentication methods from OIDC to cloud metadata. @@ -431,7 +431,7 @@ Without the `encryptedKey` attribute, the private key must be provided by the cl - **claims**: overwrites the default claims set in the authority. See [claims](configuration.mdx#claims) for details. -- **options**: see [template configuration](templates.mdx#configuring-the-ca-to-use-templates) for more details. +- **options**: see [template configuration](templates.mdx#configuring-step-ca-to-use-templates) for more details. Recommended Optional @@ -683,7 +683,7 @@ Example `ca.json` provisioner configuration for a Google provisioner: - **claims**: overwrites the default claims set in the authority, see the [claims](configuration.mdx#claims) section for all the options. -- **options**: see [template configuration](templates.mdx#configuring-the-ca-to-use-templates) for more details. +- **options**: see [template configuration](templates.mdx#configuring-step-ca-to-use-templates) for more details. Optional @@ -806,7 +806,7 @@ tokens. - **claims**: overwrites the default claims set in the authority, see the [claims](configuration.mdx#claims) section for all the options. -- **options**: see [template configuration](templates.mdx#configuring-the-ca-to-use-templates) for more details. +- **options**: see [template configuration](templates.mdx#configuring-step-ca-to-use-templates) for more details. Optional @@ -918,7 +918,7 @@ An example SSHPOP provisioner in the `ca.json`: - **claims**: overwrites the default `claims` set in the authority, see the [claims](configuration.mdx#claims) section for all the options. -- **options**: see [template configuration](templates.mdx#configuring-the-ca-to-use-templates) for more details. +- **options**: see [template configuration](templates.mdx#configuring-step-ca-to-use-templates) for more details. Optional @@ -990,7 +990,7 @@ Here's an example of an ACME provisioner configuration in `ca.json`: - **claims**: overwrites the default claims set in the authority, see the [claims](configuration.mdx#claims) section for all the options. -- **options**: see [template configuration](templates.mdx#configuring-the-ca-to-use-templates) for more details. +- **options**: see [template configuration](templates.mdx#configuring-step-ca-to-use-templates) for more details. - **termsOfService**: contains a URL pointing to the ACME server's terms of service. Defaults to empty. @@ -1229,7 +1229,7 @@ Here's an example of an ACME provisioner with Wire support enabled in `$(step pa ``` * **challenges**: to enable the Wire integration, `wire-oidc-01` and `wire-dpop-01` must be set. -* **options**: with the Wire integration enabled, the certificate template can include (transformed) properties from the OIDC and DPoP tokens (e.g. `.Oidc.preferred_username`, and `.Dpop.sub`). See [template configuration](templates.mdx#configuring-the-ca-to-use-templates) for more template configuration details. +* **options**: with the Wire integration enabled, the certificate template can include (transformed) properties from the OIDC and DPoP tokens (e.g. `.Oidc.preferred_username`, and `.Dpop.sub`). See [template configuration](templates.mdx#configuring-step-ca-to-use-templates) for more template configuration details. * **discoveryBaseUrl**: sets the OIDC discovery URL, automatically configuring the OIDC provider. If provided, the other `oidc` configuration options are ignored. * **issuerUrl**: sets the OIDC issuer URL. Ignored if `discoveryBaseUrl` is set. * **authorizationUrl**: sets the OIDC authorization URL. Ignored if `discoveryBaseUrl` is set. @@ -1386,7 +1386,7 @@ K8sSA tokens. - **claims**: overwrites the default claims set in the authority, see the [claims](configuration.mdx#claims) section for all the options. -- **options**: see [template configuration](templates.mdx#configuring-the-ca-to-use-templates) for more details. +- **options**: see [template configuration](templates.mdx#configuring-step-ca-to-use-templates) for more details. Optional @@ -1536,7 +1536,7 @@ Limits certificate issuance to new instances to mitigate the risk of credential- - **claims**: overwrites the default claims set in the authority, see the [claims](configuration.mdx#claims) section for all the options. -- **options**: see [template configuration](templates.mdx#configuring-the-ca-to-use-templates) for more details. +- **options**: see [template configuration](templates.mdx#configuring-step-ca-to-use-templates) for more details. Optional @@ -1610,7 +1610,7 @@ Limits certificate issuance to new instances to mitigate the risk of credential- - **claims**: overwrites the default claims set in the authority, see the [claims](configuration.mdx#claims) section for all the options. -- **options**: see [template configuration](templates.mdx#configuring-the-ca-to-use-templates) for more details. +- **options**: see [template configuration](templates.mdx#configuring-step-ca-to-use-templates) for more details. Optional @@ -1678,6 +1678,6 @@ In the `ca.json`, an Azure provisioner looks like: - **claims**: overwrites the default claims set in the authority, see the [claims](configuration.mdx#claims) section for all the options. -- **options**: see [template configuration](templates.mdx#configuring-the-ca-to-use-templates) for more details. +- **options**: see [template configuration](templates.mdx#configuring-step-ca-to-use-templates) for more details. Optional diff --git a/step-ca/registration-authority-ra-mode.mdx b/step-ca/registration-authority-ra-mode.mdx index 19cb4e19..c52d9e1f 100644 --- a/step-ca/registration-authority-ra-mode.mdx +++ b/step-ca/registration-authority-ra-mode.mdx @@ -1,5 +1,5 @@ --- -updated_at: September 18, 2025 +updated_at: January 20, 2026 title: Registration Authority Mode html_title: Configure Registration Authority Mode in step-ca description: Configure step-ca as a Registration Authority. Separate certificate issuance from signing for enhanced security architecture. @@ -32,7 +32,7 @@ When in RA mode, `step-ca` can peer with one of three types of upstream CA: - Another `step-ca` server ("StepCAS" mode) - A [Google CloudCAS](https://cloud.google.com/certificate-authority-service/) CA -- A [Hashicorp Vault](https://www.hashicorp.com/products/vault) CA +- A [Hashicorp Vault](https://www.hashicorp.com/en/products/vault) CA ## Configuring RA Modes diff --git a/step-ca/templates.mdx b/step-ca/templates.mdx index 449f513c..7aef9caf 100644 --- a/step-ca/templates.mdx +++ b/step-ca/templates.mdx @@ -2,7 +2,7 @@ title: Configuring step-ca Templates html_title: Certificate Template Reference for step-ca description: Create and manage certificate templates in step-ca. Customize certificate attributes for specific use cases and compliance requirements. -updated_at: September 18, 2025 +updated_at: January 20, 2026 --- People use private CAs for all sorts of things, in many different contexts: @@ -300,7 +300,7 @@ Here are some variables available in X.509 certificate templates: You can also import values from the `"templateData"` object -in your provisioner's [configuration block](#configuring-the-ca-to-use-templates). +in your provisioner's [configuration block](#configuring-step-ca-to-use-templates). ### ASN.1 Values @@ -436,7 +436,7 @@ Here is `step-ca`'s default [SSH certificate template](https://github.com/smalls ### SSH Template Fields -The [OpenSSH certificate protocol spec](https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.certkeys) defines SSH certificate fields and the available Critical Options and Extensions. +The [OpenSSH certificate protocol spec](https://datatracker.ietf.org/doc/draft-miller-ssh-cert/) defines SSH certificate fields and the available Critical Options and Extensions. Third parties can also add custom extensions. See [the complete list of fields supported by `step-ca` SSH template](https://github.com/smallstep/crypto/blob/master/sshutil/certificate.go#L16). @@ -500,7 +500,7 @@ Here are the most relevant parameters available in SSH certificate template: 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 -from your provisioner's [configuration block](#configuring-the-ca-to-use-templates). +from your provisioner's [configuration block](#configuring-step-ca-to-use-templates).
diff --git a/tutorials/acme-protocol-acme-clients.mdx b/tutorials/acme-protocol-acme-clients.mdx index b48aeab5..c50d5969 100644 --- a/tutorials/acme-protocol-acme-clients.mdx +++ b/tutorials/acme-protocol-acme-clients.mdx @@ -1,5 +1,5 @@ --- -updated_at: November 06, 2025 +updated_at: January 20, 2026 title: Configure popular ACME clients to use a private CA with the ACME protocol html_title: Configure ACME Clients with step-ca Tutorial description: Configure popular ACME clients with step-ca. Support for Certbot, acme.sh, and other ACME implementations for automated certificate management. @@ -364,7 +364,7 @@ server { With this code, you are telling NGINX to listen on port 443 using TLS, with a certificate and private key stored on disk. [Other resources][nginx-le-docker] provide a more thorough explanation of NGINX's various TLS configuration options. -[nginx-le-docker]: https://medium.com/@pentacent/nginx-and-lets-encrypt-with-docker-in-less-than-5-minutes-b4b8a60d3a71 +[nginx-le-docker]: https://nginx.org/en/docs/http/configuring_https_servers.html We can start an HTTP server using python and check our work with curl: diff --git a/tutorials/browser-certificate-setup-guide.mdx b/tutorials/browser-certificate-setup-guide.mdx index 969a3ce9..317c1526 100644 --- a/tutorials/browser-certificate-setup-guide.mdx +++ b/tutorials/browser-certificate-setup-guide.mdx @@ -1,6 +1,6 @@ --- title: Configure Web Browser Certificates -updated_at: September 17, 2025 +updated_at: January 20, 2026 html_title: Browser mTLS Certificate Setup Tutorial description: Configure browser certificates for mutual TLS authentication. Enable secure web access with client certificates across all browsers. --- @@ -27,7 +27,7 @@ Smallstep browser certificates are available for macOS, Windows, and Linux devic Before you begin, make sure: 1. Your devices are [enrolled into your Smallstep inventory](https://smallstep.com/docs/platform/enrollment-guide/). -2. Someone from [our support team](https://support.smallstep.com/kb-tickets/new) has helped you get set up. Client certificates can be used in several ways. Confirm that your Smallstep team is configured for the resource that you are using client certificates to protect. +2. Someone from [our support team](https://support.smallstep.com/en/contact-us) has helped you get set up. Client certificates can be used in several ways. Confirm that your Smallstep team is configured for the resource that you are using client certificates to protect. You will need a list of URLs that will require a client certificate on your devices. diff --git a/tutorials/vpn-client-setup-guide.mdx b/tutorials/vpn-client-setup-guide.mdx index f66ab7c2..2f6547f3 100644 --- a/tutorials/vpn-client-setup-guide.mdx +++ b/tutorials/vpn-client-setup-guide.mdx @@ -1,6 +1,6 @@ --- title: Configure Your VPN Client For Certificate-Based VPN With Smallstep -updated_at: June 3, 2024 +updated_at: January 20, 2026 html_title: How to configure common VPN servers to use Smallstep for client and server certificate authentication. description: This tutorial describes how to configure VPN servers for a high-security, certificate-based VPN with Smallstep. --- @@ -13,8 +13,8 @@ Site-to-site VPNs are not officially supported, but Smallstep can issue certific The following VPN clients are covered in this document: - [IKEv2 EAP-TLS VPN](#ikev2-eap-tls) -- [F5 SSL VPN](#f5-ssl-vpn) -- [OpenVPN](#openvpn) +- [F5 Edge and F5 Access Clients](#f5-edge-and-f5-access-clients) +- [Juniper SSL-VPN](#juniper-ssl-vpn) - [Cisco Meraki AnyConnect](#cisco-meraki-anyconnect) ## IKEv2 EAP-TLS diff --git a/tutorials/wifi-authentication-webhooks.mdx b/tutorials/wifi-authentication-webhooks.mdx index ee430531..a4e9d40e 100644 --- a/tutorials/wifi-authentication-webhooks.mdx +++ b/tutorials/wifi-authentication-webhooks.mdx @@ -1,5 +1,5 @@ --- -updated_at: September 08, 2025 +updated_at: January 20, 2026 title: "Wi-Fi Authentication Webhooks" html_title: "Wi-Fi Authentication Webhooks" description: Smallstep's RADIUS server can call external webhooks for EAP-TLS authorization decisions. @@ -15,7 +15,7 @@ Smallstep can authenticate to your webhook server using a bearer token or HTTP b ## Configuring a RADIUS Webhook in Smallstep -Our [customer support team](https://support.smallstep.com/kb-tickets/new) can configure a new RADIUS webhook for you. +Our [customer support team](https://support.smallstep.com/en/contact-us) can configure a new RADIUS webhook for you. ## RADIUS Webhook specification diff --git a/tutorials/wifi-setup-guide.mdx b/tutorials/wifi-setup-guide.mdx index b0b6b110..dff87fab 100644 --- a/tutorials/wifi-setup-guide.mdx +++ b/tutorials/wifi-setup-guide.mdx @@ -1,6 +1,6 @@ --- title: Configure 802.1x EAP-TLS WPA-Enterprise Wi-Fi on your Access Point -updated_at: November 06, 2025 +updated_at: January 20, 2026 html_title: Configure your Wi-Fi Access Point to use Enterprise EAP-TLS certificate-based authentication with Smallstep description: This tutorial describes how to set up Smallstep's certificate-based Wi-Fi on several popular Access Point models --- @@ -171,7 +171,7 @@ Your 802.1x EAP-TLS WPA-Enterprise Wi-Fi network is ready for use. ## Configure 802.1x EAP-TLS WPA-Enterprise Wi-Fi on Aruba -*Note: These instructions follow setup for Aruba mobility controllers wireless AP portals. See [Aruba reference WLAN configuration documentation](https://arubanetworking.hpe.com/techdocs/ArubaOS_8.12.0_Web_Help/Content/arubaos-solutions/virtual-ap/wlan-conf-prof.htm)* +*Note: These instructions follow setup for Aruba mobility controllers wireless AP portals. See [Aruba reference WLAN configuration documentation](https://arubanetworking.hpe.com/techdocs/VSG/docs/020-campus-deploy/esp-campus-deploy-110-configuring-wireless-access/)* First, create a new RADIUS profile: