Skip to content

Commit 09afe91

Browse files
PreeticpPreeticp
authored
Merge pull request #39282 from DebarghoGhosh/new-update-sso-with-dex-keycloak
RHDEVDOCS-3358 - new content for dex and keycloak
2 parents d94ccf1 + 75fcbad commit 09afe91

11 files changed

+352
-2
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1486,8 +1486,10 @@ Topics:
14861486
File: configuring-an-openshift-cluster-by-deploying-an-application-with-cluster-configurations
14871487
- Name: Deploying a Spring Boot application with Argo CD
14881488
File: deploying-a-spring-boot-application-with-argo-cd
1489-
- Name: Configuring SSO for Argo CD on OpenShift
1490-
File: configuring-sso-for-argo-cd-on-openshift
1489+
- Name: Configuring SSO for Argo CD using Dex
1490+
File: configuring-sso-on-argo-cd-using-dex
1491+
- Name: Configuring SSO for Argo CD using Keycloak
1492+
File: configuring-sso-for-argo-cd-using-keycloak
14911493
---
14921494
Name: Images
14931495
Dir: openshift_images

‎cicd/gitops/configuring-sso-for-argo-cd-using-keycloak.adoc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[id="configuring-sso-for-argo-cd-using-keycloak"]
2+
= Configuring SSO for Argo CD using Keycloak
3+
include::modules/common-attributes.adoc[]
4+
include::modules/gitops-document-attributes.adoc[]
5+
:context: configuring-sso-for-argo-cd-using-keycloak
6+
7+
toc::[]
8+
9+
After the {gitops-title} Operator is installed, Argo CD automatically creates a user with `admin` permissions. To manage multiple users, cluster administrators can use Argo CD to configure Single Sign-On (SSO).
10+
11+
.Prerequisites
12+
* Red Hat SSO is installed on the cluster.
13+
* Argo CD is installed on the cluster.
14+
15+
include::modules/gitops-creating-a-new-client-using-keycloak.adoc[leveloffset=+1]
16+
17+
include::modules/gitops-logging-into-keycloak.adoc[leveloffset=+1]
18+
19+
include::modules/gitops-additional-steps-for-disconnected-clusters.adoc[leveloffset=+1]
20+
21+
include::modules/gitops-uninstall-keycloak.adoc[leveloffset=+1]
22+
23+
////
24+
.Additional resources
25+
* link:https://stedolan.github.io/jq/[`jq` command-line JSON processor documentation.]
26+
* link:https://argoproj.github.io/argo-cd/operator-manual/rbac/[Argo CD upstream documentation, RBAC Configuration section].
27+
////

‎cicd/gitops/configuring-sso-on-argo-cd-using-dex.adoc‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
[id="configuring-sso-for-argo-cd-using-dex"]
2+
= Configuring SSO for Argo CD using Dex
3+
include::modules/common-attributes.adoc[]
4+
include::modules/gitops-document-attributes.adoc[]
5+
:context: configuring-sso-for-argo-cd-using-dex
6+
7+
toc::[]
8+
9+
After the {gitops-title} Operator is installed, Argo CD automatically creates a user with `admin` permissions. To manage multiple users, cluster administrators can use Argo CD to configure Single Sign-On (SSO).
10+
11+
include::modules/gitops-creating-a-new-client-in-dex.adoc[leveloffset=+1]
12+
13+
include::modules/gitops-dex-role-mappings.adoc[leveloffset=+2]
14+
15+
//include::modules/gitops-configuring-argo-cd-using-dex-github-conector.adoc[leveloffset=+1]
16+
17+
include::modules/gitops-disable-dex.adoc[leveloffset=+1]
18+
19+
////
20+
.Additional resources
21+
* link:https://stedolan.github.io/jq/[`jq` command-line JSON processor documentation.]
22+
* link:https://argoproj.github.io/argo-cd/operator-manual/rbac/[Argo CD upstream documentation, RBAC Configuration section].
23+
////

‎modules/gitops-additional-steps-for-disconnected-clusters.adoc‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
[id="gitops-additional-steps-disconnected-clusters_{context}"]
2+
= Integrating Keycloak with the OpenShift OAuth server in a disconnected cluster
3+
4+
In a disconnected cluster, Keycloak communicates with the OpenShift OAuth server through a proxy.
5+
6+
.Procedure
7+
8+
Follow these steps to integrate Keycloak with the OpenShift OAuth server:
9+
10+
. Log in to the Keycloak pod:
11+
+
12+
[source,terminal]
13+
----
14+
$ oc exec -it dc/keycloak -n argocd -- /bin/bash
15+
----
16+
. Launch the JBoss CLI tool to set up the proxy mappings:
17+
+
18+
[source,terminal]
19+
----
20+
/opt/eap/bin/jboss-cli.sh
21+
----
22+
. In the JBoss CLI tool, run the following command to start an embedded standalone server:
23+
+
24+
[source,terminal]
25+
----
26+
embed-server --server-config=standalone-openshift.xml
27+
----
28+
. Set up proxy mappings for the OpenShift OAuth server host:
29+
+
30+
[source,terminal]
31+
----
32+
/subsystem=keycloak-server/spi=connectionsHttpClient/provider=default:write-attribute(name=properties.proxy-mappings,value=["<oauth-server-hostname>;http://<proxy-server-host>:<proxy-server-port>"])
33+
----
34+
. Stop the embedded server:
35+
+
36+
[source,terminal]
37+
----
38+
quit
39+
----
40+
. Reload the JBoss CLI tool to apply the proxy mappings:
41+
+
42+
[source,terminal]
43+
----
44+
/opt/eap/bin/jboss-cli.sh --connect --command=:reload
45+
----

‎modules/gitops-configuring-argo-cd-using-dex-github-conector.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
[id="gitops-configuring-argo-cd-using-dex-github-connector_{context}"]
2+
= Configuring Argo CD SSO using Dex GitHub connector
3+
4+
[discrete]
5+
.Procedure
6+
7+
. Register the application in the identity provider as explained link:https://argo-cd.readthedocs.io/en/stable/operator-manual/user-management/#1-register-the-application-in-the-identity-provider[here]
8+
. Update the Argo CD CR.
9+
. In the `dex.config` key, add the GitHub connector to the connectors sub field. See the link:https://github.com/dexidp/website/blob/main/content/docs/connectors/github.md[Dex GitHub connector documentation]. After adding the `clientID` and the `clientSecret` will be populated.
10+
. Optional: In the `connectors.config.orgs` list, add one or more GitHub organizations. Any member of the org will then be able to login to Argo CD to perform management tasks.
11+
+
12+
[source,yaml]
13+
----
14+
apiVersion: argoproj.io/v1alpha1
15+
kind: ArgoCD
16+
metadata:
17+
name: example-argocd
18+
labels:
19+
example: openshift-oauth
20+
spec:
21+
dex:
22+
config: |
23+
connectors:
24+
# GitHub example
25+
- type: github
26+
id: github
27+
name: GitHub
28+
config:
29+
clientID: xxxxxxxxxxxxxx
30+
clientSecret: $dex.github.clientSecret # Alternatively $<some_K8S_secret>:dex.github.clientSecret
31+
orgs:
32+
- name: dummy-org
33+
----

‎modules/gitops-creating-a-new-client-in-dex.adoc‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Module is included in the following assemblies:
2+
//
3+
// * configuring-sso-for-argo-cd-on-openshift
4+
[id="gitops-creating-a-new-client-in-dex_{context}"]
5+
= Enabling the Dex OpenShift OAuth Connector
6+
7+
Dex uses the users and groups defined within OpenShift by checking the `OAuth` server provided by the platform. The following example shows the properties of Dex along with example configurations:
8+
9+
[source,yaml]
10+
----
11+
apiVersion: argoproj.io/v1alpha1
12+
kind: ArgoCD
13+
metadata:
14+
name: example-argocd
15+
labels:
16+
example: openshift-oauth
17+
spec:
18+
dex:
19+
openShiftOAuth: true <1>
20+
groups:<2>
21+
- default
22+
rbac:<3>
23+
defaultPolicy: 'role:readonly'
24+
policy: |
25+
g, cluster-admins, role:admin
26+
scopes: '[groups]'
27+
----
28+
<1> The `openShiftOAuth` property triggers the Operator to automatically configure the built-in OpenShift `OAuth` server when the value is set to `true`.
29+
<2> The `groups` property assigns users to one group or all groups in the groups list.
30+
<3> The RBAC policy property assigns the admin role in the Argo CD cluster to users in the OpenShift `cluster-admins` group.

‎modules/gitops-creating-a-new-client-using-keycloak.adoc‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
[id="gitops-creating-a-new-client-in-keycloak_{context}"]
2+
= Configuring a new client in Keycloak
3+
4+
Dex is installed by default for all the Argo CD instances created by the Operator. However, you can delete the Dex configuration and add Keycloak instead to log in to Argo CD using your OpenShift credentials. Keycloak acts as an identity broker between Argo CD and OpenShift.
5+
6+
.Procedure
7+
8+
To configure Keycloak, follow these steps:
9+
10+
. Delete the Dex configuration by removing the following section from the Argo CD Custom Resource (CR), and save the CR:
11+
+
12+
[source,yaml]
13+
----
14+
dex:
15+
openShiftOAuth: true
16+
resources:
17+
limits:
18+
cpu:
19+
memory:
20+
requests:
21+
cpu:
22+
memory:
23+
----
24+
25+
. Configure Keycloak by editing the Argo CD CR, and updating the value for the `provider` parameter as `keycloak`. For example:
26+
+
27+
[source,yaml]
28+
----
29+
apiVersion: argoproj.io/v1alpha1
30+
kind: ArgoCD
31+
metadata:
32+
name: example-argocd
33+
labels:
34+
example: basic
35+
spec:
36+
sso:
37+
provider: keycloak
38+
server:
39+
route:
40+
enabled: true
41+
----
42+
43+
[NOTE]
44+
====
45+
The Keycloak instance takes 2-3 minutes to install and run.
46+
====
47+

‎modules/gitops-dex-role-mappings.adoc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Module is included in the following assemblies:
2+
//
3+
// * configuring-sso-for-argo-cd-on-openshift
4+
5+
[id="gitops-dex-role-mappings_{context}"]
6+
= Mapping users to specific roles
7+
8+
Argo CD cannot map users to specific roles if they have a direct `ClusterRoleBinding` role. You can manually change the role as `role:admin` on SSO through OpenShift.
9+
10+
.Procedure
11+
12+
. Create a group named `cluster-admins`.
13+
+
14+
[source,terminal]
15+
----
16+
$ oc adm groups new cluster-admins
17+
----
18+
. Add the user to the group.
19+
+
20+
[source,terminal]
21+
----
22+
$ oc adm groups add-users cluster-admins USER
23+
----
24+
. Apply the `cluster-admin` `ClusterRole` to the group:
25+
+
26+
[source,terminal]
27+
----
28+
$ oc adm policy add-cluster-role-to-group cluster-admin cluster-admins
29+
----

‎modules/gitops-disable-dex.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Module is included in the following assemblies:
2+
//
3+
// * configuring-sso-for-argo-cd-on-openshift
4+
5+
[id="gitops-disable-dex_{context}"]
6+
= Disabling Dex
7+
8+
Dex is installed by default for all the Argo CD instances created by the Operator. You can disable Dex.
9+
10+
.Procedure
11+
12+
* Set the environmental variable `DISABLE_DEX` to true in the *YAML* resource of the Operator:
13+
+
14+
[source,yaml]
15+
----
16+
spec:
17+
config:
18+
env:
19+
- name: DISABLE_DEX
20+
value: "true"
21+
----

‎modules/gitops-logging-into-keycloak.adoc‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
[id="gitops-logging-into-keycloak_{context}"]
2+
= Logging in to Keycloak
3+
4+
Log in to the Keycloak console to manage identities or roles and define the permissions assigned to the various roles.
5+
6+
.Prerequisites
7+
8+
* The default configuration of Dex is removed.
9+
* Your Argo CD CR must be configured to use the Keycloak SSO provider.
10+
11+
.Procedure
12+
13+
. Get the Keycloak route URL for login:
14+
+
15+
[source,terminal]
16+
----
17+
$ oc -n argocd get route keycloak
18+
19+
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
20+
keycloak keycloak-default.apps.ci-ln-******.origin-ci-int-aws.dev.**.com keycloak <all> reencrypt None
21+
----
22+
. Get the Keycloak pod name that stores the user name and password as environment variables:
23+
+
24+
[source,terminal]
25+
----
26+
$ oc -n argocd get pods
27+
28+
NAME READY STATUS RESTARTS AGE
29+
keycloak-1-2sjcl 1/1 Running 0 45m
30+
----
31+
.. Get the Keycloak user name:
32+
+
33+
[source,terminal]
34+
----
35+
$ oc -n argocd exec keycloak-1-2sjcl -- "env" | grep SSO_ADMIN_USERNAME
36+
37+
SSO_ADMIN_USERNAME=Cqid54Ih
38+
----
39+
.. Get the Keycloak password:
40+
+
41+
[source,terminal]
42+
----
43+
$ oc -n argocd exec keycloak-1-2sjcl -- "env" | grep SSO_ADMIN_PASSWORD
44+
45+
SSO_ADMIN_PASSWORD=GVXxHifH
46+
----
47+
. On the login page, click *LOG IN VIA KEYCLOAK*.
48+
+
49+
[NOTE]
50+
====
51+
You only see the option *LOGIN VIA KEYCLOAK* after the Keycloak instance is ready.
52+
====
53+
. Click *Login with OpenShift*.
54+
+
55+
[NOTE]
56+
====
57+
Login using `kubeadmin` is not supported.
58+
====
59+
+
60+
. Enter the OpenShift credentials to log in.
61+
. Optional: By default, any user logged in to Argo CD has read-only access. You can manage the user level access by updating the `argocd-rbac-cm` config map:
62+
+
63+
[source,yaml]
64+
----
65+
policy.csv:
66+
<name>, <email>, role:admin
67+
----
68+
69+
70+

0 commit comments

Comments
 (0)