Skip to content

Commit d0a5c00

Browse files
tolushagtrivedi88
tolusha
and
gtrivedi88
authored
feat: Support OpenShift external IDP (#3024)
* feat: Support OpenShift external IDP Signed-off-by: Anatolii Bazko <abazko@redhat.com> * fixup Signed-off-by: Anatolii Bazko <abazko@redhat.com> * fixes Signed-off-by: Anatolii Bazko <abazko@redhat.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * Update modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com> * fixes Signed-off-by: Anatolii Bazko <abazko@redhat.com> * fixes Signed-off-by: Anatolii Bazko <abazko@redhat.com> * fixes Signed-off-by: Anatolii Bazko <abazko@redhat.com> * fixes Signed-off-by: Anatolii Bazko <abazko@redhat.com> --------- Signed-off-by: Anatolii Bazko <abazko@redhat.com> Co-authored-by: Gaurav Trivedi <90042568+gtrivedi88@users.noreply.github.com>
1 parent fb82363 commit d0a5c00

5 files changed

Lines changed: 239 additions & 2 deletions

File tree

‎antora.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,7 @@ asciidoc:
3131
devworkspace-id: devworkspace
3232
docker-cli: docker
3333
hosted-che-docs: xref:hosted-che:hosted-che.adoc[]
34-
identity-provider-legacy-id: keycloak
35-
identity-provider-legacy: Keycloak
34+
keycloak: Keycloak
3635
image-puller-cr-name: KubernetesImagePuller
3736
image-puller-deployment-id: kubernetes-image-puller-operator
3837
image-puller-deployment-name: kubernetes-image-puller

‎modules/administration-guide/examples/snip_che-installing-che.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ You can deploy only one instance of {prod-short} per cluster.
1212

1313
* xref:installing-che-on-openshift-using-cli.adoc[]
1414
* xref:installing-che-on-openshift-using-the-web-console.adoc[]
15+
* xref:installing-che-on-openshift-with-keycloak-as-oidc.adoc[]
1516
* xref:installing-che-in-a-restricted-environment.adoc[]
1617
* xref:installing-che-on-microsoft-azure.adoc[]
1718
* xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[]

‎modules/administration-guide/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
** xref:installing-che-in-the-cloud.adoc[]
2222
*** xref:installing-che-on-openshift-using-cli.adoc[]
2323
*** xref:installing-che-on-openshift-using-the-web-console.adoc[]
24+
*** xref:installing-che-on-openshift-with-keycloak-as-oidc.adoc[]
2425
*** xref:installing-che-in-a-restricted-environment.adoc[]
2526
*** xref:installing-che-on-microsoft-azure.adoc[]
2627
*** xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[]

‎modules/administration-guide/pages/installing-che-in-the-cloud.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ Follow the instructions below to start the {prod-short} Server in the cloud by u
2020

2121
* xref:installing-che-on-openshift-using-cli.adoc[]
2222
* xref:installing-che-on-openshift-using-the-web-console.adoc[]
23+
* xref:installing-che-on-openshift-with-keycloak-as-oidc.adoc[]
2324
* xref:installing-che-in-a-restricted-environment.adoc[]
2425
* xref:installing-che-on-microsoft-azure.adoc[]
2526
* xref:installing-che-on-amazon-elastic-kubernetes-service.adoc[]

‎modules/administration-guide/pages/installing-che-on-openshift-with-keycloak-as-oidc.adoc‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
:_content-type: PROCEDURE
2+
:description: Installing {prod-short} on Red Hat OpenShift with {keycloak} as external identity provider
3+
:keywords: overview, installing, openshift, keycloak, oidc
4+
:navtitle: Installing {prod-short} on OpenShift with {keycloak} as external identity provider
5+
6+
7+
[id="installing-che-on-openshift-with-keycloak-as-oidc"]
8+
= Install {prod-short} on OpenShift with {keycloak} as external identity provider
9+
10+
Install {prod-short} on an OpenShift cluster that uses {keycloak} as an external OIDC identity provider for centralized user authentication.
11+
12+
.Prerequisites
13+
14+
* An active `{orch-cli}` session with administrative permissions to the OpenShift cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI].
15+
16+
* {keycloak} is configured as an external identity provider for OpenShift. See link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html/authentication_and_authorization/external-auth[Enabling direct authentication with an external OIDC identity provider].
17+
18+
.Procedure
19+
20+
. Define the environment variables:
21+
+
22+
[source,shell,subs="+quotes,+attributes"]
23+
----
24+
# The {keycloak} namespace:
25+
KEYCLOAK_NAMESPACE=__<KEYCLOAK_NAMESPACE>__
26+
27+
# The {keycloak} realm used for OpenShift authentication:
28+
OPENSHIFT_REALM=<REALM>
29+
30+
# The {keycloak} URL
31+
KEYCLOAK_URL=https://$({orch-cli} get route keycloak -n $KEYCLOAK_NAMESPACE --template='{{ .spec.host }}')
32+
----
33+
34+
. Create a `{prod-id}` client in the {keycloak} Admin Console:
35+
+
36+
--
37+
.. Within the realm used for OpenShift authentication, select *Clients* on the left side of the navigation bar.
38+
.. Select the *Create client* button.
39+
.. On the *General Settings* page:
40+
+
41+
... Enter `{prod-id}` in the *Client ID* field.
42+
... Optional: Enter a *Name* and *Description* for the OAuth client.
43+
... Click *Next*.
44+
.. On the *Capability config* page:
45+
+
46+
... Toggle *Client authentication* to *On*.
47+
... Click *Next*.
48+
... Click *Save*.
49+
50+
.. Navigate to the *Credentials* tab of the newly created client and copy the *Client secret* value for use when applying the OAuth client secret.
51+
--
52+
53+
. Add the `{prod-id}` client to the audiences list in the OpenShift authentication configuration:
54+
+
55+
[source,shell,subs="+quotes,+attributes"]
56+
----
57+
{orch-cli} patch authentication.config/cluster \
58+
--type='json' \
59+
-p='[
60+
{
61+
"op": "add",
62+
"path": "/spec/oidcProviders/0/issuer/audiences/-",
63+
"value": "{prod-id}"
64+
}
65+
]'
66+
----
67+
+
68+
[NOTE]
69+
====
70+
If you have multiple OIDC providers configured, adjust the array index in the path
71+
(currently 0) to match your {keycloak} provider's position in the configuration.
72+
====
73+
74+
. Wait for the `kube-apiserver` cluster operator to roll out the configuration changes:
75+
+
76+
[source,shell,subs="+quotes,+attributes"]
77+
----
78+
watch {orch-cli} get co kube-apiserver
79+
----
80+
81+
. Create a {orch-namespace} for {prod-short}:
82+
+
83+
[source,bash,subs="+quotes,+attributes"]
84+
----
85+
{orch-cli} create {orch-namespace} {prod-namespace}
86+
----
87+
88+
. Create a secret for the OAuth client in the {prod-short} namespace:
89+
+
90+
[source,yaml,subs="+quotes,+attributes"]
91+
----
92+
{orch-cli} apply -f - <<EOF
93+
apiVersion: v1
94+
kind: Secret
95+
metadata:
96+
name: oauth-secret
97+
namespace: {prod-namespace}
98+
labels:
99+
app.kubernetes.io/part-of: che.eclipse.org
100+
stringData:
101+
oAuthSecret: __<CLIENT_SECRET>__ <1>
102+
EOF
103+
----
104+
<1> The client secret value from the `{prod-id}` client in {keycloak}.
105+
106+
107+
. Optional: Create the `ConfigMap` with a {keycloak} certificate in the `{prod-namespace}` namespace. If {keycloak} uses a certificate that is already trusted by OpenShift, skip this step.
108+
+
109+
[source,shell,subs="+attributes"]
110+
----
111+
openssl s_client \
112+
-connect "$(echo "$KEYCLOAK_URL" | sed 's|https://||'):443" \
113+
-showcerts < /dev/null \
114+
| sed -n '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p' \
115+
> keycloak-ca.crt
116+
117+
{orch-cli} create configmap keycloak-certs \
118+
--from-file=keycloak-ca.crt=keycloak-ca.crt \
119+
-n {prod-namespace} && \
120+
{orch-cli} label configmap keycloak-certs \
121+
app.kubernetes.io/part-of=che.eclipse.org \
122+
app.kubernetes.io/component=ca-bundle \
123+
-n {prod-namespace}
124+
----
125+
126+
. Prepare the `CheCluster` patch:
127+
+
128+
[source,shell,subs="+attributes"]
129+
----
130+
cat > che-patch.yaml << EOF
131+
kind: CheCluster
132+
apiVersion: org.eclipse.che/v2
133+
spec:
134+
networking:
135+
auth:
136+
oAuthClientName: {prod-id}
137+
oAuthSecret: oauth-secret
138+
identityProviderURL: "$KEYCLOAK_URL/realms/$OPENSHIFT_REALM"
139+
gateway:
140+
oAuthProxy:
141+
cookieExpireSeconds: 300
142+
deployment:
143+
containers:
144+
- name: oauth-proxy
145+
env:
146+
- name: OAUTH2_PROXY_CODE_CHALLENGE_METHOD
147+
value: S256
148+
- name: OAUTH2_PROXY_BACKEND_LOGOUT_URL
149+
value: "$KEYCLOAK_URL/realms/$OPENSHIFT_REALM/protocol/openid-connect/logout?id_token_hint=\{id_token}"
150+
components:
151+
cheServer:
152+
extraProperties:
153+
CHE_OIDC_GROUPS__CLAIM: '<GROUPS_CLAIM>' <1>
154+
CHE_OIDC_GROUPS__PREFIX: '<GROUPS_PREFIX>' <2>
155+
CHE_OIDC_USERNAME__CLAIM: '<USERNAME_CLAIM>' <3>
156+
CHE_OIDC_USERNAME__PREFIX: '<USERNAME_PREFIX>' <4>
157+
EOF
158+
----
159+
<1> The claim to use for extracting user groups.
160+
<2> The prefix to add to group names. Empty string means no prefix.
161+
<3> The claim to use for extracting the username.
162+
<4> The prefix to add to usernames from the external authentication system.
163+
+
164+
[NOTE]
165+
====
166+
These values must match the corresponding claim and prefix settings configured in the `authentication.config/cluster` resource. To view the current cluster configuration, run:
167+
168+
[source,shell,subs="+attributes"]
169+
----
170+
{orch-cli} get authentication.config/cluster -o yaml
171+
----
172+
====
173+
+
174+
. Create the {prod-short} instance with `{prod-cli}`:
175+
+
176+
[source,shell,subs="+attributes"]
177+
----
178+
{prod-cli} server:deploy \
179+
--platform openshift \
180+
--che-operator-cr-patch-yaml che-patch.yaml
181+
----
182+
183+
. Update a `{prod-id}` client to set {prod-short} callback URL:
184+
+
185+
--
186+
.. Open the {keycloak} Admin Console.
187+
.. Within the realm used for OpenShift authentication, click the `{prod-id}` client.
188+
... In the *Valid redirect URIs* field, enter the redirect URI for your {prod-short} installation. To obtain the redirect URI, run the following command:
189+
+
190+
[source,shell,subs="+quotes,+attributes"]
191+
----
192+
echo "$({orch-cli} get checluster {prod-checluster} -n {prod-namespace} -o jsonpath='{.status.cheURL}')/oauth/callback"
193+
----
194+
... Click *Save*.
195+
--
196+
197+
. Create a `ClusterRoleBinding` to grant users access to {prod-short}:
198+
+
199+
[source,shell,subs="+quotes,+attributes"]
200+
----
201+
{orch-cli} apply -f - <<EOF
202+
apiVersion: rbac.authorization.k8s.io/v1
203+
kind: ClusterRoleBinding
204+
metadata:
205+
name: openshift-developers
206+
roleRef:
207+
apiGroup: rbac.authorization.k8s.io
208+
kind: ClusterRole
209+
name: self-provisioner <1>
210+
subjects:
211+
- apiGroup: rbac.authorization.k8s.io
212+
kind: Group
213+
name: __<GROUP_NAME>__ <2>
214+
EOF
215+
----
216+
<1> Users must have at least the `self-provisioner` role to access {prod-short}.
217+
<2> The name of the user group from {keycloak} that should be granted access to {prod-short}.
218+
219+
.Verification
220+
221+
. Verify the {prod-short} instance status:
222+
+
223+
[source,shell,subs="+attributes"]
224+
----
225+
{prod-cli} server:status
226+
----
227+
228+
. Navigate to the {prod-short} cluster instance:
229+
+
230+
[source,shell,subs="+attributes"]
231+
----
232+
{prod-cli} dashboard:open
233+
----
234+
235+
. Log in to the {prod-short} instance.

0 commit comments

Comments
 (0)