Merge branch 'main' into carl/enrollment-guide

Author: tashian

.github/PULL_REQUEST_TEMPLATE

@@ -1,20 +1,7 @@
-<!---
-Please provide answers in the spaces below each prompt, where applicable.
-Not every PR requires responses for each prompt.
-Use your discretion.
--->
-#### Name of feature:
+#### Describe your changes:
 
-#### Pain or issue this feature alleviates:
 
-#### Why is this important to the project (if not answered above):
+#### Related links/other PRs/issues:
 
-#### Is there documentation on how to use this feature? If so, where?
 
-#### In what environments or workflows is this feature supported?
-
-#### In what environments or workflows is this feature explicitly NOT supported (if any)?
-
-#### Supporting links/other PRs/issues:
-
-💔Thank you!
+Thank you!

manifest.json

@@ -187,30 +187,35 @@ curl -sL https://packages.smallstep.com/scripts/smallstep-agent-install.sh | sud
     ```
     
 
-## Configure the agent
+## Register the endpoint
+
+### Auto-registration
 
 To configure the agent and register your Linux device with your Smallstep team, run:
 
 ```jsx
 sudo step-agent-plugin register [team name]
 ```
 
-Alternatively, you can configure the agent manually.
-Simply update `/etc/step-agent/agent.yaml` config file, with your Smallstep team name and Smallstep Agent CA fingerprint.
+### Manual registration
 
-```jsx
-team: "myteamname"
-fingerprint: "40523785c1d1d11EXAMPLE017b660d52a5fa5f2cb94cf0e1a9e9209dbea0826"
-```
+Alternatively, you can configure the agent manually:
+1. First, [register and approve your devices via API](./enrollment-guide.mdx#add-devices-via-api).
+2. On your endpoints, update the `/etc/step-agent/agent.yaml` config file with your Smallstep team name and Smallstep Agent CA fingerprint.
+
+   ```jsx
+   team: "myteamname"
+   fingerprint: "40523785c1d1d11EXAMPLE017b660d52a5fa5f2cb94cf0e1a9e9209dbea0826"
+   ```
 
-- Your `team` ID (team slug). This is the value after `/app/` in your Smallstep dashboard URL.
-- Your agent CA `fingerprint`. Find this value in your dashboard:
-    - In the Smallstep dashboard, select Authorities
-    - Select the Smallstep Agents authority
-    - Use the sha256 Root fingerprint displayed on this page
+   - Your `team` ID (team slug). This is the value after `/app/` in your Smallstep dashboard URL.
+   - Your agent CA `fingerprint`. Find this value in your dashboard:
+       - In the Smallstep dashboard, select Authorities
+       - Select the Smallstep Agents authority
+       - Use the sha256 Root fingerprint displayed on this page
 
 
-## Start the Smallstep agent
+## Start the agent
 
 Finally, enable and start the agent:
 

platform/smallstep-agent.mdx

@@ -6,9 +6,11 @@ description: The Smallstep platform is used across security, IT, and DevOps team
 
 With the Smallstep API, you can:
 
-- Register VMs with Smallstep as you spin them up, for instant trust bootstrapping
-- Integrate certificate lifecycle management into your Terraform and Ansible definitions
-- Programmatically manage CAs, SSH grants and tags, and more!
+- Register new devices in your Smallstep inventory
+- Manage your high-level protected resources, such as Wi-Fi or VPN configurations
+- Manage low-level resources like X.509 CAs, Attestation authorities, and provisioners
+- Manage hosts, host grants, and tags for [Smallstep SSH](../ssh/README.mdx)
+- And more!
 
 The Smallstep API is [OpenAPI conformant](https://www.openapis.org/), with JSON requests and responses.
 
@@ -17,97 +19,53 @@ The Smallstep API is [OpenAPI conformant](https://www.openapis.org/), with JSON
 👉 [Smallstep API Specification and Playground](https://gateway.smallstep.com)
 
 You can get an API token in two ways:
-- In your [Smallstep settings](https://smallstep.com/app?next=/settings). Under **API Tokens**, choose **+ Add Token.**
-- On the command line, using the [`step` CLI](https://smallstep.com/docs/step-cli/). The [`step api token create`](https://smallstep.com/docs/step-cli/reference/api/token/create/index.html) command accepts a client certificate and private key to authenticate with Smallstep and issue a temporary API token. To use this option, you must first configure a trusted root CA in your [Smallstep settings](https://smallstep.com/app?next=/settings). The trusted root can be a Smallstep CA or an external CA. Only one trusted root CA may be configured.
+- **Long-term token**: In your [Smallstep settings](https://smallstep.com/app?next=/settings). Under **API Tokens**, choose **+ Add Token.** This token has a 10 year validity period and will only be displayed once. Please store it in a safe place!
+- **Short-term token**: On the command line, using the [`step` CLI](../step-cli/README.mdx). The [`step api token create`](../step-cli/reference/api/token/create/README.mdx) command accepts a client certificate and private key to authenticate with Smallstep and issue a temporary API token with a 1 hour validity period.
+  To use this option, you must configure a trusted root CA in your [Smallstep settings](https://smallstep.com/app?next=/settings). The trusted root can be a Smallstep CA or an external CA. Only one trusted root CA may be configured.
 
 ### API Clients
 
-- [Smallstep Terraform Provider](https://github.com/smallstep/terraform-provider-smallstep) ([Documentation](https://registry.terraform.io/providers/smallstep/smallstep/latest/docs))
 - [Smallstep API Python Client](https://github.com/smallstep/smallstep-python)
+- [Smallstep Terraform Provider](https://github.com/smallstep/terraform-provider-smallstep) ([Documentation](https://registry.terraform.io/providers/smallstep/smallstep/latest/docs))
+
+### Example: Add devices via the API
+
+You can import devices from any source into Smallstep using our API.
 
-### Getting Started
+Devices added via API are automatically approved.
+but they will not be marked as high-assurance
+until Smallstep receives an attestation from the device.
 
-You’ll need an API token to get started. You can create one by [signing into the Smallstep dashboard](https://smallstep.com/app/). In the bottom-left **⋮** menu, go to **Settings**. Under **API Tokens**, choose **+ Add Token.**
+For each device, use the [Save Collection Instance](https://gateway.smallstep.com/v2023-11-01/operations/PutCollectionInstance) endpoint to create a device.
+- For the `collectionSlug`, use `default`
+- For Apple devices, the `instanceID` must be the device's serial number.
+- For TPM 2.0 devices, the `instanceID` must be the TPM Endorsement Key URI, in the format `urn:ek:sha256:ul3sYf6uQ6jVEXAMPLEXoAuHI10U8gTvEJ6bMj95LXI=`. (You can retrieve the EK URI by running `step agent tpm --fingerprint` on the device.)
 
-Your API token has a 10 year validity period and will only be displayed once. Please store it in a safe place!
+For the body of the request,
+create a user using the following value 
+(replacing `[email protected]` with the device owner's email address):
 
-Once you have a token, try your first API call:
+```
+{
+  "data": {
+    "name": "Carl's MacBook Pro",
+    "smallstep:identity": "[email protected]"
+  }
+}
+```
+
+Once added,
+the devices will be automatically approved.
+
+You can see the device using the [ListCollectionInstances](https://gateway.smallstep.com/v2023-11-01/operations/ListCollectionInstances) endpoint:
 
 ```bash
 set +o history
 echo "Authorization: Bearer [your token]" > api_headers
 set -o history
-curl -sH @api_headers https://gateway.smallstep.com/api/users | jq
+curl -sH @api_headers https://gateway.smallstep.com/api/collections/default/items | jq
 ```
 
-Output:
-
-```bash
-[
-  {
-    "active": true,
-    "displayName": "Alice T",
-    "emails": [
-      {
-        "email": "[email protected]",
-        "primary": true
-      }
-    ],
-    "familyName": "T",
-    "givenName": "Alice",
-    "groups": [
-      {
-        "id": "a1028765-3d67-44b0-b51b-f7d76727f181",
-        "name": "admin"
-      },
-      {
-        "id": "eb4b75f0-a341-4dac-a52a-12d90d91b97d",
-        "name": "super-admin"
-      }
-    ],
-    "id": "4510f372-f4ba-4dc7-b6c2-ad22fdaaadb1",
-    "posixUsers": []
-  }
-]
-```
+Or, in your Smallstep dashboard,
+you'll see the device listed under Recent Devices.
 
-### Configure Devices and Workloads via the API
-
-Here’s the most common workflow for using the Smallstepi API, either directly or via the Terraform or Ansible integrations:
-
-#### 1. [Create a device collection](https://gateway.smallstep.com/operations/PutDeviceCollection).
-    
-Set the device type according to your deployment. Note that each device type is going to have its own `deviceTypeConfiguration` as well. For example, an Azure VM device will require you to set your Azure tenant ID, for access control.
-    
-You’ll register your individual devices in step 3.
-    
-#### 2. [Add workloads](https://gateway.smallstep.com/operations/PutWorkload).
-    
-This is where you set up your workload configuration. You can specify things like certificate SANs and duration, certificate and key file ownership and permissions, reload options for the workload, and so on.
-
-A single workload can be associated with multiple devices.
-
-Have three HAProxy hosts in front of a fleet of `internal.example.com` web servers? That’s one workload.
-
-Have a PostgreSQL server with several hot standby servers? That’s one workload.
-
-Have an etcd cluster comprised of three hosts? That’s one workload.
-
-On this endpoint, you can use the `deviceMetadataKeySANs` property to dynamically map certificate SANs for each device that’s running a workload. Or, statically assign SANs for every certificate in the workload, using `staticSANs`.
-    
-#### 3. [Add devices to collection](https://gateway.smallstep.com/operations/PutCollectionInstance).
-     
-Each device’s `instanceID` should be set according to the device type:
- 
-- For AWS EC2 instances, use the EC2 instance ID (eg. [`i-0d460b88a96dfdd08`](https://us-east-2.console.aws.amazon.com/ec2/home?region=us-east-2#InstanceDetails:instanceId=i-0d460b88a96dfdd08))
-- For Azure VMs, use the managed identity principal object ID
-- For Compute Engine VMs, use the instance ID (eg. `16979701088048819`)
- 
-Use the `data` field to store any relevant instance metadata, such as:
- 
-- an instance’s region, name, or role(s)
-- DNS names (these can be mapped to a SANs using `deviceMetadataKeySANs`, above)
-
-#### 4. Install the Smallstep app on each device.
-    
-See [Smallstep App](./smallstep-app.mdx) for details.

platform/smallstep-api.mdx

@@ -31,7 +31,7 @@ Teams use `step-ca` to:
   <div>
     To get up and running quickly, or as an alternative to running your own
     <Code>step-ca</Code> server, consider creating a
-    <a href="https://smallstep.com/signup?product=cm">free hosted smallstep Certificate Manager authority</a>.
+    <a href="https://smallstep.com/signup?product=cm">hosted Smallstep authority</a>.
   </div>
 </Alert>
 

step-ca/README.mdx

@@ -193,7 +193,7 @@ $ step ca certificate localhost localhost.crt localhost.key --not-after=5m
 $ step ca certificate localhost localhost.crt localhost.key --not-before=5m --not-after=240h
 ```
 
-Note that default maximum certificate duration is 24 hours. To adjust the global default, minimum, and maximum certificate durations for your CA, add a `claims` section to the `$(step path)/config/ca.json` configuration file, under `"authority"`, with the following keys:
+Note that default maximum certificate duration is 24 hours. To adjust the global default, minimum, and maximum certificate durations for your CA, add a `claims` section to the `$(step path)/config/ca.json` configuration file, nested under `"authority"`, with the following keys:
 
 ```json
 "claims": {

step-ca/basic-certificate-authority-operations.mdx

@@ -337,7 +337,7 @@ Here are some notes on granting a custom IAM role that provides step-ca with acc
 
 ## Azure Key Vault
 
-[Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault) is Microsoft's managed key management service.
+[Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview) is Microsoft's managed key management service.
 
 ### Authentication
 

step-ca/cryptographic-protection.mdx

@@ -37,7 +37,7 @@ Here are some of the most popular options:
   <AlertTitle>Don&apos;t want to run your own CA?</AlertTitle>
   <div>
     To get up and running quickly, consider creating a{' '}
-    <a href="https://smallstep.com/signup?product=cm">free hosted smallstep Certificate Manager authority</a>.
+    <a href="https://smallstep.com/signup?product=cm">hosted Smallstep authority</a>.
   </div>
 </Alert>
 

step-ca/getting-started.mdx

@@ -324,7 +324,7 @@ a Certificate Signing Request (CSR) is sent to the CA
 along with a short-lived JSON Web Token (JWT) which authenticates the request.
 
 The JWK provisioner can be useful for custom integrations.
-JWTs are easy to [generate programmatically](https://jwt.io/#libraries-io),
+JWTs are easy to [generate programmatically](https://jwt.io/libraries),
 without using `step`.
 We have written a few [example clients](https://github.com/smallstep/clients/tree/main) for demonstration purposes.
 
@@ -1285,7 +1285,7 @@ Here's an example of a SCEP provisioner in `$(step path)/config/ca.json`:
 ```json
 {
     "type": "SCEP",
-    "name": "scepca",
+    "name": "my_scep_provisioner",
     "forceCN": true,
     "challenge": "secret1234",
     "minimumPublicKeyLength": 2048,
@@ -1323,7 +1323,7 @@ Enable this by filling in the `"insecureAddress"` property to your top-level CA
 ```
 
 Finally, restart `step-ca`.
-Your SCEP provisioner is now available at the endpoint `http://ca.example.com:8080/scep/scepca`.
+Your SCEP provisioner is now available at the endpoint `http://ca.example.com:8080/scep/my_scep_provisioner`.
 
 <Alert severity="info">
   <div>

step-ca/provisioners.mdx

@@ -559,27 +559,45 @@ Here are the `config` options for `vaultcas` authorities:
 
 - **pkiRoleEd25519**: the pki role used to issue Ed25519 certificates, defaults to *pkiRoleDefault*
 
-- **authType**: required. the authentication method used to login to the vault, one of `approle` or `kubernetes`
+- **authType**: required. the authentication method used to login to the vault, one of `approle`, `kubernetes` or `aws`
 
 - **authMountPath**: the vault mount path for the auth method you want to use, if not set the default mount path for that auth type is used (usually the same name as the auth method)
 
 - **namespace**: optional. if using Vault Enterprise, the [namespace](https://developer.hashicorp.com/vault/docs/enterprise/namespaces) to which requests should be scoped. Note: this value will apply to both the `pkiMountPath` and the `authMountPath`, effectively prefixing them
 
 - **authOptions**: required. a set of options specific to the selected auth method type
 
-  - **roleID**: [authType=`approle`] required. the approle role-id to use
+  - For [authType=`approle`]:
 
-  - **secretID**: [authType=`approle`] the approle secret-id to use
+    - **roleID**: required. the approle role-id to use
 
-  - **secretIDFile**: [authType=`approle`] the path to a file containing a secret-id (recommended method in production environments)
+    - **secretID**: the approle secret-id to use
 
-  - **secretIDEnv**: [authType=`approle`] the name of an environment variable that contains the secret-id
+    - **secretIDFile**: the path to a file containing a secret-id (recommended method in production environments)
 
-  - **isWrappingToken**: [authType=`approle`] set true if the secret-id is wrapped
+    - **secretIDEnv**: the name of an environment variable that contains the secret-id
 
-  - **role**: [authType=`kubernetes`] required. the kubernetes role to use
+    - **isWrappingToken**: set true if the secret-id is wrapped
+  
+  - For [authType=`kubernetes`]:
 
-  - **tokenPath**: [authType=`kubernetes`] the path to a token used to authenticate (default to the service account token path in a k8s pod)
+    - **role**: required. the kubernetes role to use
+
+    - **tokenPath**: the path to a token used to authenticate (default to the service account token path in a k8s pod)
+
+  - For [authType=`aws`]:
+
+    - **role**: required. the AWS role to use
+
+    - **awsAuthType**: required. the AWS authentication type to use, one of `iam` or `ec2`
+
+    - **region**: optional. the AWS region to use
+
+    - **iamServerIdHeader**: [awsAuthType=`iam`] optional. the additional header sent to Vault to mitigate replay attack
+
+    - **signatureType**: [awsAuthType=`ec2`] optional. the type of signature used to verify EC2 auth logins, one of `pkcs7`, `identity`, or `rsa2048`
+
+    - **nonce**: [awsAuthType=`ec2`] optional. the nonce sent to Vault to mitigate replay attack, a randomly generated nonce will be used if not provided
 
 Finally, remove the `"root"`, `"key"`, and `"crt"` values from your `$(step path)/config/ca.json`, and the associated files. These are generated by `step ca init` but are not used by RA servers.