Skip to content

Commit 446f788

Browse files
bergerhofferbergerhoffer
committed
OSDOCS#12643: Docs for BYO OIDC auth provider
1 parent 850cb4a commit 446f788

File tree

7 files changed

+576
-0
lines changed

7 files changed

+576
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1324,6 +1324,8 @@ Topics:
13241324
File: configuring-google-identity-provider
13251325
- Name: Configuring an OpenID Connect identity provider
13261326
File: configuring-oidc-identity-provider
1327+
- Name: Enabling direct authentication with an OIDC identity provider
1328+
File: external-auth
13271329
- Name: Using RBAC to define and apply permissions
13281330
File: using-rbac
13291331
- Name: Removing the kubeadmin user

‎authentication/external-auth.adoc

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="external-auth"]
3+
= Enabling direct authentication with an OIDC identity provider
4+
include::_attributes/common-attributes.adoc[]
5+
:context: external-auth
6+
7+
toc::[]
8+
9+
// TODO: Try to avoid back-to-back "You can"
10+
You can configure {product-title} to use an external OpenID Connect (OIDC) identity provider to issue tokens for authentication, replacing the built-in OpenShift OAuth server. While the built-in OpenShift OAuth server supports integration with a variety of identity providers, including external OIDC identity providers, it is limited to the capabilities of the OAuth server itself.
11+
12+
You can directly integrate external OIDC identity providers with {product-title} to facilitate machine-to-machine workflows, such as CLI, and provide additional capabilities that are not available when using the built-in OpenShift OAuth server.
13+
14+
:FeatureName: Direct authentication with an OIDC identity provider
15+
include::snippets/technology-preview.adoc[]
16+
17+
18+
19+
// About direct authentication with an OIDC identity provider
20+
include::modules/external-auth-about.adoc[leveloffset=+1]
21+
22+
// Direct authentication identity providers
23+
include::modules/external-auth-providers.adoc[leveloffset=+2]
24+
25+
// TODO: These prereqs here or in the module prereqs? Prob worth keeping this one both places.
26+
// Before or after about content?
27+
[id="prerequisites_{context}"]
28+
== Prerequisites
29+
30+
* Before replacing the built-in OAuth server with an external provider, ensure that you have access to a valid `kubeconfig` file.
31+
+
32+
[IMPORTANT]
33+
====
34+
If there are any issues with the external identity provider, you can use the `kubeconfig` file to gain access to the {product-title} cluster in an emergency situation.
35+
====
36+
37+
// Configuring an OIDC identity provider for direct authentication
38+
include::modules/external-auth-configuring.adoc[leveloffset=+1]
39+
40+
// OIDC provider configuration parameters
41+
include::modules/external-auth-fields.adoc[leveloffset=+2]
42+
43+
// TODO: Consider configs for keycloak and entra ID?
44+
45+
// Disabling a direct authentication OIDC identity provider
46+
include::modules/external-auth-disabling.adoc[leveloffset=+1]

‎modules/external-auth-about.adoc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/external-auth.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="external-auth-about_{context}"]
7+
// = About direct authentication for {product-title}
8+
9+
= About direct authentication with an OIDC identity provider
10+
11+
// TODO: title
12+
13+
TODO

‎modules/external-auth-configuring.adoc

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/external-auth.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="external-auth-configuring_{context}"]
7+
// = Configuring {product-title} to use an external authentication provider
8+
9+
= Configuring an OIDC identity provider for direct authentication
10+
11+
TODO: intro
12+
13+
:FeatureName: Direct authentication with an OIDC identity provider
14+
include::snippets/technology-preview.adoc[]
15+
16+
This example uses Keycloak as the identity provider, configured with a user named `user1`, who is a member of `group1`.
17+
18+
Or provide this as bullets:
19+
20+
* User called `user1` (does this matter?)
21+
* Group called `group1`, which `user1` as a member (does this matter?)
22+
* Clients for console and client
23+
* Creates a secret for console login / console client
24+
* Creates a config map to store the ca-bundle.crt
25+
26+
// TODO: check other test cases for any other use cases / things we need to document too
27+
28+
// TODO: Do we need to give any tips for configuring Keycloak?
29+
30+
.Prerequisites
31+
32+
* You have enabled the `TechnologyPreviewNoUpgrade` feature set.
33+
// TODO: Do we call this out? Do they have to do that whole thing, or can they do just the `ExternalOIDC` feature gate?
34+
* You have configured your external authentication provider. This procedure uses Keycloak as the identity provider.
35+
* You have access to a `kubeconfig` file for the cluster, to ensure that you still have access to the cluster in the case of an issue with the external authentication provider.
36+
* You have access to the cluster as a user with the `cluster-admin` role.
37+
+
38+
// TODO actually, we need to say to be logged in using the kubeconfig...
39+
40+
.Procedure
41+
42+
. Log in w/ kubeconfig (TODO: detail why).
43+
44+
. Create a secret (TODO: detail why) by running the following command:
45+
+
46+
[source,terminal]
47+
----
48+
$ oc create secret generic console-secret \ <1>
49+
--from-literal=clientSecret=<secret_value> \ <2>
50+
-n openshift-config
51+
----
52+
<1> TODO
53+
<2> Replace `<secret_value>` with the value of the secret for the client in Keycloak.
54+
+
55+
// TODO: Update callouts with comment syntax
56+
57+
. Extract (TODO: detail why) by running the following command:
58+
+
59+
[source,terminal]
60+
----
61+
$ oc extract cm/default-ingress-cert -n openshift-config-managed --to=router-ca
62+
----
63+
+
64+
// TODO: update router-ca example directory
65+
66+
. Create a config map (TODO: detail why) by running the following command:
67+
+
68+
[source,terminal]
69+
----
70+
$ oc create configmap keycloak-oidc-ca --from-file=ca-bundle.crt=router-ca/ca-bundle.crt \ <1>
71+
-n openshift-config
72+
----
73+
+
74+
// TODO: Update callouts with comment syntax
75+
76+
77+
78+
. Patch the authentication configuration:
79+
+
80+
// TODO: Patch or manually edit? Patch the authentication config - oc patch authentication.config/cluster --type=merge -p="
81+
+
82+
[source,yaml]
83+
----
84+
# ...
85+
spec:
86+
oidcProviders: <1>
87+
- claimMappings:
88+
groups:
89+
claim: groups <2>
90+
prefix: 'oidc-groups-test:'
91+
username:
92+
claim: email <3>
93+
prefixPolicy: Prefix
94+
prefix:
95+
prefixString: 'oidc-user-test:'
96+
issuer:
97+
audiences: <4>
98+
- console-test
99+
- oc-cli-test
100+
issuerCertificateAuthority:
101+
name: keycloak-oidc-ca <5>
102+
issuerURL: https://keycloak-keycloak.apps.example.com/realms/master <6>
103+
name: 'keycloak-oidc-server' <7>
104+
oidcClients:
105+
- clientID: oc-cli-test <8>
106+
componentName: cli
107+
componentNamespace: openshift-console
108+
- clientID: console-test <9>
109+
clientSecret:
110+
name: console-secret <10>
111+
componentName: console
112+
componentNamespace: openshift-console
113+
type: OIDC <11>
114+
webhookTokenAuthenticator: null <12>
115+
----
116+
<1> The OIDC provider configuration.
117+
<2> The name of the claim to construct group names for the cluster identity.
118+
<3> The name of the claim to construct usernames for the cluster identity.
119+
<4> The list of audience IDs that this authentication provider issues tokens for.
120+
<5> The name of the config map that contains the `ca-bundle.crt` key. If unset, system trust is used instead.
121+
<6> The URL for the token issuer.
122+
<7> The name for external OIDC provider.
123+
<8> The client ID that your provider uses for the {oc-first}.
124+
<9> The client ID that your provider uses for the {product-title} web console.
125+
<10> The name of the secret that stores the secret value for the console client.
126+
<11> A value of `OIDC` indicates to use an external OIDC identity provider.
127+
<12> Must be set to `null` when `type` is set to `OIDC`.
128+
+
129+
//TODO what does end of #5 mean? https://polarion.engineering.redhat.com/polarion/#/project/OSE/workitem?id=OCP-79807 - don't see the difference in config for issuerCertificateAuthority being unset
130+
+
131+
For the more details on all available parameters, see "OIDC provider configuration parameters".
132+
133+
.Verification
134+
135+
. Wait for the cluster to roll out new revisions to all nodes.
136+
137+
.. Check the Kubernetes API server Operator status by running the following command:
138+
+
139+
[source,terminal]
140+
----
141+
$ oc get co kube-apiserver
142+
----
143+
+
144+
.Example output
145+
[source,terminal]
146+
----
147+
NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE MESSAGE
148+
kube-apiserver 4.19.0 True True False 85m NodeInstallerProgressing: 2 node are at revision 8; 1 node is at revision 10
149+
----
150+
+
151+
The message in the above example shows that one node has progressed to the new revision and two nodes have not yet updated. It can take 30 minutes or more to roll out the new revision to all nodes, depending on the size of your cluster.
152+
153+
..
154+
155+
156+
Auth Operator
157+
158+
159+
Check kube-apiserver pods
160+
oc get po -n openshift-kube-apiserver -L revision -l apiserver
161+
162+
Can see the revisions there
163+
164+
Check auth operator
165+
oc get co authentication
166+
167+
Not sure what to check for here, but not sure if it’s necessary anyways
168+
169+
Check console cluster operator
170+
oc get co console
171+
172+
Not sure what to check for here, but not sure if it’s necessary anyways
173+
174+
Check console pods
175+
oc get po -n openshift-console
176+
177+
Assume looking for the pods age to be new
178+
179+
180+
TODO: I guess test logging in via CLI and console? Could take awhile for them to roll out though.

‎modules/external-auth-disabling.adoc

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * authentication/external-auth.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="external-auth-disabling_{context}"]
7+
// = Disabling a direct authentication OIDC identity provider
8+
9+
= Disabling direct authentication
10+
11+
.Prerequisites
12+
13+
// TODO: Sync these prereqs with the main one once that's complete
14+
* You have access to a `kubeconfig` file for the cluster, to ensure that you still have access to the cluster in the case of an issue with the external authentication provider.
15+
* You have access to the cluster as a user with the `cluster-admin` role.
16+
+
17+
// TODO actually, we need to say to be logged in using the kubeconfig...
18+
19+
.Procedure
20+
21+
* TODO

0 commit comments

Comments
 (0)