Merge pull request #534 from entando/ENDOC-521

ENDOC-521 Tutorial correction: Connect to an External Keycloak Instance
entando · Jul 14, 2022 · 2d6d712 · 2d6d712
2 parents f93d3cb + 295c42b
commit 2d6d712
Show file tree

Hide file tree

Showing 2 changed files with 107 additions and 86 deletions.
diff --git a/vuepress/docs/next/tutorials/devops/external-id-management.md b/vuepress/docs/next/tutorials/devops/external-id-management.md
@@ -2,75 +2,85 @@
 
 ## Purpose
 
-This tutorial enables the Entando administrator to leverage an existing
-Keycloak instance.
+This tutorial details how Entando can be connected to an existing Keycloak instance.
 
-## Requirements
+## Prerequisites
 
 -   A Keycloak instance
-
--   A realm named "entando" on that instance
-
--   An admin user for the "entando" realm
+-   A realm named "entando" in that instance
+-   Admin user credentials for the "entando" realm. These are the credentials (username/password) for the service account that has the correct level of admin permissions.
 
 ## Steps
 
-### 1. Get keycloak information
-
-Retrieve the relevant information from the Keycloak instance you want to
-use.
-
-Specifically you will need:
+### 1. Get Keycloak information
 
--   The username of the Keycloak admin that has admin rights to the
-    "entando" realm, e.g entando-keycloak-admin
+Retrieve the following information from the existing Keycloak instance:
 
--   The Keycloak admin password, e.g. password123
+-   The username of the admin user with rights to the "entando" realm, e.g entando-keycloak-admin
+-   The admin user password, e.g. password123
+-   The base URL for the Keycloak server, including the auth value, e.g. https://YOUR-KEYCLOAK-INSTANCE.com/auth
 
--   The base url for the Keycloak server, including the auth value, e.g.
-    https://your-keycloak-instance.com/auth
+> **Note** When connecting an external Keycloak instance to Entando, it is a good practice to provide the admin credentials for a dedicated service account.
+### 2. Generate the Secret
 
-### 2. Generate the secret
-
-You now need to generate a secret with name *keycloak-admin-secret*
-using the information retrieved from step 1. The Entando administrator
-will automatically detect this secret by name, and use it to log onto
-the provided Keycloak server.
-
-Here is an example of the secret you will need to construct:
+Generate a Secret named *keycloak-admin-secret* with the information retrieved in Step 1. For example:
 
     ---
     apiVersion: v1
     stringData:
         username: #the username of the Keycloak admin user for the "entando" realm
-        password: #the password of this Keycloak admin user
-        url: #the base url of the Keycloak service, typically ending with the path /auth
+        password: #the password of the Keycloak admin user
+        url: #the base URL of the Keycloak service, typically ending with the path /auth
     kind: Secret
     metadata
         name: keycloak-admin-secret
-        namespace: YOUR-APP-NAMESPACE
+        namespace: entando 
     type: Opaque
 
-> **Note**
->
-> To encode your values, in bash, you can do
-> `echo YOUR-VALUE | base64`
+Via the named Secret, Entando supplies the Keycloak APIs with the admin credentials they require to provision the "entando" realm.
+
+> **Note** To encode a value in bash, use `echo YOUR-SECRET-VALUE | base64`
+
+### 3. Create the Secret
+
+Apply the Secret to the namespace where you want to deploy your Entando instance:
+
+    kubectl apply -f keycloak-admin-secret.yaml -n entando
+
+### 4. Create a YAML configuration file
+
+Create a YAML file to configure Keycloak, based on the following template:
+
+```
+apiVersion: entando.org/v1
+kind: EntandoKeycloakServer
+metadata:
+  name: external-keycloak
+  namespace: entando
+spec:
+  environmentVariables: []
+  provisioningStrategy: UseExternal
+  adminSecretName: keycloak-admin-secret
+  frontEndUrl: >-
+    http://KEYCLOAK-URL/auth
+```
+
+### 5. Apply the YAML configuration file
+
+Apply the YAML configuration file to the namespace where you want to deploy your Entando instance:
 
-### 3. Upload the secret
+```
+kubectl apply -f YOUR-YAML-FILE.yaml -n entando
 
-Next upload the secret to the namespace where you want to deploy your
-Entando instance.
+```
 
-    oc create -f YOUR-SECRET.yaml -n MY-APP-NAMESPACE
+### 6. Deploy the Entando Application
 
-### 4. Deploy the Entando application
+You are now ready to deploy your Entando Application. Entando will use the *keycloak-admin-secret* to populate the environment correctly. 
 
-Now you are ready to deploy your Entando application and the
-administrator will reuse the *keycloak-admin-secret* secret to populate
-the environment correctly.
+Refer to the [learning path tutorials](../README.md#operations) to install, configure and customize your Entando instance.
 
 ## Conclusion
 
-You should now have a working Entando instance using an external
-Keycloak server.
+This should result in a working Entando instance that is connected to an external Keycloak server.
 
diff --git a/vuepress/docs/v7.0/tutorials/devops/external-id-management.md b/vuepress/docs/v7.0/tutorials/devops/external-id-management.md
@@ -2,75 +2,86 @@
 
 ## Purpose
 
-This tutorial enables the Entando administrator to leverage an existing
-Keycloak instance.
+This tutorial details how Entando can be connected to an existing Keycloak instance.
 
-## Requirements
+## Prerequisites
 
 -   A Keycloak instance
-
--   A realm named "entando" on that instance
-
--   An admin user for the "entando" realm
+-   A realm named "entando" in that instance
+-   Admin user credentials for the "entando" realm. These are the credentials (username/password) for the service account that has the correct level of admin permissions.
 
 ## Steps
 
-### 1. Get keycloak information
-
-Retrieve the relevant information from the Keycloak instance you want to
-use.
-
-Specifically you will need:
+### 1. Get Keycloak information
 
--   The username of the Keycloak admin that has admin rights to the
-    "entando" realm, e.g entando-keycloak-admin
+Retrieve the following information from the existing Keycloak instance:
 
--   The Keycloak admin password, e.g. password123
+-   The username of the admin user with rights to the "entando" realm, e.g entando-keycloak-admin
+-   The admin user password, e.g. password123
+-   The base URL for the Keycloak server, including the auth value, e.g. https://YOUR-KEYCLOAK-INSTANCE.com/auth
 
--   The base url for the Keycloak server, including the auth value, e.g.
-    https://your-keycloak-instance.com/auth
+> **Note** When connecting an external Keycloak instance to Entando, it is a good practice to provide the admin credentials for a dedicated service account.
+### 2. Generate the Secret
 
-### 2. Generate the secret
-
-You now need to generate a secret with name *keycloak-admin-secret*
-using the information retrieved from step 1. The Entando administrator
-will automatically detect this secret by name, and use it to log onto
-the provided Keycloak server.
-
-Here is an example of the secret you will need to construct:
+Generate a Secret named *keycloak-admin-secret* with the information retrieved in Step 1. For example:
 
     ---
     apiVersion: v1
     stringData:
         username: #the username of the Keycloak admin user for the "entando" realm
-        password: #the password of this Keycloak admin user
-        url: #the base url of the Keycloak service, typically ending with the path /auth
+        password: #the password of the Keycloak admin user
+        url: #the base URL of the Keycloak service, typically ending with the path /auth
     kind: Secret
     metadata
         name: keycloak-admin-secret
-        namespace: YOUR-APP-NAMESPACE
+        namespace: entando 
     type: Opaque
 
-> **Note**
->
-> To encode your values, in bash, you can do
-> `echo YOUR-VALUE | base64`
+Via the named Secret, Entando supplies the Keycloak APIs with the admin credentials they require to provision the "entando" realm.
+
+> **Note** To encode a value in bash, use `echo YOUR-SECRET-VALUE | base64`
+
+### 3. Create the Secret
 
-### 3. Upload the secret
+Apply the Secret to the namespace where you want to deploy your Entando instance:
 
-Next upload the secret to the namespace where you want to deploy your
-Entando instance.
+    kubectl apply -f keycloak-admin-secret.yaml -n entando
 
-    oc create -f YOUR-SECRET.yaml -n MY-APP-NAMESPACE
+### 4. Create a YAML configuration file
 
-### 4. Deploy the Entando application
+Create a YAML file to configure Keycloak, based on the following template:
 
-Now you are ready to deploy your Entando application and the
-administrator will reuse the *keycloak-admin-secret* secret to populate
-the environment correctly.
+```
+apiVersion: entando.org/v1
+kind: EntandoKeycloakServer
+metadata:
+  name: external-keycloak
+  namespace: entando
+spec:
+  environmentVariables: []
+  provisioningStrategy: UseExternal
+  adminSecretName: keycloak-admin-secret
+  frontEndUrl: >-
+    http://KEYCLOAK-URL/auth
+```
+
+### 5. Apply the YAML configuration file
+
+Apply the YAML configuration file to the namespace where you want to deploy your Entando instance:
+
+```
+kubectl apply -f YOUR-YAML-FILE.yaml -n entando
+
+```
+
+### 6. Deploy the Entando Application
+
+You are now ready to deploy your Entando Application. Entando will use the *keycloak-admin-secret* to populate the environment correctly. 
+
+Refer to the [learning path tutorials](../README.md#operations) to install, configure and customize your Entando instance.
 
 ## Conclusion
 
-You should now have a working Entando instance using an external
-Keycloak server.
+This should result in a working Entando instance that is connected to an external Keycloak server.
+