Skip to content

Commit b6d420a

Browse files
wgabor0427wgabor0427
committed
OSDOCS-15575 updated module
1 parent bfe6f7f commit b6d420a

8 files changed

+413
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1239,6 +1239,8 @@ Topics:
12391239
File: zero-trust-manager-install
12401240
- Name: Deploying Zero Trust Workload Identity Manager operands
12411241
File: zero-trust-manager-configuration
1242+
- Name: Zero Trust Workload Identity Manager upstream authority plugins
1243+
File: zero-trust-manager-upstream-authority
12421244
- Name: Monitoring Zero Trust Workload Identity Manager
12431245
File: zero-trust-manager-monitoring
12441246
- Name: Uninstalling Zero Trust Workload Identity Manager

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

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
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-cert-manager-crd_{context}"]
7+
= Configuring cert-manager plugin using the SPIRE server CRD
8+
9+
To configure the cert-manager plugin using the SPIRE server Custom Resource Defnition (CRD), perform the following steps:
10+
11+
.Procedure
12+
13+
. 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 `cert-manager` plugin.
14+
+
15+
.Example `spireserver.yaml`
16+
+
17+
[source,yaml]
18+
----
19+
apiVersion: operator.openshift.io/v1alpha1
20+
kind: SpireServer
21+
metadata:
22+
name: cluster
23+
spec:
24+
trustDomain: "example.org"
25+
upstreamAuthority:
26+
type: "cert-manager"
27+
upstreamAuthorityCertManager:
28+
issuerName: "ca-issuer" <1>
29+
issuerKind: "ClusterIssuer" <2>
30+
issuerGroup: "cert-manager.io" <3>
31+
namespace: "zero-trust-workload-identity-manager" <4>
32+
kubeConfigSecretName: "external-cluster-kubeconfig" <5>
33+
----
34+
<1> The name of the `cert-manager` Issuer or ClusterIssuer that signs the `certificateRequest`.
35+
<2> Set to `ClusterIssuer` if issuer is cluster-scoped. The default is `Issuer`.
36+
<3> The API group of the issuer. The default is `cert-manager.io`.
37+
<4> The namespace where the `CertificateRequest` is created. The default is `zero-trust-workload-identity-manager`.
38+
<5> The name of a Secret containing the `kubeconfig` to connect to the clsuter where `cert-manager` is running. If empy, an in-cluster configuration is used.
39+
40+
. Apply the configuration by running the following command:
41+
+
42+
[source, terminal]
43+
----
44+
$ oc apply -f spireserver.yaml
45+
----
46+
47+
.Verification
48+
49+
. Run the following command to list the `CertificateRequest` resources in the namespace where the SPIRE server creates them.
50+
+
51+
[source, terminal]
52+
----
53+
$ oc get certificaterequests -n <namespace>
54+
----
55+
56+
. Run the following command ot inspect a specific `CertificateRequest`. Review the `Status` section to confirm the certificate has been signed and that the certificate data is present.
57+
+
58+
[source, terminal]
59+
----
60+
$ oc describe certificaterequest <name-of-cert-request> -n <namespace>
61+
----

‎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 Kubernetes namespace. The namespace has the Certificate Signing Request (CSR) generated by the SPIRE server. The cert-manager plugin processes the `CertificateRequest` and an associated `Issuer` signs the 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: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
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 Kubernetes 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 `SpiffeCSIDriver.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` means it is a namespace resource. The other options is `ClusterIssuer`, which is a cluter-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 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+
$ kubectl 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:
77+
# The trust bundle containing the root CA and the intermediate CA
78+
bundle.crt:
79+
<trust_bundle>
80+
# The SPIRE Server's intermediate CA certificate signed by your Issuer
81+
ca.crt:
82+
<intermediate_CA_certificate>
83+
84+
# The private key for the SPIRE Server's intermediate CA
85+
ca.key:
86+
<private_key>
87+
----
88+

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
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+
= Configuring the cert-manager issuer
8+
9+
Before you can configure the cert-manager plugin, you need to create an `Issuer` since the `Issuer` represents the CA and defines how certificates are issued.
10+
11+
.Prerequisites
12+
13+
* 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].
14+
15+
16+
.Procedure
17+
18+
You create a cert-manager `Issuer` by performing the following steps:
19+
20+
. Generate the Transport Layer Security (TLS) secret by running the following command:
21+
+
22+
[source,terminal]
23+
----
24+
$ oc create secret tls my-ca-key-pair-secret \
25+
--cert=path/to/your/ca.crt \
26+
--key=path/to/your/ca.key \
27+
--namespace=my-namespace
28+
----
29+
30+
. Create a YAML file that defines the `Issuer`, for example `ca-issuer.yaml`:
31+
+
32+
.Example `ca-issuer.yaml`
33+
+
34+
[source,yaml]
35+
----
36+
apiVersion: cert-manager.io/v1
37+
kind: Issuer
38+
metadata:
39+
name: my-ca-issuer
40+
namespace: my-namespace
41+
spec:
42+
ca:
43+
secretName: my-ca-key-pair-secret <1>
44+
----
45+
<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`.
46+
47+
. Apply the configuration by running the following command:
48+
+
49+
[source, terminal]
50+
----
51+
$ oc apply -f ca-issuer.yaml
52+
----
53+
54+
.Verification
55+
How would you verify if the issuer has been created????

‎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 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` 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 the 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 `UpstreamAuthority` 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 `AppRole` ID used for authentication.
114+
<3> the `AppRole` SecretID 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+
====

0 commit comments

Comments
 (0)