ENDOC-521 Tutorial correction: Connect to an External Keycloak Instance #534

Lyd1aCla1r3 · 2022-07-11T20:22:14Z

first commit is a placeholder pending discussion

nshaw · 2022-07-11T20:51:06Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

    kind: Secret
    metadata
        name: keycloak-admin-secret
        namespace: YOUR-APP-NAMESPACE
    type: Opaque

+The client for the admin user will automatically detect this Secret by name and use it to log in to the Keycloak server at the specified URL.


"The client for the admin user.." -> "Entando will use these admin credentials via the named Secret in order to make use of the Keycloak APIs to provision the entando realm"

nshaw · 2022-07-11T20:52:08Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

+
+Upload the Secret to the namespace where you want to deploy your Entando instance:
+
+    oc create -f YOUR-SECRET.yaml -n YOUR-NAMESPACE


We should change this to kubectl apply -f ..., to match the later command, instead of oc.

nshaw · 2022-07-11T20:52:47Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

-> `echo YOUR-VALUE | base64`
+> To encode a value in bash, use `echo YOUR-SECRET-VALUE | base64`
+
+### 3. Upload the Secret


Upload is the wrong term. Either apply or create would be better, maybe just Create the Secret.

nshaw · 2022-07-11T20:56:19Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

-Now you are ready to deploy your Entando application and the
-administrator will reuse the *keycloak-admin-secret* secret to populate
-the environment correctly.
+You are now ready to deploy your Entando Application. The admin user clien will reuse *keycloak-admin-secret* to populate the environment correctly.


I would still include the article - the keycloak-admin-secret since it refers to that specific secret.

nshaw · 2022-07-11T20:59:12Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

-        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


Maybe we should simplify this tutorial like we've done elsewhere, replace YOUR-APP-NAMESPACE with entando, and YOUR-SECRET with keycloak-admin-secret. That allows the user to apply the commands as-is in a quickstart env without changes. In a custom impl, they will need to customize it regardless.

nshaw · 2022-07-12T12:37:01Z

vuepress/docs/next/tutorials/devops/external-id-management.md


-   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 best practice to exclusively enter the admin credentials of a service account dedicated to the management and tracking of system changes.


I'm not sure this has quite the meaning. Typically, you want to use a dedicated service account when connecting two systems, rather than an individual user's account. That way if the credentials change or you need to know who made a change you can tell the difference between the activities. Maybe just "... it is a good practice to provide the credentials for a dedicated service account."

nshaw · 2022-07-12T12:37:25Z

vuepress/docs/next/tutorials/devops/external-id-management.md

+  provisioningStrategy: UseExternal
+  adminSecretName: keycloak-admin-secret
+  frontEndUrl: >-
+    http://<keycloak_url>/auth


Caps for the placeholder?

nshaw · 2022-07-12T12:38:22Z

vuepress/docs/next/tutorials/devops/external-id-management.md

-Now you are ready to deploy your Entando application and the
-administrator will reuse the *keycloak-admin-secret* secret to populate
-the environment correctly.
+You are now ready to deploy your Entando Application. Entando will reuse the *keycloak-admin-secret* to populate the environment correctly.


reuse -> make use of

nshaw · 2022-07-12T17:01:57Z

vuepress/docs/next/tutorials/devops/external-id-management.md

-
-   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

jyunmitch

I think some of my comments were already applied in some cases so ignore those.

jyunmitch · 2022-07-13T21:27:23Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

@@ -2,75 +2,83 @@

 ## Purpose

-This tutorial enables the Entando administrator to leverage an existing
-Keycloak instance.
+This tutorial details how an Entando instance can be connected to an existing Keycloak instance by an admin user of the Keycloak instance.


instance is repeated 3 times in this sentence

jyunmitch · 2022-07-13T21:27:52Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

@@ -2,75 +2,83 @@

 ## Purpose


Don't think we need this header as we haven't been using it in other tutorials

jyunmitch · 2022-07-13T21:28:46Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

-use.
-
-Specifically you will need:
+### 1. Get Keycloak information


cap Information

jyunmitch · 2022-07-13T21:30:04Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

-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:


should keycloak-admin-secret be backticked?

jyunmitch · 2022-07-13T21:35:21Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

+
+    oc create -f YOUR-SECRET.yaml -n YOUR-NAMESPACE
+
+### 4. Create a YAML configuration file


maybe level 3 header doesn't need all caps but I think that's what we've been doing elsewhere. Same below

jyunmitch · 2022-07-14T13:22:44Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

+kind: EntandoKeycloakServer
+metadata:
+  name: external-keycloak
+  namespace: {{ namespace }}


are these brackets correct? I looked it up and it said something about evaluating the variable inside the brackets but in this case, I don't know if it applies. I've never noticed brackets around the namespace

jyunmitch · 2022-07-14T13:31:55Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

-Next upload the secret to the namespace where you want to deploy your
-Entando instance.
+```
+kubectl apply -f YOUR-YAML-FILE.yaml -n YOUR-NAMESPACE


should YOUR-NAMESPACE match up with the YAML file above?

jyunmitch · 2022-07-14T13:33:04Z

vuepress/docs/v7.0/tutorials/devops/external-id-management.md

-Now you are ready to deploy your Entando application and the
-administrator will reuse the *keycloak-admin-secret* secret to populate
-the environment correctly.
+You are now ready to deploy your Entando Application. The admin user clien will reuse *keycloak-admin-secret* to populate the environment correctly.


ENDOC-521

8f9d1d8

Lyd1aCla1r3 requested a review from nshaw July 11, 2022 20:22

ENDOC-521 Edits for clarity/accuracy

7498619

nshaw suggested changes Jul 11, 2022

View reviewed changes

ENDOC-521 changes + Next

46b1093

nshaw suggested changes Jul 12, 2022

View reviewed changes

nshaw reviewed Jul 12, 2022

View reviewed changes

ENDOC-521 Final revisions

3f04920

nshaw approved these changes Jul 12, 2022

View reviewed changes

ENDOC-521 Link to learning path operations

295c42b

nshaw approved these changes Jul 13, 2022

View reviewed changes

jyunmitch reviewed Jul 14, 2022

View reviewed changes

Lyd1aCla1r3 merged commit 2d6d712 into main Jul 14, 2022

nshaw deleted the ENDOC-521 branch August 26, 2022 18:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENDOC-521 Tutorial correction: Connect to an External Keycloak Instance #534

ENDOC-521 Tutorial correction: Connect to an External Keycloak Instance #534

Lyd1aCla1r3 commented Jul 11, 2022

nshaw Jul 11, 2022

nshaw Jul 11, 2022

nshaw Jul 11, 2022

nshaw Jul 11, 2022

nshaw Jul 11, 2022

nshaw Jul 12, 2022

nshaw Jul 12, 2022

nshaw Jul 12, 2022

nshaw Jul 12, 2022

jyunmitch left a comment

jyunmitch Jul 13, 2022

jyunmitch Jul 13, 2022

jyunmitch Jul 13, 2022

jyunmitch Jul 13, 2022

jyunmitch Jul 13, 2022

jyunmitch Jul 14, 2022

jyunmitch Jul 14, 2022

jyunmitch Jul 14, 2022


		Upload the Secret to the namespace where you want to deploy your Entando instance:

		oc create -f YOUR-SECRET.yaml -n YOUR-NAMESPACE


		oc create -f YOUR-SECRET.yaml -n YOUR-NAMESPACE

		### 4. Create a YAML configuration file

ENDOC-521 Tutorial correction: Connect to an External Keycloak Instance #534

ENDOC-521 Tutorial correction: Connect to an External Keycloak Instance #534

Conversation

Lyd1aCla1r3 commented Jul 11, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jyunmitch left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment