From 20f321c6282808fc0c41199c2bcce8c0ecbe27fb Mon Sep 17 00:00:00 2001 From: Guido Grazioli Date: Wed, 9 Feb 2022 11:19:49 +0100 Subject: [PATCH] document argument_specs --- CONTRIBUTING.md | 8 +- README.md | 15 +-- ...{keycloak-realm.yml => keycloak_realm.yml} | 0 roles/keycloak/meta/argument_specs.yml | 102 +++++++++--------- roles/keycloak_realm/README.md | 13 ++- roles/keycloak_realm/defaults/main.yml | 1 + roles/keycloak_realm/meta/argument_specs.yml | 40 +++---- roles/keycloak_realm/vars/main.yml | 3 - 8 files changed, 92 insertions(+), 90 deletions(-) rename playbooks/{keycloak-realm.yml => keycloak_realm.yml} (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7698001..613657d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,10 +5,10 @@ - Use spaces around jinja variables. `{{ var }}` over `{{var}}` - Variables that are internal to the role should be lowercase and start with the role name - Keep roles self contained - Roles should avoid including tasks from other roles when possible -- Plays should do nothing more than include a list of roles except where `pre_tasks` and `post_tasks` are required when possible -- Separators - Use valid name, ie. underscores (e.g. `my_role` `my_playbook`) not dashes (`my-role`) -- Paths - When defining paths, do not include trailing slashes (e.g. `my_path: /foo` not `my_path: /foo/`). When concatenating paths, follow the same convention (e.g. `{{ my_path }}/bar` not `{{ my_path }}bar`) +- Plays should do nothing more than include a list of roles, except where `pre_tasks` and `post_tasks` are required, when possible +- Separators - Use valid names, ie. underscores (e.g. `my_role` `my_playbook`) not dashes (`my-role`) +- Paths - When defining paths, do not include trailing slashes (e.g. `my_path: /foo` not `my_path: /foo/`); when concatenating paths, follow the same convention (e.g. `{{ my_path }}/bar` not `{{ my_path }}bar`) - Indentation - Use 2 spaces for each indent - `vars/` vs `defaults/` - internal or interpolated variables that don't need to change or be overridden by user go in `vars/`, those that a user would likely override, go under `defaults/` directory -- All arguments have a specification in `meta/argument_specs.yml` +- All role arguments have a specification in `meta/argument_specs.yml` - All playbooks/roles should be focused on compatibility with Ansible Tower diff --git a/README.md b/README.md index caafef7..93d7a98 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Ansible Collection - keycloak +# Ansible Collection - middleware_automation.keycloak [![Build Status](https://github.com/ansible-middleware/keycloak/workflows/CI/badge.svg?branch=main)](https://github.com/ansible-middleware/keycloak/actions/workflows/ci.yml) @@ -13,6 +13,7 @@ This collection has been tested against following Ansible versions: **>=2.9.10** Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions. + ## Installation ### Installing the Collection from Ansible Galaxy @@ -54,12 +55,12 @@ A requirement file is provided to install: Both playbooks include the `keycloak` role, with different settings, as described in the following sections. -For service configuration details, refer to the [keycloak role README](roles/keycloak/README.md). +For full service configuration details, refer to the [keycloak role README](roles/keycloak/README.md). ### Choosing between upstream project (Keycloak) and Red Hat Single Sign-On (RHSSO) -The general flag `keycloak_rhsso_enable` controls what to install between upstream(Keycloak, when `False`) or Red Hat Single Sign-On (when `True`). +The general flag `keycloak_rhsso_enable` controls what to install between upstream (Keycloak, when `False`) or Red Hat Single Sign-On (when `True`). The default value for the flag if `True` when Red Hat Network credentials are defined, `False` otherwise. @@ -133,15 +134,15 @@ ansible-playbook -i -e @rhn-creds.yml playbooks/keycloak.yml -e ### Config Playbook -[`playbooks/keycloak-realm.yml`](playbooks/keycloak-realm.yml) creates provided realm, user federation(s), client(s), client role(s) and client user(s) if they don't exist. +[`playbooks/keycloak_realm.yml`](playbooks/keycloak_realm.yml) creates or updates provided realm, user federation(s), client(s), client role(s) and client user(s). ### Example configuration command -Execute the following command from the source root directory +Execute the following command from the source root directory: ```bash -ansible-playbook -i playbooks/keycloak-realm.yml -e keycloak_admin_password= -e keycloak_realm=test +ansible-playbook -i playbooks/keycloak_realm.yml -e keycloak_admin_password= -e keycloak_realm=test ``` - `keycloak_admin_password` password for the administration console user account. @@ -153,7 +154,7 @@ ansible-playbook -i playbooks/keycloak-realm.yml -e keycloak_adm localhost ansible_connection=local ``` -For configuration details, refer to the [keycloak_realm role README](roles/keycloak_realm/README.md). +For full configuration details, refer to the [keycloak_realm role README](roles/keycloak_realm/README.md). ## License diff --git a/playbooks/keycloak-realm.yml b/playbooks/keycloak_realm.yml similarity index 100% rename from playbooks/keycloak-realm.yml rename to playbooks/keycloak_realm.yml diff --git a/roles/keycloak/meta/argument_specs.yml b/roles/keycloak/meta/argument_specs.yml index e361fc3..8331945 100644 --- a/roles/keycloak/meta/argument_specs.yml +++ b/roles/keycloak/meta/argument_specs.yml @@ -4,162 +4,162 @@ argument_specs: keycloak_version: # line 3 of keycloak/defaults/main.yml default: "15.0.2" - description: "TODO document argument" + description: "keycloak.org package version" type: "str" keycloak_archive: # line 4 of keycloak/defaults/main.yml default: "keycloak-{{ keycloak_version }}.zip" - description: "TODO document argument" + description: "keycloak install archive filename" type: "str" keycloak_download_url: # line 5 of keycloak/defaults/main.yml default: "https://github.com/keycloak/keycloak/releases/download/{{ keycloak_version }}/{{ keycloak_archive }}" - description: "TODO document argument" + description: "Download URL for keycloak" type: "str" keycloak_download_url_9x: # line 6 of keycloak/defaults/main.yml default: "https://downloads.jboss.org/keycloak/{{ keycloak_version }}/{{ keycloak_archive }}" - description: "TODO document argument" + description: "Download URL for keycloak (deprecated)" type: "str" keycloak_installdir: # line 7 of keycloak/defaults/main.yml default: "{{ keycloak_dest }}/keycloak-{{ keycloak_version }}" - description: "TODO document argument" + description: "Installation path" type: "str" keycloak_rhsso_version: # line 10 of keycloak/defaults/main.yml default: "7.5.0" - description: "TODO document argument" + description: "Red Hat Single Sign-On version" type: "str" rhsso_rhn_id: # line 11 of keycloak/defaults/main.yml default: "{{ rhsso_rhn_ids[keycloak_rhsso_version] }}" - description: "TODO document argument" + description: "Customer Portal product ID for Red Hat SSO" type: "str" keycloak_rhsso_archive: # line 12 of keycloak/defaults/main.yml default: "rh-sso-{{ keycloak_rhsso_version }}-server-dist.zip" - description: "TODO document argument" + description: "ed Hat SSO install archive filename" type: "str" keycloak_rhsso_installdir: # line 13 of keycloak/defaults/main.yml default: "{{ keycloak_dest }}/rh-sso-{{ keycloak_rhsso_version | regex_replace('^([0-9])\\.([0-9]*).*', '\\1.\\2') }}" - description: "TODO document argument" + description: "Installation path for Red Hat SSO" type: "str" keycloak_rhn_url: # line 14 of keycloak/defaults/main.yml default: "https://access.redhat.com/jbossnetwork/restricted/softwareDownload.html?softwareId=" - description: "TODO document argument" + description: "Base download URI for customer portal" type: "str" keycloak_rhsso_download_url: # line 15 of keycloak/defaults/main.yml default: "{{ keycloak_rhn_url }}{{ rhsso_rhn_id }}" - description: "TODO document argument" + description: "Full download URI for Red Hat SSO" type: "str" keycloak_rhsso_enable: # line 18 of keycloak/defaults/main.yml default: "{{ True if rhsso_rhn_id is defined and rhn_username is defined and rhn_password is defined else False }}" - description: "TODO document argument" + description: "Enable Red Hat Single Sign-on installation" type: "str" keycloak_offline_install: # line 20 of keycloak/defaults/main.yml default: false - description: "TODO document argument" + description: "Perform an offline install" type: "bool" jvm_package: # line 23 of keycloak/defaults/main.yml default: "java-1.8.0-openjdk-devel" - description: "TODO document argument" + description: "RHEL java package runtime rpm" type: "str" keycloak_dest: # line 24 of keycloak/defaults/main.yml default: "/opt/keycloak" - description: "TODO document argument" + description: "Root installation directory" type: "str" keycloak_jboss_home: # line 25 of keycloak/defaults/main.yml default: "{{ keycloak_rhsso_installdir if keycloak_rhsso_enable else keycloak_installdir }}" - description: "TODO document argument" + description: "Installation work directory" type: "str" keycloak_config_dir: # line 26 of keycloak/defaults/main.yml default: "{{ keycloak_jboss_home }}/standalone/configuration" - description: "TODO document argument" + description: "Path for configuration" type: "str" keycloak_config_standalone_xml: # line 27 of keycloak/defaults/main.yml default: "keycloak.xml" - description: "TODO document argument" + description: "Service configuration filename" type: "str" keycloak_config_path_to_standalone_xml: # line 28 of keycloak/defaults/main.yml default: "{{ keycloak_jboss_home }}/standalone/configuration/{{ keycloak_config_standalone_xml }}" - description: "TODO document argument" + description: "Custom path for configuration" type: "str" keycloak_service_user: # line 29 of keycloak/defaults/main.yml default: "keycloak" - description: "TODO document argument" + description: "posix account username" type: "str" keycloak_service_group: # line 30 of keycloak/defaults/main.yml default: "keycloak" - description: "TODO document argument" + description: "posix account group" type: "str" keycloak_service_pidfile: # line 31 of keycloak/defaults/main.yml default: "/run/keycloak.pid" - description: "TODO document argument" + description: "PID file path for service" type: "str" keycloak_bind_address: # line 34 of keycloak/defaults/main.yml default: "0.0.0.0" - description: "TODO document argument" + description: "Address for binding service ports" type: "str" keycloak_host: # line 35 of keycloak/defaults/main.yml default: "localhost" - description: "TODO document argument" + description: "Hostname for service" type: "str" keycloak_http_port: # line 36 of keycloak/defaults/main.yml default: 8080 - description: "TODO document argument" + description: "Listening HTTP port" type: "int" keycloak_https_port: # line 37 of keycloak/defaults/main.yml default: 8443 - description: "TODO document argument" + description: "Listening HTTPS port" type: "int" keycloak_ajp_port: # line 38 of keycloak/defaults/main.yml default: 8009 - description: "TODO document argument" + description: "Listening AJP port" type: "int" keycloak_jgroups_port: # line 39 of keycloak/defaults/main.yml default: 7600 - description: "TODO document argument" + description: "jgroups cluster tcp port" type: "int" keycloak_management_http_port: # line 40 of keycloak/defaults/main.yml default: 9990 - description: "TODO document argument" + description: "Management port (http)" type: "int" keycloak_management_https_port: # line 41 of keycloak/defaults/main.yml default: 9993 - description: "TODO document argument" + description: "Management port (https)" type: "int" keycloak_java_opts: # line 42 of keycloak/defaults/main.yml default: "-Xms1024m -Xmx2048m" - description: "TODO document argument" + description: "Additional JVM options" type: "str" keycloak_prefer_ipv4: # line 43 of keycloak/defaults/main.yml default: true - description: "TODO document argument" + description: "Prefer IPv4 stack and addresses for port binding" type: "bool" keycloak_ha_enabled: # line 46 of keycloak/defaults/main.yml @@ -179,52 +179,52 @@ argument_specs: keycloak_auth_realm: # line 52 of keycloak/defaults/main.yml default: "master" - description: "TODO document argument" + description: "Name for rest authentication realm" type: "str" keycloak_auth_client: # line 53 of keycloak/defaults/main.yml default: "admin-cli" - description: "TODO document argument" + description: "Authentication client for configuration REST calls" type: "str" keycloak_force_install: # line 55 of keycloak/defaults/main.yml default: false - description: "TODO document argument" + description: "Remove pre-existing versions of service" type: "bool" keycloak_modcluster_url: # line 58 of keycloak/defaults/main.yml default: "localhost" - description: "TODO document argument" + description: "URL for the modcluster reverse proxy" type: "str" keycloak_frontend_url: # line 59 of keycloak/defaults/main.yml default: "http://localhost" - description: "TODO document argument" + description: "Frontend URL for keycloak endpoints when a reverse proxy is used" type: "str" infinispan_user: # line 62 of keycloak/defaults/main.yml default: "supervisor" - description: "TODO document argument" + description: "Username for connecting to infinispan" type: "str" infinispan_pass: # line 63 of keycloak/defaults/main.yml default: "supervisor" - description: "TODO document argument" + description: "Password for connecting to infinispan" type: "str" infinispan_url: # line 64 of keycloak/defaults/main.yml default: "localhost" - description: "TODO document argument" + description: "URL for the infinispan remote-cache server" type: "str" infinispan_sasl_mechanism: # line 65 of keycloak/defaults/main.yml default: "SCRAM-SHA-512" - description: "TODO document argument" + description: "Authentication type to infinispan server" type: "str" infinispan_use_ssl: # line 66 of keycloak/defaults/main.yml default: false - description: "TODO document argument" + description: "Enable hotrod client TLS communication" type: "bool" infinispan_trust_store_path: # line 68 of keycloak/defaults/main.yml @@ -234,45 +234,45 @@ argument_specs: infinispan_trust_store_password: # line 69 of keycloak/defaults/main.yml default: "changeit" - description: "TODO document argument" + description: "Path to truststore containing infinispan server certificate" type: "str" keycloak_jdbc_engine: # line 72 of keycloak/defaults/main.yml default: "postgres" - description: "TODO document argument" + description: "Backend database flavour when db is enabled: [ postgres, mariadb ]" type: "str" keycloak_db_user: # line 74 of keycloak/defaults/main.yml default: "keycloak-user" - description: "TODO document argument" + description: "Username for connecting to database" type: "str" keycloak_db_pass: # line 75 of keycloak/defaults/main.yml default: "keycloak-pass" - description: "TODO document argument" + description: "Password for connecting to database" type: "str" keycloak_jdbc_url: # line 76 of keycloak/defaults/main.yml default: "{{ keycloak_default_jdbc[keycloak_jdbc_engine].url }}" - description: "TODO document argument" + description: "URL for connecting to backend database" type: "str" keycloak_jdbc_driver_version: # line 77 of keycloak/defaults/main.yml default: "{{ keycloak_default_jdbc[keycloak_jdbc_engine].version }}" - description: "TODO document argument" + description: "Version for the JDBC driver to download" type: "str" keycloak_admin_password: # line 4 of keycloak/vars/main.yml required: true - description: "TODO document argument" + description: "Password for the administration console user account" type: "str" keycloak_url: # line 12 of keycloak/vars/main.yml default: "http://{{ keycloak_host }}:{{ keycloak_http_port }}" - description: "TODO document argument" + description: "URL for configuration rest calls" type: "str" keycloak_management_url: # line 13 of keycloak/vars/main.yml default: "http://{{ keycloak_host }}:{{ keycloak_management_http_port }}" - description: "TODO document argument" + description: "URL for management console rest calls" type: "str" diff --git a/roles/keycloak_realm/README.md b/roles/keycloak_realm/README.md index cf1c317..e5d57b7 100644 --- a/roles/keycloak_realm/README.md +++ b/roles/keycloak_realm/README.md @@ -37,6 +37,7 @@ The following variables are available for creating clients: |`keycloak_client_default_roles` | List of default role name for clients | `[]` | |`keycloak_client_users` | List of user/role mappings for a client | `[]` | + The following variable are available for creating user federation: | Variable | Description | Default | @@ -52,14 +53,15 @@ Variable formats ```yaml - realm: name: - provider_id: - provider_type: < Provider Type, default is set to org.keycloak.storage.UserStorageProvider> - config: - mappers: + provider_id: + provider_type: + config: + mappers: ``` Refer to [docs](https://docs.ansible.com/ansible/latest/collections/community/general/keycloak_user_federation_module.html) for information on supported variables. + * `keycloak_clients`, a list of: ```yaml @@ -90,7 +92,8 @@ Refer to [docs](https://docs.ansible.com/ansible/latest/collections/community/ge realm: ``` -For a comprehensive example, refer to the [playbook](playbooks/keycloak.yml). +For a comprehensive example, refer to the [playbook](../../playbooks/keycloak_realm.yml). + Example Playbook ---------------- diff --git a/roles/keycloak_realm/defaults/main.yml b/roles/keycloak_realm/defaults/main.yml index bc9bea7..c47aea3 100644 --- a/roles/keycloak_realm/defaults/main.yml +++ b/roles/keycloak_realm/defaults/main.yml @@ -31,6 +31,7 @@ keycloak_auth_client: admin-cli # public_client: "{{ keycloak_client_public }}" # web_origins: "{{ keycloak_client_web_origins }}" # users: "{{ keycloak_client_users }}" +keycloak_clients: [] # list of roles to create in the client keycloak_client_default_roles: [] diff --git a/roles/keycloak_realm/meta/argument_specs.yml b/roles/keycloak_realm/meta/argument_specs.yml index ffbf18a..8f951b4 100644 --- a/roles/keycloak_realm/meta/argument_specs.yml +++ b/roles/keycloak_realm/meta/argument_specs.yml @@ -4,90 +4,90 @@ argument_specs: keycloak_host: # line 3 of keycloak_realm/defaults/main.yml default: "localhost" - description: "TODO document argument" + description: "hostname for rest calls" type: "str" keycloak_http_port: # line 4 of keycloak_realm/defaults/main.yml default: 8080 - description: "TODO document argument" + description: "HTTP port" type: "int" keycloak_https_port: # line 5 of keycloak_realm/defaults/main.yml default: 8443 - description: "TODO document argument" + description: "HTTPS port" type: "int" keycloak_management_http_port: # line 6 of keycloak_realm/defaults/main.yml default: 9990 - description: "TODO document argument" + description: "Management port" type: "int" keycloak_rhsso_enable: # line 7 of keycloak_realm/defaults/main.yml default: false - description: "TODO document argument" + description: "Enable Red Hat Single Sign-on" type: "bool" keycloak_admin_user: # line 10 of keycloak_realm/defaults/main.yml default: "admin" - description: "TODO document argument" + description: "Administration console user account" type: "str" keycloak_auth_realm: # line 11 of keycloak_realm/defaults/main.yml default: "master" - description: "TODO document argument" + description: "Name of the main authentication realm" type: "str" keycloak_auth_client: # line 12 of keycloak_realm/defaults/main.yml default: "admin-cli" - description: "TODO document argument" + description: "Authentication client for configuration REST calls" type: "str" keycloak_client_default_roles: # line 36 of keycloak_realm/defaults/main.yml default: "[]" - description: "TODO document argument" + description: "List of roles to configure as client default" type: "list" keycloak_client_public: # line 39 of keycloak_realm/defaults/main.yml default: true - description: "TODO document argument" + description: "Configure a public realm client" type: "bool" keycloak_client_web_origins: # line 42 of keycloak_realm/defaults/main.yml default: "+" - description: "TODO document argument" + description: "Web origins for realm client" type: "str" keycloak_client_users: # line 49 of keycloak_realm/defaults/main.yml default: "[]" - description: "TODO document argument" + description: "List of users to configure in the realm client" type: "list" keycloak_user_federation: # line 52 of keycloak_realm/defaults/main.yml default: "[]" - description: "TODO document argument" + description: "List of user federations to configure in the realm" type: "list" keycloak_admin_password: # line 5 of keycloak_realm/vars/main.yml required: true - description: "TODO document argument" + description: "Password for the administration console user account" type: "str" keycloak_realm: # line 8 of keycloak_realm/vars/main.yml required: true - description: "TODO document argument" + description: "Name of the realm to be configured" type: "str" keycloak_clients: # line 11 of keycloak_realm/vars/main.yml - required: true - description: "TODO document argument" - type: "str" + default: "[]" + description: "List of client declarations for the realm" + type: "list" keycloak_url: # line 14 of keycloak_realm/vars/main.yml default: "http://{{ keycloak_host }}:{{ keycloak_http_port }}" - description: "TODO document argument" + description: "URL for configuration rest calls" type: "str" keycloak_management_url: # line 15 of keycloak_realm/vars/main.yml default: "http://{{ keycloak_host }}:{{ keycloak_management_http_port }}" - description: "TODO document argument" + description: "URL for management console rest calls" type: "str" diff --git a/roles/keycloak_realm/vars/main.yml b/roles/keycloak_realm/vars/main.yml index 70133aa..f87e7f5 100644 --- a/roles/keycloak_realm/vars/main.yml +++ b/roles/keycloak_realm/vars/main.yml @@ -7,9 +7,6 @@ keycloak_admin_password: # name of the realm to create, this is a required variable keycloak_realm: -# keycloak realm clients, this is a required variable -keycloak_clients: - # other settings keycloak_url: "http://{{ keycloak_host }}:{{ keycloak_http_port }}" keycloak_management_url: "http://{{ keycloak_host }}:{{ keycloak_management_http_port }}"