Skip to content

Commit e9c3e24

Browse files
wgabor0427wgabor0427
committed
OSDOCS-15575 updated several modules
1 parent 8b11078 commit e9c3e24

7 files changed

+354
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1238,10 +1238,15 @@ Topics:
12381238
File: zero-trust-manager-install
12391239
- Name: Deploying Zero Trust Workload Identity Manager operands
12401240
File: zero-trust-manager-configuration
1241+
<<<<<<< HEAD
12411242
- Name: Configuring Zero Trust Workload Identity Manager OIDC Federation
12421243
File: zero-trust-manager-oidc-federation
12431244
- Name: Enabling create-only mode for the Zero Trust Workload Identity Manager
12441245
File: zero-trust-manager-reconciliation
1246+
=======
1247+
- Name: Zero Trust Workload Identity Manager upstream authority plugins
1248+
File: zero-trust-manager-upstream-authority
1249+
>>>>>>> 892f2e1a00 (OSDOCS-15575 updated several modules)
12451250
- Name: Monitoring Zero Trust Workload Identity Manager
12461251
File: zero-trust-manager-monitoring
12471252
- Name: Uninstalling the Zero Trust Workload Identity Manager

‎modules/zero-trust-manager-cert-manager-upstream-authority.adoc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manageer/zero-trust-manager-overview.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="zero-trust-manager-cert-manager-upstream-authority_{context}"]
7+
= About the cert-manager upstream authority plugin
8+
9+
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.
10+
11+
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.

‎modules/zero-trust-manager-configure-cert-manager.adoc‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="zero-trust-manager-configure-cert-manager_{context}"]
7+
= Configuring the cert-manager plugin
8+
9+
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.
10+
11+
.Prerequisites
12+
13+
* Access to a {product-title} cluster where the SPIRE Server runs.
14+
15+
* 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].
16+
17+
* A pre-configured cert-manager `Issuer` capable of signing intermediate Certificate Authority (CA) certificates.
18+
19+
.Procedure
20+
21+
. Create a YAML file that defines the `SpireSever` CR object, for example, `SpireServer.yaml`:
22+
+
23+
.Example `SpireServer.yaml`
24+
+
25+
[source,yaml]
26+
----
27+
apiVersion: operator.openshift.io/v1alpha1
28+
kind: SpireServer
29+
metadata:
30+
name: cluster
31+
spec:
32+
trustDomain: example.com
33+
upstreamAuthority:
34+
type: cert-manager
35+
certManager:
36+
issuerKind: Issuer #<1>
37+
issuerName: my-org-intermediate-ca #<2>
38+
namespace: my-namespace #<3>
39+
----
40+
41+
<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.
42+
<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).
43+
<3> Required when `issuerKind` is 'Issuer'. This field is omitted if using a `clusterIssuer`.
44+
45+
. Apply the configuration by running the following command:
46+
+
47+
[source,terminal]
48+
----
49+
$ oc apply -f SpireServer.yaml
50+
----
51+
52+
.Verification
53+
54+
. Ensure that the resulting signed certificate and trust bundle are available in the secret created by the SPIRE Operator:
55+
+
56+
[source,terminal]
57+
----
58+
$ oc get secret spire-server-server-ca -n spire -o yaml
59+
----
60+
+
61+
.Example signed certificate and trust bundle
62+
+
63+
[source,yaml]
64+
----
65+
apiVersion: v1
66+
kind: Secret
67+
metadata:
68+
name: spire-server-server-ca
69+
namespace: spire
70+
ownerReferences:
71+
- apiVersion: spire.spiffe.io/v1alpha1
72+
kind: SpireServer
73+
name: spire-server
74+
# ...
75+
type: Opaque
76+
data: <1>
77+
<trust_bundle> <2>
78+
ca.crt:
79+
<intermediate_CA_certificate> <3>
80+
ca.key:
81+
<private_key>
82+
----
83+
<1> The trust bundle containing the root CA and the intermediate CA.
84+
<2> The SPIRE Server's intermediate CA certificate signed by your Issuer.
85+
<3> The private key for the SPIRE Server's intermediate CA.
86+

‎modules/zero-trust-manager-configure-issuer.adoc‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="zero-trust-manager-configure-issuer_{context}"]
7+
8+
= Configuring the cert-manager issuer
9+
10+
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.
11+
12+
.Prerequisites
13+
14+
* 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].
15+
16+
17+
.Procedure
18+
19+
Create a cert-manager `Issuer` by performing the following steps:
20+
21+
. Generate the Transport Layer Security (TLS) Secret by running the following command:
22+
+
23+
[source,terminal]
24+
----
25+
$ oc create secret tls my-ca-key-pair-secret \
26+
--cert=path/to/your/ca.crt \
27+
--key=path/to/your/ca.key \
28+
--namespace=my-namespace
29+
----
30+
31+
. Create a YAML file that defines the `Issuer`, for example `ca-issuer.yaml`:
32+
+
33+
.Example `ca-issuer.yaml`
34+
+
35+
[source,yaml]
36+
----
37+
apiVersion: cert-manager.io/v1
38+
kind: Issuer
39+
metadata:
40+
name: my-ca-issuer
41+
namespace: my-namespace
42+
spec:
43+
ca:
44+
secretName: my-ca-key-pair-secret <1>
45+
----
46+
<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`.
47+
48+
. Apply the configuration by running the following command:
49+
+
50+
[source, terminal]
51+
----
52+
$ oc apply -f ca-issuer.yaml
53+
----
54+
55+
.Verification
56+
To verify that the `Issuer` is created, run the following command: (IS THIS CORRECT OR HOW DO WE VERIFY IT)

‎modules/zero-trust-manager-configure-vault.adoc‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manager/zero-trust-manager.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="zero-trust-manager-configure-cert-vault_{context}"]
7+
= Configuring the Vault plugin
8+
9+
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:
10+
11+
* Client Certificate Authentication
12+
13+
* Token Authentication
14+
15+
* `AppRole` Authentication
16+
17+
* Kubernetes Authentication
18+
19+
.Prerequisites
20+
21+
* A running and accessible HashiCorp Vault Server is available.
22+
23+
* A PKI secret engine is enabled and configured in Vault at the specified `pki_mount_point`.
24+
25+
* A role within the Vault PKI engine must be configured to allow issuing of intermediate CA certificates.
26+
27+
* The Vault token or authentication method used by the plugin must have the necessary permissions.
28+
29+
* 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.
30+
31+
.Procedure
32+
33+
. 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.
34+
+
35+
.Example `SpireServer.yaml`
36+
+
37+
[source,yaml]
38+
----
39+
apiVersion: spire.spiffe.io/v1alpha1
40+
kind: SpireServer
41+
metadata:
42+
name: spire-server
43+
namespace: spire
44+
spec:
45+
replicas: 1
46+
upstreamAuthority:
47+
vault:#
48+
address: "https://vault.example.com" <1>
49+
tokenPath: "/var/run/secrets/kubernetes.io/serviceaccount/token" <2>
50+
mtls:
51+
spireTrustDomain: "spiffe://example.org" <3>
52+
serverName: "vault.example.com" <4>
53+
pkcs11:
54+
jwt:
55+
----
56+
+
57+
<1> The URL of your Vault server.
58+
<2> The path to the Kubernetes service account token used for authentication with Vault.
59+
<3> The trust domain of your Spire Server.
60+
<4> The name used for Mutual Transport Layer Security (mTLS) authentication with the Vault server.
61+
62+
. Configure one of the authentication methods:
63+
.. Configure the `certAuth` authentication in the `upstreamAuthority` section of the `SpireServer.yaml` file. This method uses a client certificate and private key for authentication.
64+
+
65+
.Example `certAuth`
66+
+
67+
[source,yaml]
68+
----
69+
# ...
70+
upstreamAuthority:
71+
vault:
72+
certAuth:
73+
certAuthMountPoint: "cert" <1>
74+
clientCertSecret: "vault-client-cert-secret" <2>
75+
clientKeySecret: "vault-client-key-secret" <3>
76+
certAuthRoleName: "spire-server-role" <4>
77+
----
78+
+
79+
<1> The mount point where the TLS certificate auth method is enabled.
80+
<2> Name of the Kubernetes secret containing the client certificate in Privacy Enhanced Mail (PEM) format.
81+
<3> Name of the Kubernetes secret containing the client private key in PEM format.
82+
<4> The name of the Vault role to authenticate against.
83+
84+
.. Configure the `tokenAuth` authentication in the `spstreamAuthority` section of the `SpireServer.yaml` file. This method uses a static Vault token.
85+
+
86+
.Example `tokenAuth`
87+
+
88+
[source,yaml]
89+
----
90+
# ...
91+
upstreamAuthority:
92+
vault:
93+
tokenAuth:
94+
token: "hvs.YOUR_VAULT_TOKEN_HERE"
95+
----
96+
97+
.. Configure the `appRoleAuth` authentication in the `upstreamAuthority` section of the `SpireServer.yaml` file. This method uses the `AppRole` for Vault.
98+
+
99+
.Example `tokenAuth`
100+
+
101+
[source,yaml]
102+
----
103+
# ...
104+
upstreamAuthority:
105+
vault:
106+
appRoleAuth:
107+
appRoleMountPoint: "approle" <1>
108+
appRoleID: "your-approle-id" <2>
109+
appRoleSecretID: "your-approle-secret-id" <3>
110+
----
111+
+
112+
<1> The mount point where the `AppRole` auth method is enabled.
113+
<2> The `appRoleID` used for authentication.
114+
<3> the `appRoleSecretID` used for authentication.
115+
116+
. Configure the `k8sAuth` authentication in the `upstreamAuthority` section of the `SpireServer.yaml` file. This method uses a Kubernetes `ServiceAccount` token for authentication.
117+
+
118+
.Example `tokenAuth`
119+
+
120+
[source,yaml]
121+
----
122+
# ...
123+
upstreamAuthority:
124+
vault:
125+
k8sAuth:
126+
k8sAuthMountPoint: "kubernetes" <1>
127+
k8sAuthRoleName: "spire-server-k8s-role" <2>
128+
tokenPath: "/var/run/secrets/kubernetes.io/serviceaccount/token" <3>
129+
----
130+
+
131+
<1> The mount point where the Kubernetes auth method is enabled.
132+
<2> The name of the Vault role the plugin authenticates against.
133+
<3> The path to the Kubernetes `ServiceAccount` token file.
134+
135+
. Apply the configuration by running the following command:
136+
+
137+
[source, terminal]
138+
----
139+
$ oc apply -f spireserver.yaml
140+
----

‎modules/zero-trust-manager-vault-upstream-authority.adoc‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manageer/zero-trust-manager-overview.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="zero-trust-manager-vault-upstream-authority_{context}"]
7+
= About the Vault upstream authority plugin
8+
9+
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.
10+
11+
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.
12+
13+
[NOTE]
14+
====
15+
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.
16+
====

‎security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority.adoc‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="zero-trust-manager-upstream-authority-plugins"]
3+
= Zero Trust Workload Identity Manager upstream authority plugins
4+
5+
include::_attributes/common-attributes.adoc[]
6+
:context: zero-trust-manager-overview
7+
8+
toc::[]
9+
10+
:FeatureName: Zero Trust Workload Identity Manager
11+
include::snippets/technology-preview.adoc[]
12+
13+
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.
14+
15+
The following upstream authority plugins are available:
16+
17+
* cert-manager
18+
19+
* vault
20+
21+
== Configuring the cert-manager plugin
22+
23+
// About the cert-manager plug in
24+
include::modules/zero-trust-manager-cert-manager-upstream-authority.adoc[leveloffset=+1]
25+
26+
// Configuring an issuer
27+
include::modules/zero-trust-manager-configure-issuer.adoc[leveloffset=+1]
28+
29+
// Configuring the cert-manager plugin
30+
include::modules/zero-trust-manager-configure-cert-manager.adoc[leveloffset=+1]
31+
32+
== Configuring the Vault plugin
33+
34+
// About the vault plug in
35+
include::modules/zero-trust-manager-vault-upstream-authority.adoc[leveloffset=+1]
36+
37+
// Configuring the vault plugin
38+
include::modules/zero-trust-manager-configure-vault.adoc[leveloffset=+1]
39+
40+

0 commit comments

Comments
 (0)