From e9c3e24c08e4a21e502278448ed9cdd48b667ba6 Mon Sep 17 00:00:00 2001 From: William Gabor Date: Mon, 28 Jul 2025 15:51:00 -0400 Subject: [PATCH 1/2] OSDOCS-15575 updated several modules --- _topic_maps/_topic_map.yml | 5 + ...nager-cert-manager-upstream-authority.adoc | 11 ++ ...-trust-manager-configure-cert-manager.adoc | 86 +++++++++++ .../zero-trust-manager-configure-issuer.adoc | 56 +++++++ .../zero-trust-manager-configure-vault.adoc | 140 ++++++++++++++++++ ...rust-manager-vault-upstream-authority.adoc | 16 ++ ...zero-trust-manager-upstream-authority.adoc | 40 +++++ 7 files changed, 354 insertions(+) create mode 100644 modules/zero-trust-manager-cert-manager-upstream-authority.adoc create mode 100644 modules/zero-trust-manager-configure-cert-manager.adoc create mode 100644 modules/zero-trust-manager-configure-issuer.adoc create mode 100644 modules/zero-trust-manager-configure-vault.adoc create mode 100644 modules/zero-trust-manager-vault-upstream-authority.adoc create mode 100644 security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index b1c806bbe621..a8ccd692b6d5 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -1238,10 +1238,15 @@ Topics: File: zero-trust-manager-install - Name: Deploying Zero Trust Workload Identity Manager operands File: zero-trust-manager-configuration +<<<<<<< HEAD - Name: Configuring Zero Trust Workload Identity Manager OIDC Federation File: zero-trust-manager-oidc-federation - Name: Enabling create-only mode for the Zero Trust Workload Identity Manager File: zero-trust-manager-reconciliation +======= + - Name: Zero Trust Workload Identity Manager upstream authority plugins + File: zero-trust-manager-upstream-authority +>>>>>>> 892f2e1a00 (OSDOCS-15575 updated several modules) - Name: Monitoring Zero Trust Workload Identity Manager File: zero-trust-manager-monitoring - Name: Uninstalling the Zero Trust Workload Identity Manager diff --git a/modules/zero-trust-manager-cert-manager-upstream-authority.adoc b/modules/zero-trust-manager-cert-manager-upstream-authority.adoc new file mode 100644 index 000000000000..99e115cf972a --- /dev/null +++ b/modules/zero-trust-manager-cert-manager-upstream-authority.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * security/zero_trust_workload_identity_manageer/zero-trust-manager-overview.adoc + +:_mod-docs-content-type: CONCEPT +[id="zero-trust-manager-cert-manager-upstream-authority_{context}"] += About the cert-manager upstream authority plugin + +The cert-manager plugin enables the SPIRE Server to dynamically request and receive intermediate signing certificates from cert-manager. The plugin automates the management of the SPIRE Server intermediate signing certificates by integrating with cert-manager. + +When a SPIRE Server needs a new certificate, the cert-manager plugin creates a `CertificateRequest` custom resource in the configured {product-title} namespace. The namespace includes the Certificate Signing Request (CSR) generated by the SPIRE Server. The cert-manager plugin processes the `CertificateRequest` and an associated `Issuer` signs the Certificate Signing Request (CSR). The signed intermediate certificate and the full Certificate Authority (CA) bundle are available in the `CertificateRequest` status. These signed credentials are available to the SPIRE Server and used as its upstream signing authority. \ No newline at end of file diff --git a/modules/zero-trust-manager-configure-cert-manager.adoc b/modules/zero-trust-manager-configure-cert-manager.adoc new file mode 100644 index 000000000000..3021d4a9dd0d --- /dev/null +++ b/modules/zero-trust-manager-configure-cert-manager.adoc @@ -0,0 +1,86 @@ +// Module included in the following assemblies: +// +// * security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc + +:_mod-docs-content-type: CONCEPT +[id="zero-trust-manager-configure-cert-manager_{context}"] += Configuring the cert-manager plugin + +The cert-manager plugin for the SPIRE Server automates the intermediate signing certificates lifecycle of a SPIRE Server. The plugin manages the creation, renewal, and rotation of the signing certificates. + +.Prerequisites + +* Access to a {product-title} cluster where the SPIRE Server runs. + +* cert-manager is installed and running within the Kubernetes cluster. For more information about installing cert-manager, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html-single/security_and_compliance/index#cert-manager-operator-install[Installing the cert-manager Operator for Red{nbsp}Hat OpenShift]. + +* A pre-configured cert-manager `Issuer` capable of signing intermediate Certificate Authority (CA) certificates. + +.Procedure + +. Create a YAML file that defines the `SpireSever` CR object, for example, `SpireServer.yaml`: ++ +.Example `SpireServer.yaml` ++ +[source,yaml] +---- +apiVersion: operator.openshift.io/v1alpha1 +kind: SpireServer +metadata: + name: cluster +spec: + trustDomain: example.com + upstreamAuthority: + type: cert-manager + certManager: + issuerKind: Issuer #<1> + issuerName: my-org-intermediate-ca #<2> + namespace: my-namespace #<3> +---- + +<1> Specifies the type of cert-manager issuer to use. The value `Issuer` indicates it is a namespace resource. The other option is `clusterIssuer`, which is a cluster-wide resource. +<2> The name of the `Issuer` or `CluserIssuer` resource within cert-manager that signs the certificate request. The issuer should already exist and configured to connect to the Public Key Infrastructure (PKI). +<3> Required when `issuerKind` is 'Issuer'. This field is omitted if using a `clusterIssuer`. + +. Apply the configuration by running the following command: ++ +[source,terminal] +---- +$ oc apply -f SpireServer.yaml +---- + +.Verification + +. Ensure that the resulting signed certificate and trust bundle are available in the secret created by the SPIRE Operator: ++ +[source,terminal] +---- +$ oc get secret spire-server-server-ca -n spire -o yaml +---- ++ +.Example signed certificate and trust bundle ++ +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + name: spire-server-server-ca + namespace: spire + ownerReferences: + - apiVersion: spire.spiffe.io/v1alpha1 + kind: SpireServer + name: spire-server + # ... +type: Opaque +data: <1> + <2> + ca.crt: + <3> + ca.key: + +---- +<1> The trust bundle containing the root CA and the intermediate CA. +<2> The SPIRE Server's intermediate CA certificate signed by your Issuer. +<3> The private key for the SPIRE Server's intermediate CA. + diff --git a/modules/zero-trust-manager-configure-issuer.adoc b/modules/zero-trust-manager-configure-issuer.adoc new file mode 100644 index 000000000000..d61b5ef9d9e9 --- /dev/null +++ b/modules/zero-trust-manager-configure-issuer.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc + +:_mod-docs-content-type: PROCEDURE +[id="zero-trust-manager-configure-issuer_{context}"] + += Configuring the cert-manager issuer + +Before you can configure the cert-manager plugin, you need to create an `Issuer` since the `Issuer` represents the Certificate Authority (CA) and defines how certificates are issued. + +.Prerequisites + +* cert-manager is installed and running within the {product-tile} cluster. For more information about installing cert-manager, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html-single/security_and_compliance/index#cert-manager-operator-install[Installing the cert-manager Operator for Red{nbsp}Hat OpenShift]. + + +.Procedure + +Create a cert-manager `Issuer` by performing the following steps: + +. Generate the Transport Layer Security (TLS) Secret by running the following command: ++ +[source,terminal] +---- +$ oc create secret tls my-ca-key-pair-secret \ + --cert=path/to/your/ca.crt \ + --key=path/to/your/ca.key \ + --namespace=my-namespace +---- + +. Create a YAML file that defines the `Issuer`, for example `ca-issuer.yaml`: ++ +.Example `ca-issuer.yaml` ++ +[source,yaml] +---- +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: my-ca-issuer + namespace: my-namespace +spec: + ca: + secretName: my-ca-key-pair-secret <1> +---- +<1> The name of the Kubernetes Secret that holds the `tls.cert` and `tls.key` files. This secret must exist before you create the `Issuer`. + +. Apply the configuration by running the following command: ++ +[source, terminal] +---- +$ oc apply -f ca-issuer.yaml +---- + +.Verification +To verify that the `Issuer` is created, run the following command: (IS THIS CORRECT OR HOW DO WE VERIFY IT) \ No newline at end of file diff --git a/modules/zero-trust-manager-configure-vault.adoc b/modules/zero-trust-manager-configure-vault.adoc new file mode 100644 index 000000000000..a630efd2ff56 --- /dev/null +++ b/modules/zero-trust-manager-configure-vault.adoc @@ -0,0 +1,140 @@ +// Module included in the following assemblies: +// +// * security/zero_trust_workload_identity_manager/zero-trust-manager.adoc + +:_mod-docs-content-type: PROCEDURE +[id="zero-trust-manager-configure-cert-vault_{context}"] += Configuring the Vault plugin + +This procedure outlines the steps required to configure a SPIRE Server to obtain its intermediate signing certificates from HashiCorp Vault. The plugin supports the following methods for authenticating to Vault: + +* Client Certificate Authentication + +* Token Authentication + +* `AppRole` Authentication + +* Kubernetes Authentication + +.Prerequisites + +* A running and accessible HashiCorp Vault Server is available. + +* A PKI secret engine is enabled and configured in Vault at the specified `pki_mount_point`. + +* A role within the Vault PKI engine must be configured to allow issuing of intermediate CA certificates. + +* The Vault token or authentication method used by the plugin must have the necessary permissions. + +* The `ca_ttl` property configured in your SPIRE Server configuration must be less than or equal to the configured `max_lease_ttl` of the Vault PKI secret engine role that the plugin uses. + +.Procedure + +. Create a YAML file containing the configuration for the `SpireServer` resource, for example `SpireServer.yaml`. The file includes the `spec` block and the `upstreamAuthority` block configured to use the `vault` plugin. ++ +.Example `SpireServer.yaml` ++ +[source,yaml] +---- +apiVersion: spire.spiffe.io/v1alpha1 +kind: SpireServer +metadata: + name: spire-server + namespace: spire +spec: + replicas: 1 + upstreamAuthority: + vault:# + address: "https://vault.example.com" <1> + tokenPath: "/var/run/secrets/kubernetes.io/serviceaccount/token" <2> + mtls: + spireTrustDomain: "spiffe://example.org" <3> + serverName: "vault.example.com" <4> + pkcs11: + jwt: +---- ++ +<1> The URL of your Vault server. +<2> The path to the Kubernetes service account token used for authentication with Vault. +<3> The trust domain of your Spire Server. +<4> The name used for Mutual Transport Layer Security (mTLS) authentication with the Vault server. + +. Configure one of the authentication methods: +.. Configure the `certAuth` authentication in the `upstreamAuthority` section of the `SpireServer.yaml` file. This method uses a client certificate and private key for authentication. ++ +.Example `certAuth` ++ +[source,yaml] +---- +# ... +upstreamAuthority: + vault: + certAuth: + certAuthMountPoint: "cert" <1> + clientCertSecret: "vault-client-cert-secret" <2> + clientKeySecret: "vault-client-key-secret" <3> + certAuthRoleName: "spire-server-role" <4> +---- ++ +<1> The mount point where the TLS certificate auth method is enabled. +<2> Name of the Kubernetes secret containing the client certificate in Privacy Enhanced Mail (PEM) format. +<3> Name of the Kubernetes secret containing the client private key in PEM format. +<4> The name of the Vault role to authenticate against. + +.. Configure the `tokenAuth` authentication in the `spstreamAuthority` section of the `SpireServer.yaml` file. This method uses a static Vault token. ++ +.Example `tokenAuth` ++ +[source,yaml] +---- +# ... +upstreamAuthority: + vault: + tokenAuth: + token: "hvs.YOUR_VAULT_TOKEN_HERE" +---- + +.. Configure the `appRoleAuth` authentication in the `upstreamAuthority` section of the `SpireServer.yaml` file. This method uses the `AppRole` for Vault. ++ +.Example `tokenAuth` ++ +[source,yaml] +---- +# ... +upstreamAuthority: + vault: + appRoleAuth: + appRoleMountPoint: "approle" <1> + appRoleID: "your-approle-id" <2> + appRoleSecretID: "your-approle-secret-id" <3> +---- ++ +<1> The mount point where the `AppRole` auth method is enabled. +<2> The `appRoleID` used for authentication. +<3> the `appRoleSecretID` used for authentication. + +. Configure the `k8sAuth` authentication in the `upstreamAuthority` section of the `SpireServer.yaml` file. This method uses a Kubernetes `ServiceAccount` token for authentication. ++ +.Example `tokenAuth` ++ +[source,yaml] +---- +# ... +upstreamAuthority: + vault: + k8sAuth: + k8sAuthMountPoint: "kubernetes" <1> + k8sAuthRoleName: "spire-server-k8s-role" <2> + tokenPath: "/var/run/secrets/kubernetes.io/serviceaccount/token" <3> +---- ++ +<1> The mount point where the Kubernetes auth method is enabled. +<2> The name of the Vault role the plugin authenticates against. +<3> The path to the Kubernetes `ServiceAccount` token file. + +. Apply the configuration by running the following command: ++ +[source, terminal] +---- +$ oc apply -f spireserver.yaml +---- diff --git a/modules/zero-trust-manager-vault-upstream-authority.adoc b/modules/zero-trust-manager-vault-upstream-authority.adoc new file mode 100644 index 000000000000..17aece07122e --- /dev/null +++ b/modules/zero-trust-manager-vault-upstream-authority.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * security/zero_trust_workload_identity_manageer/zero-trust-manager-overview.adoc + +:_mod-docs-content-type: CONCEPT +[id="zero-trust-manager-vault-upstream-authority_{context}"] += About the Vault upstream authority plugin + +The Vault plugin integrates the SPIRE Server with the HashiCorp Vault Public Key Infrastructure (PKI) engine to manage the lifecycle of intermediate CA certificates. The SPIRE Server uses the CA certificates to sign the workload {svid-full}. The plugin enables the SPIRE Server to use the PKI for issuing and renewing intermediate signing certificates. + +The plugin interacts with the PKI secret engine to request intermediate CA certificates, signs the requests, and then provides the certificates to the SPIRE Server. + +[NOTE] +==== +The Vault plugin does not support the `PublishJWTKey` remote procedure call (RPC) and should not be used in SPIRE configurations where JSON Web Tokens-SPIFFE Verifiable Identity Documents (JWT-SVIDs) are used. +==== \ No newline at end of file diff --git a/security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority.adoc b/security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority.adoc new file mode 100644 index 000000000000..73bc39d653c1 --- /dev/null +++ b/security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority.adoc @@ -0,0 +1,40 @@ +:_mod-docs-content-type: ASSEMBLY +[id="zero-trust-manager-upstream-authority-plugins"] += Zero Trust Workload Identity Manager upstream authority plugins + +include::_attributes/common-attributes.adoc[] +:context: zero-trust-manager-overview + +toc::[] + +:FeatureName: Zero Trust Workload Identity Manager +include::snippets/technology-preview.adoc[] + +Upstream authority plugins are components that allow the SPIRE Server to integrate with an existing Public Key Infrastructure (PKI) to obtain intermediate signing certificates. The SPIRE Server then uses these intermediate certificates to cryptographically sign the {svid-full} that it issues to workloads. The plugins also allow the SPIRE Server to use a pre-existing root of trust, rather than establishing a new, isolated root of trust. + +The following upstream authority plugins are available: + +* cert-manager + +* vault + +== Configuring the cert-manager plugin + +// About the cert-manager plug in +include::modules/zero-trust-manager-cert-manager-upstream-authority.adoc[leveloffset=+1] + +// Configuring an issuer +include::modules/zero-trust-manager-configure-issuer.adoc[leveloffset=+1] + +// Configuring the cert-manager plugin +include::modules/zero-trust-manager-configure-cert-manager.adoc[leveloffset=+1] + +== Configuring the Vault plugin + +// About the vault plug in +include::modules/zero-trust-manager-vault-upstream-authority.adoc[leveloffset=+1] + +// Configuring the vault plugin +include::modules/zero-trust-manager-configure-vault.adoc[leveloffset=+1] + + From 903b32e0861099814ae7e8b1d40e30f22a81f7ef Mon Sep 17 00:00:00 2001 From: William Gabor Date: Mon, 20 Oct 2025 11:42:17 -0400 Subject: [PATCH 2/2] OSDOCS-1575 updated topic map --- _topic_maps/_topic_map.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index a8ccd692b6d5..687cd4b03d7e 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -1238,15 +1238,12 @@ Topics: File: zero-trust-manager-install - Name: Deploying Zero Trust Workload Identity Manager operands File: zero-trust-manager-configuration -<<<<<<< HEAD - Name: Configuring Zero Trust Workload Identity Manager OIDC Federation File: zero-trust-manager-oidc-federation - Name: Enabling create-only mode for the Zero Trust Workload Identity Manager File: zero-trust-manager-reconciliation -======= - Name: Zero Trust Workload Identity Manager upstream authority plugins File: zero-trust-manager-upstream-authority ->>>>>>> 892f2e1a00 (OSDOCS-15575 updated several modules) - Name: Monitoring Zero Trust Workload Identity Manager File: zero-trust-manager-monitoring - Name: Uninstalling the Zero Trust Workload Identity Manager