openshift · Preeticp · Dec 22, 2021 · Nov 26, 2021
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -1480,8 +1480,10 @@ Topics:
         File: configuring-an-openshift-cluster-by-deploying-an-application-with-cluster-configurations
       - Name: Deploying a Spring Boot application with Argo CD
         File: deploying-a-spring-boot-application-with-argo-cd
-  - Name: Configuring SSO for Argo CD on OpenShift
-    File: configuring-sso-for-argo-cd-on-openshift
+  - Name: Configuring SSO for Argo CD using Dex
+    File: configuring-sso-on-argo-cd-using-dex
+  - Name: Configuring SSO for Argo CD using Keycloak
+    File: configuring-sso-for-argo-cd-using-keycloak
 ---
 Name: Images
 Dir: openshift_images

diff --git a/cicd/gitops/configuring-sso-for-argo-cd-using-keycloak.adoc b/cicd/gitops/configuring-sso-for-argo-cd-using-keycloak.adoc
@@ -0,0 +1,27 @@
+[id="configuring-sso-for-argo-cd-using-keycloak"]
+= Configuring SSO for Argo CD using Keycloak
+include::modules/common-attributes.adoc[]
+include::modules/gitops-document-attributes.adoc[]
+:context: configuring-sso-for-argo-cd-using-keycloak
+
+toc::[]
+
+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).
+
+.Prerequisites
+* Red Hat SSO is installed on the cluster.
+* Argo CD is installed on the cluster. 
+
+include::modules/gitops-creating-a-new-client-using-keycloak.adoc[leveloffset=+1]
+
+include::modules/gitops-logging-into-keycloak.adoc[leveloffset=+1]
+
+include::modules/gitops-additional-steps-for-disconnected-clusters.adoc[leveloffset=+1]
+
+include::modules/gitops-uninstall-keycloak.adoc[leveloffset=+1]
+
+////
+.Additional resources
+* link:https://stedolan.github.io/jq/[`jq` command-line JSON processor documentation.]
+* link:https://argoproj.github.io/argo-cd/operator-manual/rbac/[Argo CD upstream documentation, RBAC Configuration section].
+////
diff --git a/cicd/gitops/configuring-sso-on-argo-cd-using-dex.adoc b/cicd/gitops/configuring-sso-on-argo-cd-using-dex.adoc
@@ -0,0 +1,23 @@
+[id="configuring-sso-for-argo-cd-using-dex"]
+= Configuring SSO for Argo CD using Dex
+include::modules/common-attributes.adoc[]
+include::modules/gitops-document-attributes.adoc[]
+:context: configuring-sso-for-argo-cd-using-dex
+
+toc::[]
+
+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).
+
+include::modules/gitops-creating-a-new-client-in-dex.adoc[leveloffset=+1]
+
+include::modules/gitops-dex-role-mappings.adoc[leveloffset=+2]
+
+//include::modules/gitops-configuring-argo-cd-using-dex-github-conector.adoc[leveloffset=+1]
+
+include::modules/gitops-disable-dex.adoc[leveloffset=+1]
+
+////
+.Additional resources
+* link:https://stedolan.github.io/jq/[`jq` command-line JSON processor documentation.]
+* link:https://argoproj.github.io/argo-cd/operator-manual/rbac/[Argo CD upstream documentation, RBAC Configuration section].
+////
diff --git a/modules/gitops-additional-steps-for-disconnected-clusters.adoc b/modules/gitops-additional-steps-for-disconnected-clusters.adoc
@@ -0,0 +1,45 @@
+[id="gitops-additional-steps-disconnected-clusters_{context}"]
+= Integrating Keycloak with the OpenShift OAuth server in a disconnected cluster
+
+In a disconnected cluster, Keycloak communicates with the OpenShift OAuth server through a proxy. 
+
+.Procedure
+
+Follow these steps to integrate Keycloak with the OpenShift OAuth server:
+
+. Log in to the Keycloak pod:
++
+[source,terminal]
+----
+$ oc exec -it dc/keycloak -n argocd -- /bin/bash
+----
+. Launch the JBoss CLI tool to set up the proxy mappings:
++
+[source,terminal]
+----
+/opt/eap/bin/jboss-cli.sh
+----
+. In the JBoss CLI tool, run the following command to start an embedded standalone server:
++
+[source,terminal]
+----
+embed-server --server-config=standalone-openshift.xml
+----
+. Set up proxy mappings for the OpenShift OAuth server host:
++
+[source,terminal]
+----
+/subsystem=keycloak-server/spi=connectionsHttpClient/provider=default:write-attribute(name=properties.proxy-mappings,value=["<oauth-server-hostname>;http://<proxy-server-host>:<proxy-server-port>"])
+----
+. Stop the embedded server:
++
+[source,terminal]
+----
+quit
+----
+. Reload the JBoss CLI tool to apply the proxy mappings:
++
+[source,terminal]
+----
+/opt/eap/bin/jboss-cli.sh --connect --command=:reload
+----
diff --git a/modules/gitops-configuring-argo-cd-using-dex-github-conector.adoc b/modules/gitops-configuring-argo-cd-using-dex-github-conector.adoc
@@ -0,0 +1,33 @@
+[id="gitops-configuring-argo-cd-using-dex-github-connector_{context}"]
+= Configuring Argo CD SSO using Dex GitHub connector
+
+[discrete]
+.Procedure
+
+. 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]
+. Update the Argo CD CR.
+. 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.
+. 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.
++
+[source,yaml]
+----
+  apiVersion: argoproj.io/v1alpha1
+kind: ArgoCD
+metadata:
+  name: example-argocd
+  labels:
+    example: openshift-oauth
+spec:
+  dex:
+    config: |
+      connectors:
+        # GitHub example
+        - type: github
+          id: github
+          name: GitHub
+          config:
+            clientID: xxxxxxxxxxxxxx
+            clientSecret: $dex.github.clientSecret # Alternatively $<some_K8S_secret>:dex.github.clientSecret
+            orgs:
+            - name: dummy-org
+----
diff --git a/modules/gitops-creating-a-new-client-in-dex.adoc b/modules/gitops-creating-a-new-client-in-dex.adoc
@@ -0,0 +1,30 @@
+// Module is included in the following assemblies:
+//
+// * configuring-sso-for-argo-cd-on-openshift
+[id="gitops-creating-a-new-client-in-dex_{context}"]
+= Enabling the Dex OpenShift OAuth Connector
+
+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:
+
+[source,yaml]
+----
+apiVersion: argoproj.io/v1alpha1
+kind: ArgoCD
+metadata:
+  name: example-argocd
+  labels:
+    example: openshift-oauth
+spec:
+  dex:
+    openShiftOAuth: true <1>
+    groups:<2>
+     - default
+  rbac:<3>
+    defaultPolicy: 'role:readonly'
+    policy: |
+      g, cluster-admins, role:admin
+    scopes: '[groups]'
+----
+<1> The `openShiftOAuth` property triggers the Operator to automatically configure the built-in OpenShift `OAuth` server when the value is set to `true`.
+<2> The `groups` property assigns users to one group or all groups in the groups list.
+<3> The RBAC policy property assigns the admin role in the Argo CD cluster to users in the OpenShift `cluster-admins` group.
diff --git a/modules/gitops-creating-a-new-client-using-keycloak.adoc b/modules/gitops-creating-a-new-client-using-keycloak.adoc
@@ -0,0 +1,47 @@
+[id="gitops-creating-a-new-client-in-keycloak_{context}"]
+= Configuring a new client in Keycloak
+
+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.
+
+.Procedure
+
+To configure Keycloak, follow these steps:
+
+. Delete the Dex configuration by removing the following section from the Argo CD Custom Resource (CR), and save the CR: 
++
+[source,yaml]
+----
+dex:
+    openShiftOAuth: true
+    resources:
+      limits:
+        cpu: 
+        memory: 
+      requests:
+        cpu: 
+        memory: 
+----
+
+. Configure Keycloak by editing the Argo CD CR, and updating the value for the `provider` parameter as `keycloak`. For example:
++
+[source,yaml]
+----
+apiVersion: argoproj.io/v1alpha1
+kind: ArgoCD
+metadata:
+  name: example-argocd
+  labels:
+    example: basic
+spec:
+  sso:
+    provider: keycloak
+  server:
+    route:
+     enabled: true
+----
+
+[NOTE]
+====
+The Keycloak instance takes 2-3 minutes to install and run.
+====
+
diff --git a/modules/gitops-dex-role-mappings.adoc b/modules/gitops-dex-role-mappings.adoc
@@ -0,0 +1,29 @@
+// Module is included in the following assemblies:
+//
+// * configuring-sso-for-argo-cd-on-openshift
+
+[id="gitops-dex-role-mappings_{context}"]
+= Mapping users to specific roles
+
+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.
+
+.Procedure
+
+. Create a group named `cluster-admins`.
++
+[source,terminal]
+----
+$ oc adm groups new cluster-admins
+----
+. Add the user to the group.
++
+[source,terminal]
+----
+$ oc adm groups add-users cluster-admins USER
+----
+. Apply the `cluster-admin` `ClusterRole` to the group:
++
+[source,terminal]
+----
+$ oc adm policy add-cluster-role-to-group cluster-admin cluster-admins
+----
diff --git a/modules/gitops-disable-dex.adoc b/modules/gitops-disable-dex.adoc
@@ -0,0 +1,21 @@
+// Module is included in the following assemblies:
+//
+// * configuring-sso-for-argo-cd-on-openshift
+
+[id="gitops-disable-dex_{context}"]
+= Disabling Dex
+
+Dex is installed by default for all the Argo CD instances created by the Operator. You can disable Dex.
+
+.Procedure
+
+* Set the environmental variable `DISABLE_DEX` to true in the *YAML* resource of the Operator:
++
+[source,yaml]
+----
+  spec:
+  config:
+    env:
+    - name: DISABLE_DEX
+      value: "true"
+----
diff --git a/modules/gitops-logging-into-keycloak.adoc b/modules/gitops-logging-into-keycloak.adoc
@@ -0,0 +1,70 @@
+[id="gitops-logging-into-keycloak_{context}"]
+= Logging in to Keycloak
+
+Log in to the Keycloak console to manage identities or roles and define the permissions assigned to the various roles.
+
+.Prerequisites
+
+* The default configuration of Dex is removed.
+* Your Argo CD CR must be configured to use the Keycloak SSO provider.
+
+.Procedure
+
+. Get the Keycloak route URL for login:
++
+[source,terminal]
+----
+$ oc -n argocd get route keycloak
+
+NAME        HOST/PORT                                                        PATH   SERVICES   PORT    TERMINATION   WILDCARD
+keycloak    keycloak-default.apps.ci-ln-******.origin-ci-int-aws.dev.**.com         keycloak   <all>    reencrypt     None
+----
+. Get the Keycloak pod name that stores the user name and password as environment variables:
++
+[source,terminal]
+----
+$ oc -n argocd get pods
+
+NAME                      READY   STATUS           RESTARTS   AGE
+keycloak-1-2sjcl           1/1    Running            0        45m
+----
+.. Get the Keycloak user name:
++
+[source,terminal]
+----
+$ oc -n argocd exec keycloak-1-2sjcl -- "env" | grep SSO_ADMIN_USERNAME
+
+SSO_ADMIN_USERNAME=Cqid54Ih
+----
+.. Get the Keycloak password:
++
+[source,terminal]
+----
+$ oc -n argocd exec keycloak-1-2sjcl -- "env" | grep SSO_ADMIN_PASSWORD
+
+SSO_ADMIN_PASSWORD=GVXxHifH
+----
+. On the login page, click *LOG IN VIA KEYCLOAK*.
++
+[NOTE]
+====
+You only see the option *LOGIN VIA KEYCLOAK* after the Keycloak instance is ready.
+====
+. Click *Login with OpenShift*.
++
+[NOTE]
+====
+Login using `kubeadmin` is not supported.
+====
++
+. Enter the OpenShift credentials to log in.
+. 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:
++
+[source,yaml]
+----
+policy.csv:
+<name>, <email>, role:admin
+----
+
+
+
diff --git a/modules/gitops-uninstall-keycloak.adoc b/modules/gitops-uninstall-keycloak.adoc
@@ -0,0 +1,23 @@
+[id="gitops-uninstalling-keycloak_{context}"]
+= Uninstalling Keycloak
+
+You can delete the Keycloak resources and their relevant configurations by removing the `SSO` field from the Argo CD Custom Resource (CR) file. After you remove the `SSO` field, the values in the file look similar to the following:
+
+[source,yaml]
+----
+  apiVersion: argoproj.io/v1alpha1
+  kind: ArgoCD
+  metadata:
+    name: example-argocd
+    labels:
+      example: basic
+  spec:
+    server:
+      route:
+       enabled: true
+----
+
+[NOTE]
+====
+A Keycloak application created by using this method is currently not persistent. Additional configurations created in the Argo CD Keycloak realm are deleted when the server restarts.
+====