From a2e701bdaafb47c52202af34690935abcacde044 Mon Sep 17 00:00:00 2001 From: Linda-Ikechukwu Date: Wed, 5 Jun 2024 14:15:12 +0100 Subject: [PATCH 1/4] resolving merge conflicts --- certificate-manager/core-concepts.mdx | 193 ++++--------------------- certificate-manager/webhook-events.mdx | 2 + platform/getting-started.mdx | 6 +- platform/how-it-works.mdx | 41 ++---- platform/use-cases.mdx | 5 +- 5 files changed, 51 insertions(+), 196 deletions(-) diff --git a/certificate-manager/core-concepts.mdx b/certificate-manager/core-concepts.mdx index 3505c1ae..f492ec90 100644 --- a/certificate-manager/core-concepts.mdx +++ b/certificate-manager/core-concepts.mdx @@ -6,165 +6,49 @@ description: Core Concepts of the Smallstep Platform. The Smallstep Platform is powered by a number of components that can be combined to deliver automated certificate management for a broad set of use cases and implementations. -# Certificates +The components include: -A **certificate** is a sort of credential. Concretely, a certificate is a data -structure that contains a name, public key, validity period (a.k.a., lifetime), -and additional metadata. Certificates are **signed** by a trusted **certificate -authority** (CA) and issued to **endpoints**. A **relying party** validates a -certificate and extracts the **subject name** to authenticate the identity of an -endpoint. +- **[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 -# Endpoints - -An **Endpoint** is an entity (person, device, workload) that is issued a -certificate. Certificate Manager attempts to group certificate renewals for an -Endpoint for alerting, audit, and billing purposes. - -Certificate Manager can be configured to alert you when an Endpoint’s last -certificate is approaching expiry and has not been renewed. - -The Certificate Manager dashboard provides an Endpoint detail view that makes it -easy for administrators to view the historical certificate lineage for an -Endpoint. This aggregated view simplifies operations, auditing, reporting, and -compliance inquiries. - -Certificate Manager billing is also metered on Endpoint-months. - -- Billing starts when a certificate is issued for a new Endpoint -- Billing ends when an Endpoint’s last certificate expires or is revoked - -Billing per-certificate would penalize deployments that use short-lived -certificates and automated renewal. Endpoint billing is designed to encourage -this best practice. - -Two Endpoint examples: - -1. A single device with **one 30-day certificate** would be billed at the same - rate as, -2. A single device with **60 one-day certificates** renewed every 12-hours. - -**Endpoint** grouping is automatic and intuitive for most use cases: - -- For provisioners with renewal enabled: - - Certificates issued using `step ca certificate` (or any other method that - uses the `/sign` API) create a new Endpoint - - Certificates issued using `step ca renew` (or any other method that uses the - `/renew` API) are associated with the existing Endpoint of the certificate - that’s being renewed -- For provisioners with renewal disabled, common with ACME and OIDC, - certificates with identical subjects (common name and SANs), ignoring order - and capitalization, belong to the same Endpoint - -For billing purposes, there is a limit of three active certificates per -Endpoint. Each active certificate above three is billed as an additional -Endpoint. To avoid being charged for multiple Endpoints you can revoke unused -certificates after they’ve been renewed. - -If you’d like to opt-in to certificate-based billing, inquire about high-volume -fixed pricing, or have any other questions about Endpoint-based billing for your -use case please [contact us](mailto:support@smallstep.com). # Authorities -Authorities are the foundation of the Smallstep Platform. They are trusted services that provide core certificate signing and management functions (issue, sign, renew, and revoke certificates), and can run at any level of the PKI trust chain. Authorities are -highly configurable, and multiple authorities can be used together to meet -complex requirements. - -There are different types of authorities supported: +Authorities, powered by `step-ca`, are the foundation of the Smallstep Platform and provide core certificate signing and management functions (issue, renew, and revoke certificates). +Authorities are used to issue and sign certificates and can run at any level of the PKI trust chain. -## Issuing Authorities - -An **issuing authority** is an online certificate authority that authenticates -and authorizes certificate requests and issues certificates. Issuing authorities -sign certificates themselves. To do so, they are provisioned with a special CA -certificate and private key. - -There are two types of issuing authority: - -1. **Hosted**: run by smallstep on your behalf as part of your Certificate - Manager account. -2. **Linked**: an instance of `step-ca` you run that connects to your - Certificate Manager account for reporting, alerting, revocation, and other - managed services. - -If an issuing authority's private key is compromised, it can be used to -maliciously issue certificates that will be trusted by the rest of your -infrastructure. To protect these keys, `step-ca` integrates with hardware and -software key managers, including PKCS#11 Hardware Security Modules (HSMs), -YubiKeys, and cloud key management systems (KMSs) from AWS, GCP, and Azure. For -hosted authorities, smallstep secures these keys for you in GCP's CloudKMS, with -options for software or FIPS 140-2 Level 3 hardware protection levels. - -## Root CA -At the bottom of the PKI trust chain is the root authority. Typically, a Root CA is only invoked to sign intermediate CA certificates. +- **Root CA** - At the bottom of the PKI trust chain is the root authority. +Typically, a Root CA is only invoked to sign intermediate CA certificates. This indirection allows for redundant topologies and facilitates migrations. It also means root CA private keys can be managed, stored, and accessed with more care. - For the most security-sensitive use cases root signing keys can even be kept offline in a physically secure environment. -A **root CA** is _directly_ trusted by relying parties. The root CA's -certificate must be deployed to VMs, devices, and containers, then software and -systems must be configured to trust it. - -## Intermediate CA -Automated certificate management requires an online CA with an API that's capable of authenticating certificate signing requests (CSRs) and issuing certificates. -An intermediate CA (also called a **subordinate CA**) is an issuing CA which recursively _chains up_ to the root CA. It is used to sign and issue certificates for devices, people, workloads, or whatever else you need to identify. It also allows you to keep your root signing keys offline, which improves security. - -For most scenarios, this is a nuance you won't have to worry about. By default, -Certificate Manager will create a non-issuing root CA and a separate issuing -authority for you automatically. For advanced scenarios, you can use your own -offline root CA, provision multiple issuing authorities from a single root, -configure multiple levels of intermediates, and revoke and re-issue intermediate -authority certificates as necessary. - -## Registration Authority -A registration authority is an online service that accepts and authenticates certificate requests. But, instead of issuing certificates itself, a registration authority passes authentic requests to an -issuing authority (an Intermediate CA or Root CA) to sign and catalog. Registration authorities support all Provisioner types and are an optional component. They deliver most of the benefits of a -linked issuing authority with less operational complexity since there's no -signing key to manage. -Registration Authorities are also useful for connecting remote sites to a central set of signing authorities. - -![ACME Registration Authority](/graphics/ia-cloud-ra-challenge-client.svg 'In this example, the Smallstep ACME RA runs within the local network or VPC and responds to ACME requests from internal infrastructure and workloads. The RA accepts ACME orders and authenticates requests by verifying an ACME challenge. Upon verification, a CSR is securely passed to the Issuing Authority to sign and catalog.') - -## Validation Authorities - -A validation authority distributes certificate revocation status. Validation -authorities implement two open standards to support active revocation: - -- **Certificate Revocation List (CRL)**: a signed, immutable ledger that lists - the serial number of all revoked certificates. CRLs are signed by trusted - infrastructure and served from cloud storage for high performance and - availability. -- **Online Certificate Status Protocol (OCSP)**: a standard API for requesting - the revocation status of a particular certificate. The Certificate Manager - OCSP responder is a shared-nothing service that uses CRLs as a data source. - +- **Intermediate CA** - Automated certificate management requires an online CA with an API that's capable of authenticating certificate signing requests (CSRs) and issuing certificates. +An intermediate CA is used to sign and issue certificates for devices, people, workloads, or whatever else you need to identify. +- **Registration Authority** - Not a certificate signer, a Registration Authority accepts and verifies certificate requests. +Upon verification, certificate signing requests are passed to an Intermediate CA or Root CA to sign and catalog. +Registration Authorities are useful for connecting remote sites to a central set of signing authorities.
Authorities are an open-source feature. The best way to learn about Authorities is to create one for yourself. - Follow the instructions on the step-ca getting started page and you will have your own Authority in no time at all.. + Follow the instructions on the step-ca` getting started page and you will have your own Authority in no time at all..
# Provisioners -Provisioners verify the legitimacy of certificate signing requests and attest to the identity of the requesting service or human. Provisioners are used to bootstrap new entities into the PKI, and make it easy to automate certificate management where -possible, and support semi-automated / self-serve workflows where required. - -Certificate lifetimes, access control policies, renewal, templates, and many -other options are configurable per-provisioner. Since an issuing authority can -have multiple provisioners, you implement complex authentication and -authorization policies and issue different kinds of certificates from one -issuing authority. - -Each Provisioner addresses a particular environment, enabling different use cases. - A few examples include: +Provisioners verify the legitimacy of certificate signing requests and attest to the identity of the requesting service or human. +Used to help bootstrap new entities into the PKI, +each Provisioner addresses a particular environment, enabling different use cases. +A few examples include: - **OIDC Provisioner** - Useful for getting certificates to people, the OAuth/OpenID Connect (OIDC) Provisioner uses identity tokens for authentication. -With this provisioner, you can use single sign-on with Google Workspace, Okta, Microsoft Entra ID, or any other OAuth OIDC provider +With this provisioner, you can use single sign-on with G Suite, Okta, Azure Active Directory, or any other OAuth OIDC provider to verify the user's identity before issuing a certificate. - **ACME Provisioner** - Useful for automating TLS certificates, the ACME provisioner provides CSR generation, domain ownership verification, certificate download, and installation. @@ -175,16 +59,10 @@ Cloud API Provisioners use the native cloud provider API and instance identity d With support for AWS, GCP, and Azure metadata APIs, the Cloud API provisioner accelerates secure cloud operations. - **JWK Provisioner** - Useful for a broad range of workflows, the JWK provisioner provides a flexible JSON Web Token-based authentication flow. Often paired with infrastructure automation solutions, the JWK Provisioner can deliver one-time tokens to a new workload to later be exchanged for an x.509 certificate. -- **The `X5C` and `SSHPOP` provisioners** - Useful for getting short-lived device certificates. These provisioners let you get a certificate - using an existing x509 or SSH certificate issued from another authority. This - can be used by devices to exchange long-lived _birth certificates_ issued at - manufacture time for short-lived _workload certificates_ and for other - _derived credential_ workflows where a certificate from a canonical CA is used - to automatically obtain certificates from one or more special-purpose CA(s).
- Provisioners are an open-source feature. Visit the step-ca documentation for a complete list of Provisioners and instructions on usage and capabilities of each. + Provisioners are an open-source feature. Visit the step-ca` documentation for a complete list of Provisioners and instructions on usage and capabilities of each.
@@ -202,38 +80,23 @@ In both cases, the name in the authentication credential used to request a certi
- Inventories is a feature available on the Smallstep platform. + Inventories is a feature availaible on the Smallstep platform.
# Templates -Templates give you granular control over certificate details and can be used to customize x.509 or SSH certificates for any use case. -By default, -Certificate Manager is tuned to issue short-lived certificates for use with TLS. -Templates let you customize every detail of a certificate, down to the -[OID](https://en.wikipedia.org/wiki/Object_identifier), to support any use case. -With Templates, you can add custom SANs or extensions to: +Templates are JSON documents that describe the most important fields in the final certificate or certificate request. +Used to customize x.509 or SSH certificates for any use case, +Templates allow you to add custom SANs or extensions: - Customize certificates for a broad range of applications and integrations. - Provides full control of all of certificate fields, even add custom extensions. - Automate custom certificate generation and skip the manual workflows. -Concretely, a template is a JSON representation of a certificate that's -materialized using Go's [`text/template`](https://golang.org/pkg/text/template/) -module and [sprig functions](http://masterminds.github.io/sprig/). They look -like this: - -![Certificate Templates](/graphics/templates-screenshot.svg 'Certificate Templates') - -Context from certificate requests and authentication credentials are made -available as template variables, so you can adjust certificate details based on -who's requesting the certificate. - -
- Templates are an open-source feature. See the step-ca documentation for a complete description of Templates and instructions on usage and capabilities. + Templates are an open-source feature. the step-ca` documentation for a complete description of Templates and instructions on usage and capabilities. Visit
@@ -247,7 +110,7 @@ Events can be generated and surfaced via standard mechanisms.
- Events are a feature of the commercial Smallstep platform. See the Webhook Events doc to learn more. + Events are a feature of the commercial Smallstep platform. See the Webhook Events doc to learn more.
diff --git a/certificate-manager/webhook-events.mdx b/certificate-manager/webhook-events.mdx index fb7efeb1..f340f26d 100644 --- a/certificate-manager/webhook-events.mdx +++ b/certificate-manager/webhook-events.mdx @@ -4,6 +4,8 @@ html_title: Smallstep Platform | Webhook Events for Observability description: Smallstep Platform Webhook Events provide observability around certificate lifecycle activities. --- + +# Webhook Events Webhook Events allow for real-time logging of SSH sessions, certificate creation, and certificate expirations events. diff --git a/platform/getting-started.mdx b/platform/getting-started.mdx index c79b0b54..251f44a5 100644 --- a/platform/getting-started.mdx +++ b/platform/getting-started.mdx @@ -1,11 +1,13 @@ --- title: Getting Started With The Smallstep Platform html_title: Getting Started With The Smallstep Platform -description: The Smallstep platform is used across security, IT, and DevOps teams to enable end-to-end network encryption, privileged access management, passwordless authentication, and much more. +description: The Smallstep platform is used across security, IT, and DevOps teams to enable end-to-end network encryption, priviledged access management, passwordless authentication, and much more. --- [Sign up](https://smallstep.com/app) for an account to get started! +{Walkthrough tutorials for different workloads should be linked here.} + ## Usage You can use the Smallstep platform as a SaaS offering, or you can host it on-premise via our Run Anywhere (Kubernetes) or VM Appliance options. @@ -16,6 +18,6 @@ Your client machines can use the Step CLI for utility tasks, like bootstrapping ## Smallstep API -[The Smallstep API](smallstep-api.mdx) gives you full programmatic access to the functionality of the Smallstep platform. You can register workloads or devices, create collections, and configure the Smallstep agent all through the API without needing to use the platform UI. +The Smallstep API gives you full programmatic access to the functionality of the Smallstep platform. You can register workloads or devices, create collections, and configure the Smallstep agent all through the API without needing to use the platform UI. We also have a Smallstep Terraform Provider, which sits on top of the API to provision and manage your Smallstep resources, and the Smallstep Ansible Collection makes it easy to deploy the agent to your infrastructure. diff --git a/platform/how-it-works.mdx b/platform/how-it-works.mdx index 78445d13..997f8022 100644 --- a/platform/how-it-works.mdx +++ b/platform/how-it-works.mdx @@ -1,12 +1,11 @@ --- -title: How It Works -html_title: How It Works -description: The Smallstep platform is used across security, IT, and DevOps teams to enable end-to-end network encryption, privileged access management, passwordless authentication, and much more. +title: Use Cases of The Smallstep Platform +html_title: Smallstep Use Cases +description: The Smallstep platform is used across security, IT, and DevOps teams to enable end-to-end network encryption, priviledged access management, passwordless authentication, and much more. --- -![Device and Workload Management Setup](/graphics/workload-management-setup.png "This image describes the process of bringing a workload under management on the Smallstep Platform. First, you register your device and install the Smallstep agent on it. Next you'll select the workloads on that device that you wish you to encrypt. Then you'll follow the resulting configuration instructions provided by Smallstep. Finally, the agent issues a certificate for the workload, and will automatically renew the certificate every 24 hours ") -With Smallstep, your PKI can become a unified foundation for encryption and authentication for all your devices, people and workloads: from web apps and databases to Kubernetes clusters to GitHub Actions, SSH, VPN and Wi-Fi. +With Smallstep, your PKI can become a unified foundation for encryption and authentication for all your devices, people and workloads: from web apps and databases to Kubernetes clusters to GitHub Actions, SSH, VPN and WiFi. We don’t do this by trying to become your identity provider, user or asset database, MDM provider, or network gateway. Instead, we leverage roots of trust that are already around you, integrate with your existing resources, and provide a platform for managing encryption everywhere in your network. @@ -14,21 +13,17 @@ We don’t do this by trying to become your identity provider, user or asset dat All devices registering with your Smallstep team are first added to your device trust zone (or device PKI). To register, devices can leverage existing roots of trust: a Trusted Platform Module (TPM) in Linux, an Instance Identity document or attestation token from any cloud provider, or an attestation certificate. -We rely on hardware roots of trust wherever possible, so that *only* your devices can register with Smallstep. The Smallstep [API](smallstep-api.mdx) and IaC integrations make it easy to sync your device inventory to Smallstep. The device trust zone is a privileged trust zone. It offers an authentication factor, and it becomes a foundation for creating other trust zones. +We rely on hardware roots of trust wherever possible, so that *only* your devices can register with Smallstep. The Smallstep [API](https://gateway.smallstep.com/) and [IaC integrations](https://github.com/smallstep/ansible-collection-agent/) make it easy to sync your device inventory to Smallstep. The device trust zone is a privileged trust zone. It offers an authentication factor, and it becomes a foundation for creating other trust zones. ## People and Workload Trust Zones -The people and workload trust zones are dedicated to infrastructure access. Smallstep can issue certificates to people and applications by leveraging a device certificate (from the device trust zone), a Single Sign-on (SSO) token, or another authentication method. Keep managing your own directory, and Smallstep will ensure all the right attributes end up on your account certificates for the applications you need to access. +Built on top of the device trust zone, the people and workloads trust zone is dedicated to infrastructure access. Smallstep can issue certificates to your people and applications by leveraging a device certificate from the device trust zone, a Single Sign-on (SSO) token, or another authentication method. Keep managing your own user directory, and Smallstep will ensure all the right attributes end up on your user certificates for the applications you need to access. -Smallstep monitors all the certificates it issues, seamlessly renewing them as needed and updating the affected services. +Smallstep can monitor and manage all the certificates it issues to your workloads, seamlessly renewing them as needed and updating the affected services. User certificates are short-lived and can be issued on-demand. -## Account certificates +## The Smallstep agent -Smallstep builds on a foundation of trust zones for devices, workloads, and people to issue client certificates for specific applications. Account certificates are short-lived, are issued on-demand, are instantly revocable, and can combine device and user identities. - -## The Smallstep Agent - -The Smallstep agent is a binary package that runs locally as a background service on devices with workloads to be managed. The agent is the backbone of the entire process and provides services such as: +The Smallstep agent is a Go binary package that is installed and runs locally as a background service on devices with workloads to be managed. The agent is the backbone of the entire process and provides services such as: - **Automated certificate renewal and management for devices and workloads**. The agent renews the certificate every 24 hours and will reload the service to activate the new certificate. - **Telemetry monitoring to aid troubleshooting**. The agent relays essential information about its host machine, including architecture, OS, and agent version, enabling visibility on the Smallstep UI. It also relays information about certificate permissions and configuration correctness, validating certificate validity and proper workload setup. Users can easily spot and address configuration issues, such as certificate storage errors, incorrect permissions, server key access problems, or agent interruptions due to device settings. @@ -47,7 +42,7 @@ This demo shows the process of registering a Linux device into the device trust allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen> -For walk through guides for other workloads, see [Getting Started](getting-started.mdx). +For walk through guides for other workloads, see our Getting Started page. ## Supported Device Types @@ -56,18 +51,11 @@ For walk through guides for other workloads, see [Getting Started](getting-start - Ubuntu (Current Stable and LTS releases) - Debian (Current Releases) - Fedora (Current Releases) -- Apple devices running iOS 16 or newer (with Jamf, Intune, or ACME device attestation) -- macOS Sonoma (with Intune, Jamf, or ACME device attestation) +- iPhones running iOS 16 or newer (ACME device attestation) +- macOS Sonoma (ACME device attestation) - macOS Ventura, with any MDM that supports SCEP - Windows devices, with any MDM that supports SCEP (eg. Intune, Workspace One) -## Supported Account Types - -- Enterprise WPA2/WPA3 Wi-Fi (eg. EAP-TLS, EAP-TTLS) -- VPN -- SSH -- GitHub - ## Supported Workload Types - Redis @@ -77,9 +65,8 @@ For walk through guides for other workloads, see [Getting Started](getting-start - Apache Tomcat - HAProxy - NGINX -- SSH hosts +- SSH (clients and servers) - GitHub Actions -- FreeRADIUS - Any custom app that uses TLS -Don’t see your workload type listed? [Ask us](https://support.smallstep.com/kb-tickets/new). +Don’t see your workload type listed? Ask us. diff --git a/platform/use-cases.mdx b/platform/use-cases.mdx index 4d5822a4..542ba83c 100644 --- a/platform/use-cases.mdx +++ b/platform/use-cases.mdx @@ -1,7 +1,7 @@ --- title: Use Cases of The Smallstep Platform html_title: Smallstep Use Cases -description: The Smallstep platform is used across security, IT, and DevOps teams to enable end-to-end network encryption, privileged access management, passwordless authentication, and much more. +description: The Smallstep platform is used across security, IT, and DevOps teams to enable end-to-end network encryption, priviledged access management, passwordless authentication, and much more. --- Typical use cases for Smallstep include, but not limited to the following: @@ -19,4 +19,5 @@ Also, from what we’ve heard, here’s how different teams employ Smallstep: - **IT teams** use Smallstep for device management and modern zero touch provisioning. Smallstep can manage certificates for 802.1x WiFi or VPN authentication, using the latest device attestation workflows and hardware-bound keys. - **DevOps teams** use Smallstep to manage SSH server access and SSO-for-SSH integration using certificates. -You can [schedule time](https://smallstep.com/request-demo/) with the Smallstep team to learn how the platform can help your project. +How are you hoping to use Smallstep? +(Should we include a form here?) From 863e8003e637d1cd3403e7da1dcf9293974d618a Mon Sep 17 00:00:00 2001 From: Linda-Ikechukwu Date: Wed, 5 Jun 2024 14:16:55 +0100 Subject: [PATCH 2/4] resolving merge conflicts --- certificate-manager/README.mdx | 19 +++++++++++++------ manifest.json | 29 ++++------------------------- 2 files changed, 17 insertions(+), 31 deletions(-) diff --git a/certificate-manager/README.mdx b/certificate-manager/README.mdx index 0f716cbc..5d2410e2 100644 --- a/certificate-manager/README.mdx +++ b/certificate-manager/README.mdx @@ -4,13 +4,20 @@ html_title: Certificate Manager Documentation from Smallstep description: Learn how to get started with Smallstep Certificate Manager. --- - Smallstep Certificate Manager is a commercial product built on `step-ca` that delivers a highly available hosted certificate authorities, expiry notifications and alerts, a management dashboard, Active Revocation, API, and other features. With Smallstep Certificate Manager, you can easily issue private TLS/SSL certificates to all your things. [Learn more here.](https://smallstep.com/certificate-manager) - -
- Are you looking for the open source step-ca documentation? Find it here. -
- +If you need to manage devices or workloads that are not supported yet, then you can use Certificate Manager to tinker a solution. + +The Certificate Manager exposes the fundamental building blocks for the supported use cases within the Smallstep platform. + +For context, Amazon Web Services (AWS) offers Elastic Beanstalk, streamlining application deployment on AWS. It manages infrastructure provisioning, including servers (EC2 instances), databases, load balancers, networks, and auto-scaling groups. You upload your app's code, and Elastic Beanstalk handles the rest. While it creates these resources, you maintain complete control and visibility over each resource, enabling developers to customize them as required. In contrast, if you were to manually navigate through AWS, you'd find yourself having to reason about these individual components, a potentially complex and time-consuming task. That's what Certificate Manager is to the Smallstep platform. + +When you register a device or workload for management of the Smallstep platform, behind the scene, authorities, provisioners, templates, policies and other stuff are created automatically for you. + +Certificate Manager is a big heap of technology that demands you to reason about the design, architecture, and configuration of your PKI yourself. We understand that PKI might not be your primary focus, so instead of diving into certificate intricacies, tell us your certificate-related goals, and we can provide guidance to expedite your journey. + + + + diff --git a/manifest.json b/manifest.json index bbf5bb07..a601be6a 100644 --- a/manifest.json +++ b/manifest.json @@ -34,31 +34,6 @@ { "title": "Getting Started", "path": "/platform/getting-started.mdx" - }, - { - "title": "Smallstep API", - "path": "/platform/smallstep-api.mdx" - } - ] - }, - { - "title": "How To Guides", - "routes": [ - { - "title": "Deploy EAP-TLS Wi-Fi with Jamf Pro + Smallstep", - "path": "/tutorials/apple-mdm-jamf-setup-guide.mdx" - }, - { - "title": "Deploy EAP-TLS Wi-Fi with Intune + Smallstep", - "path": "/tutorials/intune-mdm-setup-guide.mdx" - }, - { - "title": "Set up Wi-Fi Access Points for EAP-TLS", - "path": "/tutorials/wifi-setup-guide.mdx" - }, - { - "title": "Set up certificate-based VPN with Smallstep", - "path": "/tutorials/vpn-setup-guide.mdx" } ] }, @@ -119,6 +94,10 @@ "title": "Introduction", "path": "/certificate-manager/README.mdx" }, + { + "title": "Core Concepts", + "path": "/certificate-manager/core-concepts.mdx" + }, { "title": "Getting Started", "path": "/certificate-manager/getting-started.mdx" From 17d31baa00485f2630409362c155a072808908bc Mon Sep 17 00:00:00 2001 From: Linda-Ikechukwu Date: Wed, 5 Jun 2024 16:03:02 +0100 Subject: [PATCH 3/4] high level product docs revamp for device identity --- manifest.json | 38 ++++++---- platform/README.mdx | 131 ++++++++++++++++++++++++++++++++--- platform/getting-started.mdx | 23 ------ platform/how-it-works.mdx | 72 ------------------- platform/use-cases.mdx | 23 ------ 5 files changed, 147 insertions(+), 140 deletions(-) delete mode 100644 platform/getting-started.mdx delete mode 100644 platform/how-it-works.mdx delete mode 100644 platform/use-cases.mdx diff --git a/manifest.json b/manifest.json index a601be6a..b6401fbc 100644 --- a/manifest.json +++ b/manifest.json @@ -17,23 +17,41 @@ "title": "Platform" }, { - "title": "Platform", + "title": "Smallstep Overview", "routes": [ { - "title": "Overview", + "title": "About Smallstep", "path": "/platform/README.mdx" }, { - "title": "Use Cases", - "path": "/platform/use-cases.mdx" + "title": "Smallstep API", + "path": "/platform/smallstep-api.mdx" + } + ] + }, + { + "title": "Smallstep for WPA-Enterprise Wi-Fi", + "routes": [ + { + "title": "Set up Wi-Fi Access Points for EAP-TLS", + "path": "/tutorials/wifi-setup-guide.mdx" }, { - "title": "How It Works", - "path": "/platform/how-it-works.mdx" + "title": "Deploy EAP-TLS Wi-Fi with Jamf Pro", + "path": "/tutorials/apple-mdm-jamf-setup-guide.mdx" }, { - "title": "Getting Started", - "path": "/platform/getting-started.mdx" + "title": "Deploy EAP-TLS Wi-Fi with Intune", + "path": "/tutorials/intune-mdm-setup-guide.mdx" + } + ] + }, + { + "title": "Smallstep for Certificate-Based VPN", + "routes": [ + { + "title": "Set up certificate-based VPN with Smallstep", + "path": "/tutorials/vpn-setup-guide.mdx" } ] }, @@ -94,10 +112,6 @@ "title": "Introduction", "path": "/certificate-manager/README.mdx" }, - { - "title": "Core Concepts", - "path": "/certificate-manager/core-concepts.mdx" - }, { "title": "Getting Started", "path": "/certificate-manager/getting-started.mdx" diff --git a/platform/README.mdx b/platform/README.mdx index f3cc516b..79f3679c 100644 --- a/platform/README.mdx +++ b/platform/README.mdx @@ -1,16 +1,14 @@ --- -title: Overview of The Smallstep Platform -html_title: The Smallstep Platform -description: The Smallstep platform helps teams quickly and reliably connect devices, workloads, and people using end-to-end encryption and cryptographic identity, making it easy to deploy and monitor an internal Public Key Infrastructure (PKI) in the cloud. +title: What is Smallstep? +html_title: What is Smallstep? +description: Smallstep is a centralised comprehensive internal PKI toolchain, providing IT/Security/DevOps engineers with everything they need to automate the deployment, and management (renewal, revocation and monitoring) of certificates for a broad range of contexts, use cases and environments. --- -The Smallstep platform helps teams quickly and reliably connect devices, workloads, and people using end-to-end encryption and cryptographic identity, making it easy to deploy and monitor an internal Public Key Infrastructure (PKI) in the cloud. +Certificates are a fundamental part of any non-trivial architecture, as they are the strongest possible way to encrypt communications, authenticate users and devices, protect data integrity, and ensure compliance with security standards. -Built by PKI experts, our platform employs modern, standard protocols and PKI best practices. We believe network encryption and production identity should be ubiquitous, automated, monitored, and unobtrusive. +Smallstep is a centralised comprehensive internal PKI toolchain, providing IT/Security/DevOps engineers with everything they need to automate the deployment, and management (renewal, revocation and monitoring) of certificates for a broad range of contexts, use cases and environments. -Whether you’re securing an NGINX web app, an IoT fleet, or a mobile MDM deployment, you can use Smallstep to safeguard your infrastructure. Our goal is to help you encrypt all the communication within your organization, creating a *cryptographic perimeter* around your resources, using short-lived certificates. - -Under the hood, Smallstep deploys, manages, and monitors TLS, SSH, and X.509 certificates for your users and infrastructure. We support deep integrations for securing network connections to servers, databases, VPNs, Linux VMs, managed devices, web applications, and much more. +We offer robust integration solutions for securing network connections to various resources like servers, databases, internal web applications, Kubernetes clusters, GitHub Actions, VPNs, VMs, Wi-Fi, managed devices, and more. With Smallstep, your PKI can serve as a unified foundation for certificate-driven security for all your devices, people, and workloads.
@@ -24,6 +22,119 @@ Under the hood, Smallstep deploys, manages, and monitors TLS, SSH, and X.509 cer -## Learn More +# What can you use Smallstep for? +## Enterprise IT + +Smallstep can be used to establish high-assurance device identities and restrict access by devices, ensuring that sensitive resources are only accessible from trusted company-managed devices. When combined with user identities, device identities bound to hardware can offer the strongest possible security guarantees. + +Device Identity helps your organisation: + +- [Protect against credential theft based attacks](https://smallstep.com/blog/road-to-phishing-resistant-authentication/). +- Meet regulatory requirements and industry standards such as GDPR, HIPAA, and PCI DSS. +- Enforce non-repudiation, so you can seamlessly verify and attribute every action. + +After devices have been securely enrolled and identified, Smallstep takes care of automatically deploying client certificates to company devices for accessing each of your most important resources, such as: + +- Wi-Fi (for 802.1x EAP-TLS WPA-Enterprise) +- VPN Servers +- Zero Trust Network Access (ZTNA) +- HTTP/3 Proxies +- Internal Websites +- Cloud-based collaboration suites (Google Workspace, Microsoft Office365, Zoho Workplace, Atlassian Suite, e.t.c) +- Public SaaS applications (Stripe, Quickbooks, Slack, etc.) + +### For Organisations With MDM + +Smallstep integrates with your MDM to deploy client certificates to company-managed devices to enable certificate-based network authentication for Wi-Fi (802.1x EAP-TLS WPA-Enterprise), VPN, ZTNA, etc. + +We offer integrations for any MDMs for Apple and Windows devices that support Dynamic SCEP or ACME certificate enrollment protocols. + +![Jamf MDM Marketecture.png](/graphics/Jamf_MDM_Marketecture.png) + +Supported MDMs include: Jamf, Intune, Workspace ONE, Mosyle, Ivanti, Jumpcloud, and lots more. + +Smallstep can also be used as a drop-in replacement for Active Directory Certificate Services (ADCS), allowing you to transition from ADCS while still serving legacy workloads. We provide backwards-compatible support for SCEP and NDES, and also let you bring your existing Root CA with you, so you can get up and running in minutes. + +![Intune MDM Marketecture.png](/graphics/Intune_flow_diagram.png) + +See: + +- [Why Your Organisation Should Be Migrating From Microsoft AD CS](https://smallstep.com/blog/migrate-from-microsoft-adcs/) +- [How to Bring Your Own Root from AD CS to Smallstep](https://smallstep.com/blog/byor-adcs-to-smallstep/) + + +
+ 💡 What about MDM’s that do not support Dynamic SCEP? +

+ There are two main approaches to using SCEP as a certificate enrolment protocol: static and dynamic. +

+

+ In static SCEP, a single challenge password is in every SCEP payload for every device. This practice is insecure and not recommended. Furthermore, it only shows a single user in reporting. We do not support this because we believe it's crucial to provide the most secure options for your infrastructure. +

+

+ In contrast, for Dynamic SCEP, webhooks are used to generate new challenges and unique passwords for each device, and you would be able to see reporting for all devices. +

+

In such a case where your MDM does not support Dynamic SCEP, your next best bet to deploy Smallstep is to use the Smallstep Agent. See details below +

+
+ + +### For Organisations Without MDM or with Linux Devices + +The Smallstep Agent is the recommended way to get identify devices and get client certificates to devices for Enterprise Wi-Fi, VPN, HTTP/3 proxies, or web applications in the following scenarios: + +- SMEs with 20 - 100 devices without an MDM +- Linux devices +- Managed devices under an MDM that does not support Dynamic SCEP + +The Smallstep Agent is a lightweight program that runs in the background on devices and manages end-to-end certificate lifecycle for various resources (workloads). The agent leverages Trusted Platform Modules (TPMs) for trust bootstrapping. It works with all TPM 2.0 devices—virtual TPMs, firmware TPMs, or physical TPMs—and on some TEEs and Secure Enclaves (eg. Apple Managed Device Attestation). + +To get started, [sign up now](https://smallstep.com/signup/). + +# How Can You Use Smallstep? + +Depending on what’s best for your infrastructure and current reality, Smallstep offers different deployment options to meets your needs: + +## Smallstep SaaS cloud offering + +The Smallstep Saas cloud offering is our default recommended offering, unless you have security requirements that prohibit you from using a cloud CA. We also provide an ****API, Terraform Provider, and Ansible Collection for automation and IaC integration. + +## Smallstep Run Anywhere + +The Smallstep Run Anywhere is a copy of our hosted SaaS software that can be deployed in any customer-managed data center or cloud hosting provider. This solution allows customers to manage their own infrastructure and meet compliance while still being able to use Smallstep’s tech stack to issue and manage certificates. + +At its core, `run anywhere` requires a Kubernetes cluster for compute resources. It plugs into a PostgreSQL database, Redis instance, load balancing solution, and either a KMS or HSM. If you would like to deploy `run anywhere` into a GCP, AWS, or Azure environment, we have Terraform modules available for use or reference. Alternatively, users may work with Smallstep to configure their own solutions for other cloud hosting providers and data centers as desired. + +Talk to Smallstep’s Customer Engineering Team at [support.smallstep.com](http://support.smallstep.com) to design a deployment custom-tailored to all of your security needs. + +## Smallstep Open-Source Toolchain + +Our open source toolchain the most popular open-source certificate management toolchain, and was designed for DevOps and homelab or POC use cases—it’s not a device identity platform, and doesn’t solve the problems listed above. + +Our open-source toolchain for certificate and PKI management features 3 components: + +- [step CLI](https://github.com/smallstep/cli): A user-friendly command-line interface to build, operate, and automate PKI systems. +- [step-ca](https://github.com/smallstep/certificates): A powerful online CA for secure, automated certificate management. +- [step-issuer](https://github.com/smallstep/step-issuer) and [autocert](https://github.com/smallstep/autocert): Kubernetes-native solutions for seamless certificate issuance and management in containerized environments. + +Get tinkering and [***Join our open-source Discord community*** ](https://u.step.sm/discord). + +## Smallstep Enterprise CA + +Smallstep Enterprise CA is a drop-in upgrade for open-source certificate management toolchain, offering advanced features, support, and compliance options. It extends our open source with Device Identity features and integrations. + +The Enterprise CA is ideal for organisations who want full On-Prem Control or need to make the transition from open-source to commercial to access Device Identity capabilities and advanced compliance options. + +With Enterprise CA, just like our open source toolchain, you still maintain full control over the CA and root signing keys while benefiting from our cloud-based integrations and management interface. + +Key Features are: + +- Fast and lightweight setup on Linux, Kubernetes, and Docker +- Smallstep Device Identity, including MDM & posture integrations and active revocation (CRL & OCSP) +- High-volume certificate issuance with HSM integration +- FIPS and software supply-chain compliance, including SBOM & code-signing +- Broad support for enrollment protocols, such as SCEP, REST API, SSO (OAuth OIDC), SPIFFE, cloud identities, and Kubernetes integration +- Connectors for existing PKI backends (AD CS, GCP CAS, AWS PCM) +- High availability, automation, and CLM integration with Sectigo and Digicert -You can [schedule time](https://smallstep.com/request-demo/) with the Smallstep team to learn how the platform can help your project. +We offer standard SLAs with 24-hour response for non-critical issues and 4-hour turnaround for critical incidents. For organizations requiring tailored assistance, enhanced support options are available, ensuring your infrastructure remains secure and operational. [Reach out](https://go.smallstep.com/request-demo) if you're looking to explore this option. diff --git a/platform/getting-started.mdx b/platform/getting-started.mdx deleted file mode 100644 index 251f44a5..00000000 --- a/platform/getting-started.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Getting Started With The Smallstep Platform -html_title: Getting Started With The Smallstep Platform -description: The Smallstep platform is used across security, IT, and DevOps teams to enable end-to-end network encryption, priviledged access management, passwordless authentication, and much more. ---- - -[Sign up](https://smallstep.com/app) for an account to get started! - -{Walkthrough tutorials for different workloads should be linked here.} - -## Usage - -You can use the Smallstep platform as a SaaS offering, or you can host it on-premise via our Run Anywhere (Kubernetes) or VM Appliance options. - -Your Linux devices will run the Smallstep agent, which manages certificates for the device and its workloads. - -Your client machines can use the Step CLI for utility tasks, like bootstrapping trust with your PKI, configuring SSH for Smallstep, etc. - -## Smallstep API - -The Smallstep API gives you full programmatic access to the functionality of the Smallstep platform. You can register workloads or devices, create collections, and configure the Smallstep agent all through the API without needing to use the platform UI. - -We also have a Smallstep Terraform Provider, which sits on top of the API to provision and manage your Smallstep resources, and the Smallstep Ansible Collection makes it easy to deploy the agent to your infrastructure. diff --git a/platform/how-it-works.mdx b/platform/how-it-works.mdx deleted file mode 100644 index 997f8022..00000000 --- a/platform/how-it-works.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Use Cases of The Smallstep Platform -html_title: Smallstep Use Cases -description: The Smallstep platform is used across security, IT, and DevOps teams to enable end-to-end network encryption, priviledged access management, passwordless authentication, and much more. ---- - - -With Smallstep, your PKI can become a unified foundation for encryption and authentication for all your devices, people and workloads: from web apps and databases to Kubernetes clusters to GitHub Actions, SSH, VPN and WiFi. - -We don’t do this by trying to become your identity provider, user or asset database, MDM provider, or network gateway. Instead, we leverage roots of trust that are already around you, integrate with your existing resources, and provide a platform for managing encryption everywhere in your network. - -## Device Trust Zone - -All devices registering with your Smallstep team are first added to your device trust zone (or device PKI). To register, devices can leverage existing roots of trust: a Trusted Platform Module (TPM) in Linux, an Instance Identity document or attestation token from any cloud provider, or an attestation certificate. - -We rely on hardware roots of trust wherever possible, so that *only* your devices can register with Smallstep. The Smallstep [API](https://gateway.smallstep.com/) and [IaC integrations](https://github.com/smallstep/ansible-collection-agent/) make it easy to sync your device inventory to Smallstep. The device trust zone is a privileged trust zone. It offers an authentication factor, and it becomes a foundation for creating other trust zones. - -## People and Workload Trust Zones - -Built on top of the device trust zone, the people and workloads trust zone is dedicated to infrastructure access. Smallstep can issue certificates to your people and applications by leveraging a device certificate from the device trust zone, a Single Sign-on (SSO) token, or another authentication method. Keep managing your own user directory, and Smallstep will ensure all the right attributes end up on your user certificates for the applications you need to access. - -Smallstep can monitor and manage all the certificates it issues to your workloads, seamlessly renewing them as needed and updating the affected services. User certificates are short-lived and can be issued on-demand. - -## The Smallstep agent - -The Smallstep agent is a Go binary package that is installed and runs locally as a background service on devices with workloads to be managed. The agent is the backbone of the entire process and provides services such as: - -- **Automated certificate renewal and management for devices and workloads**. The agent renews the certificate every 24 hours and will reload the service to activate the new certificate. -- **Telemetry monitoring to aid troubleshooting**. The agent relays essential information about its host machine, including architecture, OS, and agent version, enabling visibility on the Smallstep UI. It also relays information about certificate permissions and configuration correctness, validating certificate validity and proper workload setup. Users can easily spot and address configuration issues, such as certificate storage errors, incorrect permissions, server key access problems, or agent interruptions due to device settings. -- **Remote configuration**: The agent actively monitors configuration changes made either through the UI or API and promptly synchronizes them with the managed devices and workloads. For instance, when a new workload is added to a device, the agent on that device immediately fetches the updated configuration and initiates certificate issuance for the new workload. Similarly, if any changes are made to the workload, such as altering the key type, the agent will reissue certificates to align with the modified settings. - -## Example: Redis on Linux - -This demo shows the process of registering a Linux device into the device trust zone, and deploying TLS server authentication for a Redis server. - - - -For walk through guides for other workloads, see our Getting Started page. - -## Supported Device Types - -- Linux devices or cloud VMs running any of the following: - - Enterprise Linux (RHEL, CentOS Stream, Rocky Linux, Alma Linux, etc) - - Ubuntu (Current Stable and LTS releases) - - Debian (Current Releases) - - Fedora (Current Releases) -- iPhones running iOS 16 or newer (ACME device attestation) -- macOS Sonoma (ACME device attestation) -- macOS Ventura, with any MDM that supports SCEP -- Windows devices, with any MDM that supports SCEP (eg. Intune, Workspace One) - -## Supported Workload Types - -- Redis -- PostgreSQL -- MySQL -- Apache httpd -- Apache Tomcat -- HAProxy -- NGINX -- SSH (clients and servers) -- GitHub Actions -- Any custom app that uses TLS - -Don’t see your workload type listed? Ask us. diff --git a/platform/use-cases.mdx b/platform/use-cases.mdx deleted file mode 100644 index 542ba83c..00000000 --- a/platform/use-cases.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Use Cases of The Smallstep Platform -html_title: Smallstep Use Cases -description: The Smallstep platform is used across security, IT, and DevOps teams to enable end-to-end network encryption, priviledged access management, passwordless authentication, and much more. ---- - -Typical use cases for Smallstep include, but not limited to the following: - -- **End to end network encryption:** Authenticate and encrypt network traffic within your infrastructure. Provision and manage TLS certs for web applications (NGINX, Caddy, Apache httpd, etc.), databases (MySQL, Postgres, MongoDB, etc), browsers, Kubernetes, IoT devices, and more. Issue SSH host and short-lived user certificates. -- **Privileged Access Management:** Provision cryptographic identities and fine-grained trust policies for the people, devices, processes, or technology requiring access to workloads for easier detection and monitoring. - - Get hardware-bound device certificates for Linux, Windows, and mobile devices. - - Streamline and simplify SSH access with single sign-on SSH -- **Passwordless or Secretless authentication:** Shared and long lived authentication credentials (passwords, keys, e.t.c) are major enablers of credential theft and data breaches. Get rid of shared or long lived credentials within your infrastructure, and replace them with ephemeral certificates. -- **IoT/OT:** Bootstrap IoT devices with CA trust. Issue device identity certificates and workload certificates to IoT or OT devices, so that all communications are encrypted and authenticated. - -Also, from what we’ve heard, here’s how different teams employ Smallstep: - -- **Security teams** use Smallstep to secure connections to web applications, databases, and Linux servers. We integrate with modern infrastructure-as-code (IaC) tools like Ansible and Terraform. -- **IT teams** use Smallstep for device management and modern zero touch provisioning. Smallstep can manage certificates for 802.1x WiFi or VPN authentication, using the latest device attestation workflows and hardware-bound keys. -- **DevOps teams** use Smallstep to manage SSH server access and SSO-for-SSH integration using certificates. - -How are you hoping to use Smallstep? -(Should we include a form here?) From 3204efeba80087d3ec8ec637d25b30f713a0a975 Mon Sep 17 00:00:00 2001 From: Linda-Ikechukwu Date: Wed, 5 Jun 2024 17:17:28 +0100 Subject: [PATCH 4/4] minor changes to certificate manager core concepts --- certificate-manager/core-concepts.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/certificate-manager/core-concepts.mdx b/certificate-manager/core-concepts.mdx index f492ec90..921825cc 100644 --- a/certificate-manager/core-concepts.mdx +++ b/certificate-manager/core-concepts.mdx @@ -34,7 +34,7 @@ Registration Authorities are useful for connecting remote sites to a central set
Authorities are an open-source feature. The best way to learn about Authorities is to create one for yourself. - Follow the instructions on the step-ca` getting started page and you will have your own Authority in no time at all.. + Follow the instructions on the `step-ca` getting started page and you will have your own Authority in no time at all..
@@ -62,7 +62,7 @@ Often paired with infrastructure automation solutions, the JWK Provisioner can d
- Provisioners are an open-source feature. Visit the step-ca` documentation for a complete list of Provisioners and instructions on usage and capabilities of each. + Provisioners are an open-source feature. Visit the `step-ca` documentation for a complete list of Provisioners and instructions on usage and capabilities of each.
@@ -96,8 +96,7 @@ Templates allow you to add custom SANs or extensions:
- Templates are an open-source feature. the step-ca` documentation for a complete description of Templates and instructions on usage and capabilities. - Visit + Templates are an open-source feature. the `step-ca` documentation for a complete description of Templates and instructions on usage and capabilities.