From f5eaaf36502ac3ea4911bf01e5a6d15554cbe699 Mon Sep 17 00:00:00 2001
From: Guido Grazioli <ggraziol@redhat.com>
Date: Wed, 22 Dec 2021 14:02:13 +0100
Subject: [PATCH] Update READMEs

---
 README.md                      |  7 +++++
 roles/keycloak_realm/README.md | 53 ++++++++++++++++++++++++++++++++--
 2 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index e9263e9..055bb2e 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,13 @@ rhsso_rhn_id: '<sso_product_id>'
 
 where `sso_product_id` is the ID for the specific Red Hat Single Sign-On version, ie. _101971_ will install version _7.5_)
 
+
+## Included roles
+
+* `keycloak`: role for installing the service.
+* `keycloak_realm`: role for configuring a realm, with clients and users, in an installed service.
+
+
 ## License
 
 Apache License v2.0 or later
diff --git a/roles/keycloak_realm/README.md b/roles/keycloak_realm/README.md
index 40c2ec7..d39b2a3 100644
--- a/roles/keycloak_realm/README.md
+++ b/roles/keycloak_realm/README.md
@@ -9,7 +9,12 @@ Role Defaults
 
 | Variable | Description | Default |
 |:---------|:------------|:---------|
-|`keycloak_admin_user`| Administration console user account | `admin` |
+|`keycloak_admin_user` | Administration console user account | `admin` |
+|`keycloak_host` | hostname | `localhost` |
+|`keycloak_http_port` | HTTP port | `8080` |
+|`keycloak_https_port` | TLS HTTP port | `8443` |
+|`keycloak_auth_realm` | Name of the main authentication realm | `master` |
+
 
 Role Variables
 --------------
@@ -19,19 +24,58 @@ The following are a set of _required_ variables for the role:
 | Variable | Description |
 |:---------|:------------|
 |`keycloak_admin_password`| Password for the administration console user account |
+|`keycloak_realm` | Name of the realm to be created |
 
 
-The following variables are _required_ only when keycloak_ha_enabled is True:
+The following variables are available for creating clients:
 
 | Variable | Description | Default |
 |:---------|:------------|:---------|
+|`keycloak_clients` | List of _client_ declarations for the realm | `[]` |
+|`keycloak_client_default_roles` | List of default role name for clients | `[]` |
+|`keycloak_client_users` | List of user/role mappings for a client | `[]` |
 
 
+Variable formats
+----------------
+
+* `keycloak_clients`, a list of:
+
+```yaml
+    - name: <name of the client>
+      roles: <keycloak_client_default_roles>
+      realm: <name of the realm that contains the client>
+      public_client: <true for public, false for confidential>
+      web_origins: <list of allowed we origins for the client>
+      users: <keycloak_client_users>
+```
+
+* `keycloak_client_users`, a list of:
+
+```yaml
+    - username: <username, required>
+      password: <password, required>
+      firstName: <firstName, optional>
+      lastName: <lastName, optional>
+      email: <email, optional>
+      client_roles: <list of client user/role mappings>
+```
+
+* Client user/role mappings, a list of:
+
+```yaml
+    - client: <name of the client>
+      role: <name of the role>
+      realm: <name of the realm>
+```
+
+For a comprehensive example, refer to the [playbook](playbooks/keycloak.yml).
+
 
 Example Playbook
 ----------------
 
-The following is an example playbook that makes use of the role to install keycloak
+The following is an example playbook that makes use of the role to create a realm in keycloak.
 
 ```yaml
 ---
@@ -44,8 +88,11 @@ The following is an example playbook that makes use of the role to install keycl
             name: keycloak_realm
           vars:
             keycloak_admin_password: "changeme"
+            keycloak_realm: TestRealm
+            keycloak_clients: [...]
 ```
 
+
 License
 -------