Merge pull request #55 from appuio/reordering

Reorder how-to pages
appuio · Oct 26, 2021 · 9ff0eee · 9ff0eee
2 parents cb479de + 3295e1f
commit 9ff0eee
Show file tree

Hide file tree

Showing 6 changed files with 120 additions and 88 deletions.
diff --git a/docs/modules/ROOT/pages/how-to/keycloak-rbac-login-flow.adoc b/docs/modules/ROOT/pages/how-to/keycloak-rbac-login-flow.adoc
@@ -54,15 +54,3 @@ Provider = Deny access
 ----
 
 . Mark both executions in the "Check User Roles" sub-flow as `REQUIRED`.
-
-== Configure all {zone} clients to use custom browser login flow
-
-Configure the "Browser Rbac" flow as the browser login flow for each {zone} {idp} client.
-
-. Go to "Clients > zone-client > Authentication Flow Overrides"
-. Set the browser flow to "Browser Rbac"
-+
-[source]
-----
-Browser Flow = browser rbac
-----
diff --git a/docs/modules/ROOT/pages/how-to/keycloak-setup.adoc b/docs/modules/ROOT/pages/how-to/keycloak-setup.adoc
@@ -13,14 +13,19 @@ Replace IDs and URLs as needed for your setup.
 
 * `oc` version 4.8 or above
 * working Commodore setup
-* SMTP server for sending out emails from Keycloak
 
 == Configure component-keycloak
 
 . Login to the cluster as cluster admin with `oc`
 
 . Add component configuration to Project Syn cluster catalog
 +
+[NOTE]
+====
+VSHN employees can refer to xref:how-to/vshn-example/activate-global.adoc#configure-cluster[this step] for a shortcut.
+Be sure to come back here for the next steps.
+====
++
 [source,yaml,subs="attributes+"]
 ----
 applications:
@@ -73,6 +78,8 @@ parameters:
 
 == Configure Keycloak
 
+These steps configure Keycloak on a global level and have to be done once per {product} environment.
+
 . Extract the password from the `keycloak-admin-user` secret.
 +
 [source,bash]
@@ -86,70 +93,13 @@ oc --as cluster-admin -n appuio-keycloak-test get secret keycloak-admin-user -o
 
 . Create a realm role called `appuio-zone-access`
 
-. Create a new Keycloak Client with the following settings (leave the others at default value)
-+
-[source]
-----
-Client ID = c-cluster-id <1>
-Access Type = confidential
-Valid Redirect URIs = https://oauth-openshift.apps.cluster-id.tld/oauth2callback/APPUiO-Cloud
-Base URL = https://console.apps.cluster-id.tld/
-----
-<1> For each enabled {zone} there shall be its own client using the cluster ID as name.
-
-. Configure the browser login flow for the client as described in xref:appuio-cloud:ROOT:how-to/keycloak-rbac-login-flow.adoc[Setup role-based access control for {product}]
-
-. Configure outgoing email settings in the realm
-+
-[source]
-----
-Host = mxout1.corp.vshn.net
-Port = 25
-From Display Name = APPUiO Cloud
-From = [email protected]
-Envelope From = [email protected]
-Enable StartTLS = true
-----
-
-. Allow the cluster's egress IP address(es) to relay mails on the configured SMTP host
-
 . Create a sync user as described in https://hub.syn.tools/group-sync-operator/how-tos/configure-keycloak-sync.html[Configure Group Sync with Keycloak]
-
-== Configure openshift4-authentication
-
-. Add the client secret to Vault.
-  The value is being displayed in a grey box in the "Credentials" tab from the Keycloak client settings.
-
-. Add component configuration
 +
-[source,yaml,subs="attributes+"]
-----
-parameters:
-  openshift4_authentication:
-    secrets:
-      appuio-cloud-keycloak:
-        clientSecret: '?{vaultkv:${cluster:tenant}/${cluster:name}/oidc/appuio-keycloak/clientSecret}' <1>
-
-    identityProviders:
-      appuio_keycloak:
-        name: APPUiO-Cloud
-        type: OpenID
-        mappingMethod: add
-        openID:
-          issuer: https://id.appuio.cloud/auth/realms/appuio-cloud
-          clientID: ${cluster:name}
-          clientSecret:
-            name: appuio-cloud-keycloak
-          claims: <2>
-            preferredUsername:
-              - preferred_username
-            name:
-              - name
-            email:
-              - email
-----
-<1> The Vault path for client secret
-<2> See also xref:explanation/decisions/usernames.adoc[User object names in the OpenShift cluster]
+[NOTE]
+====
+VSHN employees can refer to xref:how-to/vshn-example/activate-global.adoc#_configure_keycloak[this step] instead.
+====
 
-. Compile and push the cluster catalog
-. Wait for Argo CD to sync the config
+. Configure the browser login flow as described in xref:how-to/keycloak-rbac-login-flow.adoc[Setup role-based access control for {product}]
+
+For each {zone} to be added, follow the dedicated xref:how-to/zone-setup.adoc[Add a Cluster to {product}] guide.
diff --git a/docs/modules/ROOT/pages/how-to/vshn-example/activate-global.adoc b/docs/modules/ROOT/pages/how-to/vshn-example/activate-global.adoc
@@ -0,0 +1,48 @@
+= Activate {global} Environment
+
+NOTE: This guide is targeted at VSHN employees.
+
+== Prerequisites
+
+* working Commodore setup
+* SMTP server for sending out emails from Keycloak
+
+== Configure Cluster
+
+. Add the Commodore class to your cluster:
++
+[source,yaml]
+----
+classes:
+  - global.apps.appuio-cloud-global
+----
+
+== Configure Keycloak
+
+. Configure outgoing email settings in "appuio-cloud (realm) > Realm Settings > Email"
++
+[source]
+----
+Host = mxout1.corp.vshn.net
+Port = 25
+From Display Name = APPUiO Cloud
+From = [email protected]
+Envelope From = [email protected]
+Enable StartTLS = true
+----
+
+. Allow the cluster's egress IP address(es) to relay mails on the configured SMTP host
+
+. Add an API user in "master (realm) > Users > Add user" with the following properties:
++
+[source]
+----
+Username = appuio-keycloak-sync
+[ Credentials tab ] <1>
+Password = <Password>
+Temporary = False
+[ Role Mappings tab ] <1>
+Client Roles = appuio-cloud-realm
+Assigned Roles = view-users
+----
+<1> The tabs are visible after saving the new user first.
diff --git a/docs/modules/ROOT/pages/how-to/vshn-example/activate-zone.adoc b/docs/modules/ROOT/pages/how-to/vshn-example/activate-zone.adoc
@@ -2,16 +2,7 @@
 
 NOTE: This guide is targeted at VSHN employees.
 
-. Add the cluster as a new client to {idp}
-+
-[source]
-----
-Client ID = $CLUSTER_ID
-Access type = confidential
-Valid Redirect URIs = https://oauth-openshift.apps.<domain>/oauth2callback/APPUiO <1>
-Base URL = https://console.apps.<domain> <1>
-----
-<1> `<domain>` is a placeholder for the base hostname of the cluster
+. Add the cluster as a new client to {idp} as described in xref:how-to/zone-setup.adoc#_configure_keycloak[Configure Keycloak].
 
 . Add the Commodore class to your cluster:
 +
@@ -29,6 +20,7 @@ vault kv put clusters/kv/${TENANT_ID}/${CLUSTER_ID}/oidc/appuio-keycloak-sync pa
 vault kv put clusters/kv/${TENANT_ID}/${CLUSTER_ID}/oidc/appuio-keycloak clientSecret=... <2>
 ----
 <1> The API user for syncing groups and attributes from {idp}.
+    Retrieve the credentials from the Vault entry in the cluster where {global} is running on.
 <2> The generated client secret when configuring the cluster as a client in {idp} in previous step.
 
 . Compile and push cluster catalog
diff --git a/docs/modules/ROOT/pages/how-to/zone-setup.adoc b/docs/modules/ROOT/pages/how-to/zone-setup.adoc
@@ -2,7 +2,60 @@
 
 This guide describes the steps required to turn an OpenShift 4 cluster into an {zone}.
 
-NOTE: VSHN employees can refer to xref:how-to/vshn-example/activate-zone.adoc[Activate Zone] for an easier setup.
+== Configure Keycloak
+
+. Create a new Keycloak Client with the following settings (leave the others at default value)
++
+[source]
+----
+Client ID = c-cluster-id <1>
+Access Type = confidential
+Valid Redirect URIs = https://oauth-openshift.apps.cluster-id.tld/oauth2callback/APPUiO-Cloud
+Base URL = https://console.apps.cluster-id.tld/
+
+[ Authentication Flow Overrides ]
+Browser Flow = browser rbac <2>
+----
+<1> For each enabled {zone} there shall be its own client using the cluster ID as name.
+<2> See xref:how-to/keycloak-rbac-login-flow.adoc[Setup RBAC]
+
+NOTE: VSHN employees can now follow xref:how-to/vshn-example/activate-zone.adoc[Activate Zone] instead of continuing this guide.
+
+== Configure openshift4-authentication
+
+. After adding the cluster as a new client to {idp}, add the client secret to Vault.
+  The value is being displayed in a grey box in the "Credentials" tab from the Keycloak client settings.
+
+. Add component configuration
++
+[source,yaml,subs="attributes+"]
+----
+parameters:
+  openshift4_authentication:
+    secrets:
+      appuio-cloud-keycloak:
+        clientSecret: '?{vaultkv:${cluster:tenant}/${cluster:name}/oidc/appuio-keycloak/clientSecret}' <1>
+
+    identityProviders:
+      appuio_keycloak:
+        name: APPUiO-Cloud
+        type: OpenID
+        mappingMethod: add
+        openID:
+          issuer: https://id.appuio.cloud/auth/realms/appuio-cloud
+          clientID: ${cluster:name}
+          clientSecret:
+            name: appuio-cloud-keycloak
+          claims: <2>
+            preferredUsername:
+              - preferred_username
+            name:
+              - name
+            email:
+              - email
+----
+<1> The Vault path for client secret
+<2> See also xref:explanation/decisions/usernames.adoc[User object names in the OpenShift cluster]
 
 == Configure group-sync-operator
 

diff --git a/docs/modules/ROOT/partials/nav-howtos.adoc b/docs/modules/ROOT/partials/nav-howtos.adoc
@@ -13,3 +13,4 @@
 ** xref:appuio-cloud:ROOT:how-to/vshn-example/keycloak-brokering-rolemapping.adoc[Configure role mappings for Keycloak Brokering]
 ** xref:appuio-cloud:ROOT:how-to/vshn-example/keycloak-brokering-rbac.adoc[Configure role-based access control for brokered users]
 ** xref:appuio-cloud:ROOT:how-to/vshn-example/activate-zone.adoc[Activate Zone]
+** xref:appuio-cloud:ROOT:how-to/vshn-example/activate-global.adoc[Activate Global Environment]