Merge pull request #41 from appuio/group-sync

Add how-to page to setup Zones

docs/modules/ROOT/pages/how-to/keycloak-setup.adoc

@@ -109,6 +109,8 @@ 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.

docs/modules/ROOT/pages/how-to/zone-setup.adoc

@@ -0,0 +1,64 @@
+= Activate {zone}
+
+This guide describes the steps required to turn an OpenShift 4 cluster into an {zone}.
+
+== Configure group-sync-operator
+
+The https://github.com/appuio/keycloak-attribute-sync-controller[group-sync-operator] is required to sync Keycloak groups to each {zone}.
+
+. Add component configuration
++
+[source,yaml,subs="attributes+"]
+----
+parameters:
+  group_sync_operator:
+    secrets:
+      sync-appuio-keycloak-groups:
+        stringData:
+          username: '?{vaultkv:${cluster:tenant}/${cluster:name}/oidc/appuio-keycloak-user-sync/username}'
+          password: '?{vaultkv:${cluster:tenant}/${cluster:name}/oidc/appuio-keycloak-user-sync/password}'
+    sync:
+      sync-keycloak-groups:
+        schedule: '* * * * *'
+        providers:
+          keycloak:
+            keycloak:
+              url: https://id.appuio.cloud
+              credentialsSecret:
+                name: sync-appuio-keycloak-groups
+              loginRealm: master
+              realm: appuio-cloud
+              scope: sub
+----
+
+== Configure keycloak-attribute-sync-controller
+
+The https://github.com/redhat-cop/group-sync-operator[keycloak-attribute-sync-controller] is required to sync Keycloak user attributes to each {zone}.
+
+. Add component configuration
++
+[source,yaml,subs="attributes+"]
+----
+parameters:
+  keycloak_attribute_sync_controller:
+    sync_credentials:
+      sync-default-org-credentials:
+        stringData:
+          username: '?{vaultkv:${cluster:tenant}/${cluster:name}/oidc/appuio-keycloak-user-sync/username}' <1>
+          password: '?{vaultkv:${cluster:tenant}/${cluster:name}/oidc/appuio-keycloak-user-sync/password}'
+
+    sync_configurations:
+      sync-default-org:
+        url: https://id.appuio.cloud
+        loginRealm: master
+        credentialsSecret:
+          name: sync-default-org-credentials
+        realm: appuio-cloud
+        attribute: appuio.io/default-organization
+        targetAnnotation: appuio.io/default-organization
+        schedule: '@every 1m'
+----
+<1> The user for syncing attributes is the same as the one used for group-sync-operator.
+
+. Compile and push the cluster catalog
+. Wait for Argo CD to sync the config

docs/modules/ROOT/partials/nav-howtos.adoc

@@ -1,3 +1,4 @@
 * Installation
 ** xref:appuio-cloud:ROOT:how-to/keycloak-setup.adoc[Install Keycloak]
 ** xref:appuio-cloud:ROOT:how-to/keycloak-brokering.adoc[Add Keycloak brokering]
+** xref:appuio-cloud:ROOT:how-to/zone-setup.adoc[Activate {zone}]