Skip to content

Commit eb74085

Browse files
bergerhofferbergerhoffer
authored
Merge pull request #93779 from bergerhoffer/OSDOCS-12643-oidc
OSDOCS#12643: Docs for BYO OIDC auth provider
2 parents ac0fecd + cc43aaf commit eb74085

8 files changed

+428
-2
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1318,6 +1318,8 @@ Topics:
13181318
File: configuring-google-identity-provider
13191319
- Name: Configuring an OpenID Connect identity provider
13201320
File: configuring-oidc-identity-provider
1321+
- Name: Enabling direct authentication with an OIDC identity provider
1322+
File: external-auth
13211323
- Name: Using RBAC to define and apply permissions
13221324
File: using-rbac
13231325
- Name: Removing the kubeadmin user

‎authentication/external-auth.adoc

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="external-auth"]
3+
= Enabling direct authentication with an external OIDC identity provider
4+
include::_attributes/common-attributes.adoc[]
5+
:context: external-auth
6+
7+
toc::[]
8+
9+
While the built-in OpenShift OAuth server supports integration with a variety of identity providers, including external OpenID Connect (OIDC) identity providers, it is limited to the capabilities of the OAuth server itself. You can configure {product-title} to use an external OIDC identity provider directly to issue tokens for authentication, which replaces the built-in OpenShift OAuth server.
10+
11+
:FeatureName: Direct authentication with an OIDC identity provider
12+
include::snippets/technology-preview.adoc[]
13+
14+
// About direct authentication with an external OIDC identity provider
15+
include::modules/external-auth-about.adoc[leveloffset=+1]
16+
17+
// Direct authentication identity providers
18+
include::modules/external-auth-providers.adoc[leveloffset=+2]
19+
20+
// Configuring an external OIDC identity provider for direct authentication
21+
include::modules/external-auth-configuring.adoc[leveloffset=+1]
22+
23+
// OIDC provider configuration parameters
24+
include::modules/external-auth-fields.adoc[leveloffset=+2]
25+
26+
// Disabling direct authentication
27+
include::modules/external-auth-disabling.adoc[leveloffset=+1]

‎modules/external-auth-about.adoc

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
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 with an external OIDC identity provider
8+
9+
You can enable direct integration with an external OpenID Connect (OIDC) identity provider to issue tokens for authentication. This bypasses the built-in OAuth server and uses the external identity provider directly.
10+
11+
By integrating directly with an external OIDC provider, you can leverage the advanced capabilities of your preferred OIDC provider instead of being limited by the capabilities of the built-in OAuth server. Your organization can manage users and groups from a single interface, while also streamlining authentication across multiple clusters and in hybrid environments. You can also integrate with existing tools and solutions.
12+
13+
// TODO: Add back in if we test machine-to-machine workflows in the future
14+
// You can also facilitate machine-to-machine workflows and integrate with existing tools and solutions.
15+
16+
[IMPORTANT]
17+
====
18+
Currently, you may configure only one OIDC provider for direct authentication.
19+
====
20+
21+
After switching to direct authentication, existing authentication configuration is not guaranteed to be preserved. Prior to enabling direct authentication, back up any existing user, group, oauthclient, or identity provider configuration in case you need to revert back to using the built-in OAuth server for authentication.
22+
23+
Before replacing the built-in OAuth server with an external provider, ensure that you have access to a long-lived method of logging in with cluster administrator permissions, such as one of the following:
24+
25+
* a certificate-based user `kubeconfig` file, such as the one generated by the installation program
26+
* a long-lived service account token `kubeconfig` file
27+
* a certificate-based service account `kubeconfig` file
28+
29+
If there are any issues with the external identity provider, you need one of these methods to gain access to the {product-title} cluster in an emergency situation.

‎modules/external-auth-configuring.adoc

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
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 an external OIDC identity provider for direct authentication
8+
9+
You can configure {product-title} to directly use an external OIDC identity provider to issue tokens for authentication.
10+
11+
:FeatureName: Direct authentication with an OIDC identity provider
12+
include::snippets/technology-preview.adoc[]
13+
14+
.Prerequisites
15+
16+
* You have enabled the `TechPreviewNoUpgrade` feature set.
17+
* You have configured your external authentication provider.
18+
+
19+
This procedure uses Keycloak as the identity provider and assumes that you have the following clients configured:
20+
21+
** A confidential client for the web console called `console-test` with the valid redirect URIs set to [x-]`https://<openshift_console_route>/auth/callback`
22+
23+
** A public client for the {oc-first} called `oc-cli-test` with the valid redirect URIs set to [x-]`http://localhost:8080`
24+
25+
* You have access to the `kubeconfig` file generated by the installation program for the cluster.
26+
* You have backed up any existing authentication configuration, in case you need to revert back to using the built-in OAuth server for authentication.
27+
28+
.Procedure
29+
30+
. Ensure that you are using the `kubeconfig` file generated by the installation program, or another long-lived method of logging in as a cluster administrator.
31+
32+
. Create a secret that allows you to authenticate with the web console by running the following command:
33+
+
34+
[source,terminal]
35+
----
36+
$ oc create secret generic console-secret \
37+
--from-literal=clientSecret=<secret_value> \// <1>
38+
-n openshift-config
39+
----
40+
<1> Replace `<secret_value>` with the value of the secret for the `console-test` client in your identity provider.
41+
42+
. Optional: Create a config map that contains the provider's certificate authority bundle by running the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ oc create configmap keycloak-oidc-ca --from-file=ca-bundle.crt=my-directory/ca-bundle.crt \// <1>
47+
-n openshift-config
48+
----
49+
<1> Specify the path to your provider's `ca-bundle.crt` file.
50+
51+
. Edit the authentication configuration by running the following command:
52+
+
53+
[source,terminal]
54+
----
55+
$ oc edit authentication.config/cluster
56+
----
57+
58+
. Update the authentication configuration by setting the `type` field to `OIDC`, configuring the `oidcProviders` field for your provider, and setting the `webhookTokenAuthenticator` field to `null`:
59+
+
60+
[source,yaml]
61+
----
62+
apiVersion: config.openshift.io/v1
63+
kind: Authentication
64+
metadata:
65+
# ...
66+
spec:
67+
oidcProviders: <1>
68+
- claimMappings:
69+
groups:
70+
claim: groups <2>
71+
prefix: 'oidc-groups-test:'
72+
username:
73+
claim: email <3>
74+
prefixPolicy: Prefix
75+
prefix:
76+
prefixString: 'oidc-user-test:'
77+
issuer:
78+
audiences: <4>
79+
- console-test
80+
- oc-cli-test
81+
issuerCertificateAuthority:
82+
name: keycloak-oidc-ca <5>
83+
issuerURL: https://keycloak-keycloak.apps.example.com/realms/master <6>
84+
name: 'keycloak-oidc-server' <7>
85+
oidcClients:
86+
- clientID: oc-cli-test <8>
87+
componentName: cli
88+
componentNamespace: openshift-console
89+
- clientID: console-test <9>
90+
clientSecret:
91+
name: console-secret <10>
92+
componentName: console
93+
componentNamespace: openshift-console
94+
type: OIDC <11>
95+
webhookTokenAuthenticator: null <12>
96+
----
97+
<1> The OIDC provider configuration. Currently, only one OIDC provider configuration is allowed.
98+
<2> The name of the claim to construct group names for the cluster identity.
99+
<3> The name of the claim to construct usernames for the cluster identity.
100+
<4> The list of audiences that this authentication provider issues tokens for.
101+
<5> The name of the config map that contains the `ca-bundle.crt` key. If unset, system trust is used instead.
102+
<6> The URL for the token issuer.
103+
<7> The name for external OIDC provider.
104+
<8> The client ID that your provider uses for the {oc-first}.
105+
<9> The client ID that your provider uses for the {product-title} web console.
106+
<10> The name of the secret that stores the secret value for the console client.
107+
<11> Must be set to `OIDC` to indicate to use an external OIDC identity provider.
108+
<12> Must be set to `null` when `type` is set to `OIDC`.
109+
+
110+
For more details on all available parameters, see "OIDC provider configuration parameters".
111+
112+
. Exit and save the changes to apply the new configuration.
113+
114+
. Wait for the cluster to roll out new revisions to all nodes.
115+
116+
.. Check the Kubernetes API server Operator status by running the following command:
117+
+
118+
[source,terminal]
119+
----
120+
$ oc get co kube-apiserver
121+
----
122+
+
123+
.Example output
124+
[source,terminal]
125+
----
126+
NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE MESSAGE
127+
kube-apiserver 4.19.0 True True False 85m NodeInstallerProgressing: 2 node are at revision 8; 1 node is at revision 10
128+
----
129+
+
130+
The message in the preceding example shows that one node has progressed to the new revision and two nodes have not yet updated. It can take 20 minutes or more to roll out the new revision to all nodes, depending on the size of your cluster.
131+
132+
.. To troubleshoot any issues, you can also check the Cluster Authentication Operator and `kube-apiserver` pod logs for errors.
133+
134+
.Verification
135+
136+
. Verify that you can log in to the {oc-first} by authenticating with your identity provider:
137+
138+
.. Log in by running the following command:
139+
+
140+
[source,terminal]
141+
----
142+
$ oc login --exec-plugin=oc-oidc \// <1>
143+
--issuer-url=https://keycloak-keycloak.apps.example.com/realms/master \// <2>
144+
--client-id=oc-cli-test \// <3>
145+
--extra-scopes=email --callback-port=8080 \
146+
--oidc-certificate-authority my-directory/ca-bundle.crt <4>
147+
----
148+
<1> Specify `oc-oidc` as the exec plugin type. Only a value of `oc-oidc` is allowed.
149+
<2> Specify the issuer URL for your identity provider.
150+
<3> Specify client ID for the {oc-first}.
151+
<4> Specify the path to the `ca-bundle.crt` file on your local machine.
152+
+
153+
.Example output
154+
[source,terminal]
155+
----
156+
Please visit the following URL in your browser: http://localhost:8080
157+
----
158+
159+
.. Open http://localhost:8080 in a browser.
160+
161+
.. Authenticate with credentials from your identity provider.
162+
+
163+
After successfully authenticating, you should see a message similar to the following output in your terminal:
164+
+
165+
[source,terminal]
166+
----
167+
Logged into "https://api.my-cluster.example.com:6443" as "oidc-user-test:user1@example.com" from an external oidc issuer.
168+
----
169+
170+
. Verify that you can log in to the {product-title} web console by authenticating with your identity provider:
171+
172+
.. Open the web console URL for your cluster in a browser.
173+
+
174+
You are redirected to your identity provider to log in.
175+
176+
.. Authenticate with credentials from your identity provider.
177+
+
178+
Verify that you logged in successfully and are redirected to the {product-title} web console.

‎modules/external-auth-disabling.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+
// * authentication/external-auth.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="external-auth-disabling_{context}"]
7+
= Disabling direct authentication
8+
9+
If necessary, you can disable direct authentication for your cluster and revert back to authenticating with the built-in OpenShift OAuth server.
10+
11+
.Prerequisites
12+
13+
* You have access to the `kubeconfig` file generated by the installation program for the cluster.
14+
15+
.Procedure
16+
17+
. Ensure that you are using the `kubeconfig` file generated by the installation program, or another long-lived method of logging in as a cluster administrator.
18+
19+
. Update the authentication configuration to use the built-in OpenShift OAuth server by running the following command:
20+
+
21+
[source,terminal]
22+
----
23+
$ oc patch authentication.config/cluster --type=merge -p='
24+
spec:
25+
type: "" <1>
26+
oidcProviders: null <2>
27+
'
28+
----
29+
<1> Sets `type` to `""` to use the built-in OpenShift OAuth server. A value of `IntegratedOAuth` is also equivalent.
30+
<2> Removes the `oidcProviders` configuration.
31+
32+
. Wait for the cluster to roll out new revisions to all nodes.
33+
34+
.. Check the Kubernetes API server Operator status by running the following command:
35+
+
36+
[source,terminal]
37+
----
38+
$ oc get co kube-apiserver
39+
----
40+
+
41+
.Example output
42+
[source,terminal]
43+
----
44+
NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE MESSAGE
45+
kube-apiserver 4.19.0 True True False 85m NodeInstallerProgressing: 2 node are at revision 12; 1 node is at revision 14
46+
----
47+
+
48+
The message in the preceding example shows that one node has progressed to the new revision and two nodes have not yet updated. It can take 20 minutes or more to roll out the new revision to all nodes, depending on the size of your cluster.
49+
50+
.. To troubleshoot any issues, you can also check the Cluster Authentication Operator and `kube-apiserver` pod logs for errors.
51+
52+
. If necessary, restore any existing authentication configuration.
53+
54+
.Verification
55+
56+
* Verify that you can successfully log in to the {product-title} web console and {oc-first}.

0 commit comments

Comments
 (0)