Merge pull request #111 from stakater/external-keycloak

Add Keycloak integration configuration docs

content/explanation/console.md

@@ -25,15 +25,13 @@ components:
         host: tenant-operator-keycloak.<hostname>
         tlsSecretName: <tls-secret-name>
     showback: true
-    trustedRootCert: <root-ca-secret-name>
 ```  
 
 `<hostname>` : hostname of the cluster  
 `<ingress-class-name>` : name of the ingress class  
 `<tls-secret-name>` : name of the secret that contains the TLS certificate and key  
-`<root-ca-secret-name>` : name of the secret that contains the root CA certificate
 
->Note: `trustedRootCert` and `tls-secret-name` are optional. If not provided, MTO will use the default root CA certificate and secrets respectively.
+>Note: `tls-secret-name` are optional. If not provided, MTO will use the default secrets.
 
 Once the above configuration is set on the IntegrationConfig, MTO would start provisioning the required resources for MTO Console to be ready. In a few moments, you should be able to see the Console Ingress in the `multi-tenant-operator` namespace which gives you access to the Console.
 

content/how-to-guides/integration-config.md

@@ -23,7 +23,6 @@ Spec:
       Gateway:
         Host: tenant-operator-gateway.apps.mycluster-ams.abcdef.cloud
         TLSSecretName: tenant-operator-tls
-    trustedRootCert: my-custom-cert
   accessControl:
     rbac:
       tenantRoles:
@@ -94,8 +93,12 @@ Spec:
       annotations:
         openshift.io/node-selector: node-role.kubernetes.io/worker=
   integrations:
+    keycloak:
+      realm: mto
+      address: https://keycloak.apps.prod.abcdefghi.kubeapp.cloud    #include /auth if using RH-SSO
+      clientName: mto-console
     argocd:
-      enabled: bool
+      enabled: true
       clusterResourceWhitelist:
         - group: tronador.stakater.com
           kind: EnvironmentProvisioner
@@ -105,7 +108,7 @@ Spec:
       namespace: openshift-operators
     vault:
       enabled: true
-      authMethod: kubernetes      #enum: {kubernetes:default, Token}
+      authMethod: kubernetes      #enum: {kubernetes:default, token}
       accessInfo: 
         accessorPath: oidc/
         address: https://vault.apps.prod.abcdefghi.kubeapp.cloud/
@@ -136,7 +139,6 @@ Following are the different components that can be used to configure multi-tenan
       Gateway:
         Host: tenant-operator-gateway.apps.mycluster-ams.abcdef.cloud
         TLSSecretName: tenant-operator-tls
-    trustedRootCert: my-custom-cert
 ```
 
 - `components.console:` Enables or disables the console GUI for MTO.
@@ -152,7 +154,6 @@ Following are the different components that can be used to configure multi-tenan
     - `keycloak:` Settings for the Keycloak's ingress.
         - `host:` hostname for the Keycloak's ingress.
         - `tlsSecretName:` Name of the secret containing the TLS certificate and key for the Keycloak's ingress.
-- `components.trustedRootCert:` Name of the secret containing the root CA certificate.  
 
 Here's an example of how to generate the secrets required to configure MTO:
 
@@ -164,15 +165,7 @@ Create a TLS secret containing your SSL/TLS certificate and key for secure commu
 kubectl -n multi-tenant-operator create secret tls <tls-secret-name> --key=<path-to-key.pem> --cert=<path-to-cert.pem>
 ```
 
-**Trusted Root Certificate Secret:**  
-
-If using a custom certificate authority (CA) or self-signed certificates, create a Kubernetes secret containing your root CA certificate. This is required in order to ensure MTO Components trust the custom certificates.
-
-```bash
-kubectl -n multi-tenant-operator create secret generic <root-ca-secret-name> --from-file=<path-to-rootCA.pem>
-```
-
->Note: `trustedRootCert` and `tls-secret-name` are optional. If not provided, MTO will use the default root CA certificate and secrets respectively.
+>Note: `tls-secret-name` is optional. If not provided, MTO will use the default secrets.
 
 Integration config will be managing the following resources required for console GUI:
 
@@ -436,8 +429,12 @@ Integrations are used to configure the integrations that MTO has with other tool
 
 ```yaml
 integrations:
+  keycloak:
+    realm: mto
+    address: https://keycloak.apps.prod.abcdefghi.kubeapp.cloud/
+    clientName: mto-console
   argocd:
-    enabled: bool
+    enabled: true
     clusterResourceWhitelist:
       - group: tronador.stakater.com
         kind: EnvironmentProvisioner
@@ -459,6 +456,25 @@ integrations:
       ssoClient: vault
 ```
 
+### Keycloak
+
+[Keycloak](https://www.keycloak.org/) is an open-source Identity and Access Management solution aimed at modern applications and services. It makes it easy to secure applications and services with little to no code.
+
+If a `Keycloak` instance is already set up within your cluster, configure it for MTO by enabling the following configuration:
+
+```yaml
+keycloak:
+  realm: mto
+  address: https://keycloak.apps.prod.abcdefghi.kubeapp.cloud/
+  clientName: mto-console
+```
+
+- `keycloak.realm:` The realm in Keycloak where the client is configured.
+- `keycloak.address:` The address of the Keycloak instance.
+- `keycloak.clientName:` The name of the client in Keycloak.
+
+For more details around enabling Keycloak in MTO, visit [here](../reference-guides/integrating-external-keycloak.md)
+
 ### ArgoCD
 
 [ArgoCD](https://argoproj.github.io/argo-cd/) is a declarative, GitOps continuous delivery tool for Kubernetes. It follows the GitOps pattern of using Git repositories as the source of truth for defining the desired application state. ArgoCD uses Kubernetes manifests and configures the applications on the cluster.
@@ -467,7 +483,7 @@ If `argocd` is configured on a cluster, then ArgoCD configuration can be enabled
 
 ```yaml
 argocd:
-  enabled: bool
+  enabled: true
   clusterResourceWhitelist:
     - group: tronador.stakater.com
       kind: EnvironmentProvisioner

content/reference-guides/configuring-multitenant-network-isolation.md

@@ -67,14 +67,15 @@ spec:
     sandbox:
       labels:
         stakater.com/kind: sandbox
-  privileged:
-    namespaces:
-      - default
-      - ^openshift-*
-      - ^kube-*
-    serviceAccounts:
-      - ^system:serviceaccount:openshift-*
-      - ^system:serviceaccount:kube-*
+  accessControl:
+    privileged:
+      namespaces:
+        - default
+        - ^openshift-*
+        - ^kube-*
+      serviceAccounts:
+        - ^system:serviceaccount:openshift-*
+        - ^system:serviceaccount:kube-*
 ```
 
 Bill has added a new label `tenant-network-policy: "true"` in project section of IntegrationConfig, now MTO will add that label in all tenant projects.

content/reference-guides/integrating-external-keycloak.md

@@ -0,0 +1,48 @@
+# Integrating External Keycloak
+
+MTO Console uses Keycloak for authentication and authorization. By default, the MTO Console uses an internal Keycloak instance that is provisioned by the Multi Tenant Operator in its own namespace. However, you can also integrate an external Keycloak instance with the MTO Console.
+
+This guide will help you integrate an external Keycloak instance with the MTO Console.
+
+## Prerequisites
+
+- An OpenShift cluster with Multi Tenant Operator installed.
+- An external Keycloak instance.
+
+## Steps
+
+**Navigate to the Keycloak console.**
+
+- Go to your realm.
+- Click on the `Clients`.
+- Click on the `Create` button to create a new client.
+
+![Keycloak realm](../images/integrating-external-keycloak-1.png)
+
+**Create a new client.**
+
+- Fill in the `Client ID`, `Client Name` and `Client Protocol` fields.
+
+![Client creation](../images/integrating-external-keycloak-2.png)
+
+- Add `Valid Redirect URIs` and `Web Origins` for the client.
+
+![Client creation](../images/integrating-external-keycloak-3.png)
+
+> **Note:** The `Valid Redirect URIs` and `Web Origins` should be the URL of the MTO Console.
+
+- Click on the `Save` button.
+
+## Update Integration Config
+
+- Update the `IntegrationConfig` CR with the following configuration.
+
+```yaml
+integrations: 
+  keycloak:
+    realm: <realm>
+    address: <keycloak-address>
+    clientName: <client-name>
+```
+
+- Now, the MTO Console will be integrated with the external Keycloak instance.

content/reference-guides/integrationconfig.md

@@ -20,12 +20,13 @@ metadata:
   name: tenant-operator-config
   namespace: multi-tenant-operator
 spec:
-  privileged:
-    namespaces:
-      - ^default$
-      - ^openshift-.*
-      - ^kube-.*
-      - ^stakater-.*
+  accessControl:
+    privileged:
+      namespaces:
+        - ^default$
+        - ^openshift-.*
+        - ^kube-.*
+        - ^stakater-.*
 ```
 
 After mentioning the required regex (`^stakater-.*`) under `privilegedNamespaces`, Bill can create the namespace without interference.
@@ -46,13 +47,14 @@ metadata:
   name: tenant-operator-config
   namespace: multi-tenant-operator
 spec:
-  privileged:
-    serviceAccounts:
-      - system:serviceaccount:openshift
-      - system:serviceaccount:stakater
-      - system:serviceaccount:kube
-      - system:serviceaccount:redhat
-      - system:serviceaccount:hive
+  accessControl:
+    privileged:
+      serviceAccounts:
+        - system:serviceaccount:openshift
+        - system:serviceaccount:stakater
+        - system:serviceaccount:kube
+        - system:serviceaccount:redhat
+        - system:serviceaccount:hive
 ```
 
 Bill can also use regex patterns to ignore a set of service accounts:
@@ -64,10 +66,11 @@ metadata:
   name: tenant-operator-config
   namespace: multi-tenant-operator
 spec:
-  privileged:
-    serviceAccounts:
-      - ^system:serviceaccount:openshift-.*
-      - ^system:serviceaccount:stakater-.*
+  accessControl:
+    privileged:
+      serviceAccounts:
+        - ^system:serviceaccount:openshift-.*
+        - ^system:serviceaccount:stakater-.*
 ```
 
 ## Configuring Vault in IntegrationConfig

content/tutorials/argocd/enabling-multi-tenancy-argocd.md

@@ -34,8 +34,10 @@ metadata:
   namespace: multi-tenant-operator
 spec:
   ...
-  argocd:
-    namespace: openshift-operators
+  integrations:
+    argocd:
+      enabled: true
+      namespace: openshift-operators
   ...
 ```
 
@@ -143,6 +145,7 @@ spec:
   ...
   integrations:
     argocd:
+      enabled: true
       namespace: openshift-operators
       namespaceResourceBlacklist:
         - group: ""
@@ -184,6 +187,7 @@ spec:
   ...
   integrations:
     argocd:
+      enabled: true
       namespace: openshift-operators
       clusterResourceWhitelist:
         - group: ""

theme_override/mkdocs.yml

@@ -44,6 +44,7 @@ nav:
       - reference-guides/deploying-private-helm-charts.md
       - reference-guides/extend-default-roles.md
       - reference-guides/integrationconfig.md
+      - reference-guides/integrating-external-keycloak.md
       - reference-guides/mattermost.md
       - reference-guides/secret-distribution.md
       - reference-guides/custom-metrics.md