Workload Identity Resource Documentation

docs/config.json

@@ -289,6 +289,11 @@
       "destination": "/reference/operator-resources/resources-teleport-dev-users/",
       "permanent": true
     },
+    {
+      "source": "/enroll-resources/workload-identity/workload-attestation/",
+      "destination": "/reference/workload-identity/workload-identity-api-and-workload-attestation/",
+       "permanent": true
+    },
     {
       "source": "/access-controls/guides/role-templates/",
       "destination": "/admin-guides/access-controls/guides/role-templates/",

docs/cspell.json

@@ -1003,6 +1003,7 @@
     "webproxy",
     "webui",
     "westeurope",
+    "WIMSE",
     "winadj",
     "windowsaccountname",
     "windowsdesktop",

docs/pages/enroll-resources/workload-identity/introduction.mdx

@@ -97,10 +97,11 @@ Teleport Proxy is not used for securing workload-to-workload communication.
 Learn more about Teleport Workload Identity:
 
 - [SPIFFE](./spiffe.mdx): Learn about the SPIFFE specification and how it is implemented by Teleport Workload Identity.
-- [Workload Attestation](./workload-attestation.mdx): Learn about using Workload Attestation to securely issue SVIDs to specific workloads.
 - [Federation](./federation.mdx): Learn about using Federation to allow workloads to trust workloads from other trust domains.
 - [JWT SVIDs](./jwt-svids.mdx): Learn about the short-lived JWTs issued by Workload Identity.
 - [Best Practices](./best-practices.mdx): Best practices for using Workload Identity in Production.
+- [WorkloadIdentity Resource](../../reference/workload-identity/workload-identity-resource.mdx): The full reference for the WorkloadIdentity resource.
+- [Workload Identity API and Workload Attestation](../../reference/workload-identity/workload-identity-api-and-workload-attestation.mdx): To learn more about the Workload Identity API and Workload Attestation.
 
 Learn how to configure Teleport Workload Identity for specific use-cases:
 

docs/pages/includes/machine-id/workload-identity-selector-config.yaml

@@ -0,0 +1,12 @@
+# Selector is used to control which WorkloadIdentity resource will be used to
+# issue the workload identity credential. The selector can either be the name of
+# a specific WorkloadIdentity resource or a label selector that can match
+# multiple WorkloadIdentity resources.
+#
+# The selector must be set to either a name or labels, but not both.
+selector:
+  # Name is used to select a specific WorkloadIdentity resource by its name.
+  name: foo
+  # Labels is used to select multiple WorkloadIdentity resources by their labels.
+  labels:
+    app: [foo, bar]

docs/pages/reference/cli/tbot.mdx

@@ -509,8 +509,87 @@ command supports these additional flags:
 | `--username` | The database user name. The bot user must have permission to connect as this user. Required. |
 | `--database` | The name of the database available in the requested service. Required. |
 
+## tbot start workload-identity-x509
+
+Issues an X509 workload identity credential using Teleport Workload Identity and
+writes this credential to a specified destination.
+
+See [TODO] for further information about the workload identity credential output
+and the YAML configuration file format.
+
+### Flags
+
+In addition to the [common `tbot start` flags](#common-start-flags), this
+command supports these additional flags:
+
+| Flag                                     | Description                                                                                                                                                        |
+|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--destination`                          | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required.                                                     |
+| `--reader-user`                          | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux.                                 |
+| `--reader-group`                         | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux.                                |
+| `--[no-]include-federated-trust-bundles` | If set, include federated trust bundles in the output                                                                                                              |
+| `--name-selector`                        | Specifies a WorkloadIdentity resource by name to use when issuing the X509 for a workload. Mutually exclusive with `--label-selector`.                             |
+| `--label-selector`                       | Specifies a set of labels to use when selecting WorkloadIdentity resources to use when issuing the X509 for a workload. Mutually exclusive with `--name-selector`. |
+
+## tbot start workload-identity-jwt
+
+Issues a JWT workload identity credential using Teleport Workload Identity and
+writes this credential to a specified destination.
+
+The JWT workload identity credential is compatible with the [SPIFFE JWT SVID
+specification](https://github.com/spiffe/spiffe/blob/main/standards/JWT-SVID.md).
+
+See [TODO] for further information about the workload identity credential output
+and the YAML configuration file format.
+
+### Flags
+
+In addition to the [common `tbot start` flags](#common-start-flags), this
+command supports these additional flags:
+
+| Flag               | Description                                                                                                                                                        |
+|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--destination`    | A destination URI, such as file:///foo/bar. See [Destination URIs](#destination-uris) for more info. Required.                                                     |
+| `--reader-user`    | An additional user name or UID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux.                                 |
+| `--reader-group`   | An additional group name or GID that should be allowed by ACLs to read this destination. Only valid for file destinations on Linux.                                |
+| `--name-selector`  | Specifies a WorkloadIdentity resource by name to use when issuing the X509 for a workload. Mutually exclusive with `--label-selector`.                             |
+| `--label-selector` | Specifies a set of labels to use when selecting WorkloadIdentity resources to use when issuing the X509 for a workload. Mutually exclusive with `--name-selector`. |
+| `--audience`       | The audience for the JWT. Can be provided multiple times to produce a JWT with multiple audiences. At least one audience must be provided.                         |
+
+## tbot start workload-identity-api
+
+Starts the `tbot` agent and opens a listener for the local workload identity
+API.
+
+The configuration for this service can be complex, and therefore, it is
+recommended that you leverage the YAML configuration.
+
+See [Workload Identity API & Workload Attestation](../workload-identity/workload-identity-api-and-workload-attestation.mdx)
+for further information about the local workload identity API and the YAML
+configuration.
+
+### Flags
+
+In addition to the [common `tbot start` flags](#common-start-flags), this
+command supports these additional flags:
+
+| Flag               | Description                                                                                                                                                        |
+|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--listen`         | A socket URI to listen on, e.g. `tcp://localhost:1234` or `unix:///opt/workload-identity.sock`. Required.                                                          |
+| `--name-selector`  | Specifies a WorkloadIdentity resource by name to use when issuing the X509 for a workload. Mutually exclusive with `--label-selector`.                             |
+| `--label-selector` | Specifies a set of labels to use when selecting WorkloadIdentity resources to use when issuing the X509 for a workload. Mutually exclusive with `--name-selector`. |
+
 ## tbot start spiffe-svid
 
+<Admonition type="warning" >
+The use of this command has been deprecated as part of the introduction of the
+new Workload Identity configuration experience. You can replace the use of this
+command with the new `tbot start workload-identity-x509` command.
+
+For further information, see [the new Workload Identity configuration experience
+and how to migrate](../workload-identity/configuration-resource-migration.mdx).
+</Admonition>
+
 ### Flags
 
 In addition to the [common `tbot start` flags](#common-start-flags), this

docs/pages/reference/machine-id/configuration.mdx

@@ -311,8 +311,70 @@ principals:
 (!docs/pages/includes/machine-id/common-output-config.yaml!)
 ```
 
+### `workload-identity-x509`
+
+The `workload-identity-x509` output is used to issue an X509 workload identity
+credential and write this to a configured destination.
+
+The output generates the following artifacts:
+
+- `svid.pem`: the X509 SVID.
+- `svid.key`: the private key associated with the X509 SVID.
+- `bundle.pem`: the X509 bundle that contains the trust domain CAs.
+
+See [Workload Identity introduction](../../enroll-resources/workload-identity/introduction.mdx)
+for more information on Workload Identity functionality.
+
+```yaml
+# type specifies the type of the output. For the X509 Workload Identity output,
+# this will always be `workload-identity-x509`.
+type: workload-identity-x509
+(!docs/pages/includes/machine-id/workload-identity-selector-config.yaml!)
+(!docs/pages/includes/machine-id/common-output-config.yaml!)
+```
+
+### `workload-identity-jwt`
+
+The `workload-identity-jwt` output is used to issue a JWT workload identity
+credential and write this to a configured destination.
+
+The JWT workload identity credential is compatible with the [SPIFFE JWT SVID
+specification](https://github.com/spiffe/spiffe/blob/main/standards/JWT-SVID.md).
+
+The output generates the following artifacts:
+
+- `jwt_svid`: the JWT SVID.
+
+See [Workload Identity introduction](../../enroll-resources/workload-identity/introduction.mdx)
+for more information on Workload Identity functionality.
+
+```yaml
+# type specifies the type of the output. For the JWT Workload Identity output,
+# this will always be `workload-identity-jwt`.
+type: workload-identity-jwt
+# audiences specifies the values that should be included in the `aud` claim of
+# the JWT. Typically, this identifies the intended recipient of the JWT and
+# contains a single value.
+#
+# At least one audience value must be specified.
+audiences:
+ - example.com
+ - foo.example.com
+(!docs/pages/includes/machine-id/workload-identity-selector-config.yaml!)
+(!docs/pages/includes/machine-id/common-output-config.yaml!)
+```
+
 ### `spiffe-svid`
 
+<Admonition type="warning" >
+The use of this service has been deprecated as part of the introduction of the
+new Workload Identity configuration experience. You can replace the use of this
+output with the new `workload-identity-x509` or `workload-identity-jwt` service.
+
+For further information, see [the new Workload Identity configuration experience
+and how to migrate](../workload-identity/configuration-resource-migration.mdx).
+</Admonition>
+
 The `spiffe-svid` output is used to generate a SPIFFE X509 SVID and write this
 to a configured destination.
 
@@ -367,8 +429,26 @@ Outputs, they may not necessarily generate artifacts. Typically, services
 provide supporting functionality for machine to machine access, for example,
 opening tunnels or providing APIs.
 
+### `workload-identity-api`
+
+The `workload-identity-api` services opens a listener that provides a local
+workload identity API, intended to serve workload identity credentials
+(e.g X509/JWT SPIFFE SVIDs) to workloads running on the same host.
+
+For more information about this, see the
+[Workload Identity API and Workload Attestation reference](../workload-identity/workload-identity-api-and-workload-attestation.mdx)
+
 ### `spiffe-workload-api`
 
+<Admonition type="warning" >
+The use of this service has been deprecated as part of the introduction of the
+new Workload Identity configuration experience. You can replace the use of this
+service with the new `workload-identity-api` service.
+
+For further information, see [the new Workload Identity configuration experience
+and how to migrate](../workload-identity/configuration-resource-migration.mdx).
+</Admonition>
+
 The `spiffe-workload-api` service opens a listener for a service that implements
 the SPIFFE Workload API. This service is used to provide SPIFFE SVIDs to
 workloads.
@@ -500,10 +580,10 @@ service, three additional special names can be used to aid configuration:
 
 - `default`: `tbot` will return the default SVID for the workload.
 - `ROOTCA`: `tbot` will return the trust bundle for the trust domain that the
-   workload is a member of.
+workload is a member of.
 - `ALL`: `tbot` will return the trust bundle for the trust domain that the
-  workload is a member of, as well as the trust bundles of any trust domain
-  that the trust domain is federated with.
+workload is a member of, as well as the trust bundles of any trust domain
+that the trust domain is federated with.
 
 The following is an example Envoy configuration that sources a certificate
 and trust bundle from the `spiffe-workload-api` service listening on