From b0bedfc36345e95bad5af738044e50ae4b53d3b6 Mon Sep 17 00:00:00 2001 From: ansible-middleware-core Date: Mon, 1 Jun 2026 14:26:22 +0000 Subject: [PATCH] Update docs for main Signed-off-by: ansible-middleware-core --- main/CHANGELOG.html | 780 +++++----- main/README.html | 115 +- main/_sources/CHANGELOG.rst.txt | 5 + main/_sources/README.md.txt | 105 +- main/_sources/plugins/index.rst.txt | 27 + .../plugins/keycloak_authentication.rst.txt | 779 ++++++++++ .../keycloak_authentication_flow.rst.txt | 65 +- ...ak_authentication_required_actions.rst.txt | 772 ++++++++++ .../keycloak_authentication_v2.rst.txt | 1216 +++++++++++++++ ...keycloak_authz_authorization_scope.rst.txt | 637 ++++++++ .../keycloak_authz_custom_policy.rst.txt | 596 ++++++++ .../plugins/keycloak_authz_permission.rst.txt | 815 ++++++++++ .../keycloak_authz_permission_info.rst.txt | 637 ++++++++ main/_sources/plugins/keycloak_client.rst.txt | 311 ++-- .../keycloak_client_rolemapping.rst.txt | 761 ++++++++++ .../plugins/keycloak_client_rolescope.rst.txt | 595 ++++++++ .../plugins/keycloak_client_scope.rst.txt | 65 +- .../keycloak_clientscope_rolemappings.rst.txt | 579 ++++++++ .../plugins/keycloak_clientscope_type.rst.txt | 585 ++++++++ .../keycloak_clientsecret_info.rst.txt | 595 ++++++++ .../keycloak_clientsecret_regenerate.rst.txt | 591 ++++++++ .../plugins/keycloak_clienttemplate.rst.txt | 839 +++++++++++ .../plugins/keycloak_component.rst.txt | 656 +++++++++ .../plugins/keycloak_component_info.rst.txt | 555 +++++++ main/_sources/plugins/keycloak_group.rst.txt | 864 +++++++++++ .../keycloak_identity_provider.rst.txt | 1252 ++++++++++++++++ main/_sources/plugins/keycloak_realm.rst.txt | 723 ++++++++- .../plugins/keycloak_realm_info.rst.txt | 406 +++++ .../plugins/keycloak_realm_key.rst.txt | 1238 ++++++++++++++++ .../keycloak_realm_keys_metadata_info.rst.txt | 542 +++++++ .../keycloak_realm_localization.rst.txt | 692 +++++++++ .../keycloak_realm_rolemapping.rst.txt | 731 +++++++++ main/_sources/plugins/keycloak_role.rst.txt | 112 +- main/_sources/plugins/keycloak_user.rst.txt | 1133 ++++++++++++++ ...eycloak_user_execute_actions_email.rst.txt | 611 ++++++++ .../plugins/keycloak_user_federation.rst.txt | 185 ++- .../plugins/keycloak_user_rolemapping.rst.txt | 747 ++++++++++ .../plugins/keycloak_userprofile.rst.txt | 1306 +++++++++++++++++ main/index.html | 36 +- main/objects.inv | Bin 884 -> 2812 bytes main/plugins/index.html | 350 ++++- main/plugins/keycloak_authentication.html | 770 ++++++++++ .../plugins/keycloak_authentication_flow.html | 74 +- ...cloak_authentication_required_actions.html | 763 ++++++++++ main/plugins/keycloak_authentication_v2.html | 1208 +++++++++++++++ .../keycloak_authz_authorization_scope.html | 628 ++++++++ .../plugins/keycloak_authz_custom_policy.html | 587 ++++++++ main/plugins/keycloak_authz_permission.html | 806 ++++++++++ .../keycloak_authz_permission_info.html | 626 ++++++++ main/plugins/keycloak_client.html | 323 ++-- main/plugins/keycloak_client_rolemapping.html | 752 ++++++++++ main/plugins/keycloak_client_rolescope.html | 586 ++++++++ main/plugins/keycloak_client_scope.html | 74 +- .../keycloak_clientscope_rolemappings.html | 570 +++++++ main/plugins/keycloak_clientscope_type.html | 576 ++++++++ main/plugins/keycloak_clientsecret_info.html | 584 ++++++++ .../keycloak_clientsecret_regenerate.html | 582 ++++++++ main/plugins/keycloak_clienttemplate.html | 836 +++++++++++ main/plugins/keycloak_component.html | 647 ++++++++ main/plugins/keycloak_component_info.html | 544 +++++++ main/plugins/keycloak_group.html | 861 +++++++++++ main/plugins/keycloak_identity_provider.html | 1243 ++++++++++++++++ main/plugins/keycloak_realm.html | 737 +++++++++- main/plugins/keycloak_realm_info.html | 430 ++++++ main/plugins/keycloak_realm_key.html | 1235 ++++++++++++++++ .../keycloak_realm_keys_metadata_info.html | 531 +++++++ main/plugins/keycloak_realm_localization.html | 689 +++++++++ main/plugins/keycloak_realm_rolemapping.html | 722 +++++++++ main/plugins/keycloak_role.html | 126 +- main/plugins/keycloak_user.html | 1130 ++++++++++++++ .../keycloak_user_execute_actions_email.html | 603 ++++++++ main/plugins/keycloak_user_federation.html | 199 ++- main/plugins/keycloak_user_rolemapping.html | 738 ++++++++++ main/plugins/keycloak_userprofile.html | 1303 ++++++++++++++++ main/roles/index.html | 4 +- main/searchindex.js | 2 +- 76 files changed, 44661 insertions(+), 1037 deletions(-) create mode 100644 main/_sources/plugins/keycloak_authentication.rst.txt create mode 100644 main/_sources/plugins/keycloak_authentication_required_actions.rst.txt create mode 100644 main/_sources/plugins/keycloak_authentication_v2.rst.txt create mode 100644 main/_sources/plugins/keycloak_authz_authorization_scope.rst.txt create mode 100644 main/_sources/plugins/keycloak_authz_custom_policy.rst.txt create mode 100644 main/_sources/plugins/keycloak_authz_permission.rst.txt create mode 100644 main/_sources/plugins/keycloak_authz_permission_info.rst.txt create mode 100644 main/_sources/plugins/keycloak_client_rolemapping.rst.txt create mode 100644 main/_sources/plugins/keycloak_client_rolescope.rst.txt create mode 100644 main/_sources/plugins/keycloak_clientscope_rolemappings.rst.txt create mode 100644 main/_sources/plugins/keycloak_clientscope_type.rst.txt create mode 100644 main/_sources/plugins/keycloak_clientsecret_info.rst.txt create mode 100644 main/_sources/plugins/keycloak_clientsecret_regenerate.rst.txt create mode 100644 main/_sources/plugins/keycloak_clienttemplate.rst.txt create mode 100644 main/_sources/plugins/keycloak_component.rst.txt create mode 100644 main/_sources/plugins/keycloak_component_info.rst.txt create mode 100644 main/_sources/plugins/keycloak_group.rst.txt create mode 100644 main/_sources/plugins/keycloak_identity_provider.rst.txt create mode 100644 main/_sources/plugins/keycloak_realm_info.rst.txt create mode 100644 main/_sources/plugins/keycloak_realm_key.rst.txt create mode 100644 main/_sources/plugins/keycloak_realm_keys_metadata_info.rst.txt create mode 100644 main/_sources/plugins/keycloak_realm_localization.rst.txt create mode 100644 main/_sources/plugins/keycloak_realm_rolemapping.rst.txt create mode 100644 main/_sources/plugins/keycloak_user.rst.txt create mode 100644 main/_sources/plugins/keycloak_user_execute_actions_email.rst.txt create mode 100644 main/_sources/plugins/keycloak_user_rolemapping.rst.txt create mode 100644 main/_sources/plugins/keycloak_userprofile.rst.txt create mode 100644 main/plugins/keycloak_authentication.html create mode 100644 main/plugins/keycloak_authentication_required_actions.html create mode 100644 main/plugins/keycloak_authentication_v2.html create mode 100644 main/plugins/keycloak_authz_authorization_scope.html create mode 100644 main/plugins/keycloak_authz_custom_policy.html create mode 100644 main/plugins/keycloak_authz_permission.html create mode 100644 main/plugins/keycloak_authz_permission_info.html create mode 100644 main/plugins/keycloak_client_rolemapping.html create mode 100644 main/plugins/keycloak_client_rolescope.html create mode 100644 main/plugins/keycloak_clientscope_rolemappings.html create mode 100644 main/plugins/keycloak_clientscope_type.html create mode 100644 main/plugins/keycloak_clientsecret_info.html create mode 100644 main/plugins/keycloak_clientsecret_regenerate.html create mode 100644 main/plugins/keycloak_clienttemplate.html create mode 100644 main/plugins/keycloak_component.html create mode 100644 main/plugins/keycloak_component_info.html create mode 100644 main/plugins/keycloak_group.html create mode 100644 main/plugins/keycloak_identity_provider.html create mode 100644 main/plugins/keycloak_realm_info.html create mode 100644 main/plugins/keycloak_realm_key.html create mode 100644 main/plugins/keycloak_realm_keys_metadata_info.html create mode 100644 main/plugins/keycloak_realm_localization.html create mode 100644 main/plugins/keycloak_realm_rolemapping.html create mode 100644 main/plugins/keycloak_user.html create mode 100644 main/plugins/keycloak_user_execute_actions_email.html create mode 100644 main/plugins/keycloak_user_rolemapping.html create mode 100644 main/plugins/keycloak_userprofile.html diff --git a/main/CHANGELOG.html b/main/CHANGELOG.html index c7e378d..a60a755 100644 --- a/main/CHANGELOG.html +++ b/main/CHANGELOG.html @@ -51,54 +51,55 @@
  • Role Index
  • Changelog @@ -295,248 +296,249 @@
    -

    middleware_automation.keycloak Release Notes

    +

    middleware_automation.keycloak Release Notes

    This changelog describes changes after version 0.2.6.

    -

    v3.0.7-devel

    +

    v3.0.7-devel

    +
    +

    Major Changes

    +
      +

    • Migrate Keycloak modules from the community.general collection to Keycloak collection. #341

      • +
    +
    -

    Minor Changes

    +

    Minor Changes

    -

    Bugfixes

    +

    Bugfixes

    • Fix molecule tests #339

    -

    v3.0.6

    -
    -

    Major Changes

    +

    v3.0.6

    +
    +

    Major Changes

    • AMW-540 Fix the upstream collection requirements with common v1.2.4 #337

    -

    v3.0.5

    -
    -

    Minor Changes

    +

    v3.0.5

    +
    +

    Minor Changes

    • AMW-528 Deployment fails in keycloak_quarkus due to missing escalation variables #335

    -

    v3.0.4

    -
    -

    Major Changes

    +

    v3.0.4

    +
    +

    Major Changes

    • AMW-467 Download keycloak binary from password protected HTTP location #321

    • v26.4.x compability #317

    -
    -

    Minor Changes

    +
    +

    Minor Changes

    • AMW-518 Validating arguments against arg spec ‘main’ fails unexpectedly. #324

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Removing parseable from lint file as Additional properties are not allowed #319

    -

    v3.0.3

    -
    -

    Major Changes

    +

    v3.0.3

    +
    +

    Major Changes

    • Update to keycloak 26.3.0 #293

    • ansible-core 2.19 compatibility #310

    -
    -

    Minor Changes

    +
    +

    Minor Changes

    • Allow to install provider jars from remote paths #303

    • Declared proxy_mode as deprecated, updated quarkus and realm readme #306

    • Fix config_key_store_file description to match variable name #308

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • keycloak collection CI label is showing no status #312

    • keycloak_realm: allow secret in keycloak_clients #304

      • @@ -626,9 +634,9 @@
    -

    v3.0.2

    -
    -

    Minor Changes

    +

    v3.0.2

    +
    +

    Minor Changes

    • New checksum property for keycloak_quarkus_providers #280

    • New parameter to set the jgroups host IP address #281

      • @@ -636,8 +644,8 @@

    • Update keycloak/RHBK to v26.2.4 #283

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Fix keycloak_quarkus_force_install parameter being ignored by install #296

    • Fix alternate download location being ignored (JBossNeworkAPI always used) #298

      • @@ -648,39 +656,39 @@
    -

    v3.0.1

    -
    -

    Minor Changes

    +

    v3.0.1

    +
    +

    Minor Changes

    • Version update to 26.0.8 / rhbk 26.0.11 #277

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Trigger rebuild handler on envvars file change #276

    -

    v3.0.0

    -
    -

    Minor Changes

    +

    v3.0.0

    +
    +

    Minor Changes

    • Add theme cache invalidation handler #252

    • keycloak_realm: change url variables to defaults #268

    -

    Breaking Changes / Porting Guide

    +

    Breaking Changes / Porting Guide

    • Bump major and ansible-core versions #266

    • Rename parameters to follow upstream #270

    • Update for keycloak v26 #254

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Access token lifespan is too short for ansible run #251

    • Load environment vars during kc rebuild #274

      • @@ -689,47 +697,47 @@
    -

    New Modules

    +

    New Modules

    • middleware_automation.keycloak.keycloak_realm - Allows administration of Keycloak realm via Keycloak API

    -

    v2.4.3

    -
    -

    Minor Changes

    +

    v2.4.3

    +
    +

    Minor Changes

    • Update keycloak to 24.0.5 #241

    -

    v2.4.2

    -
    -

    Minor Changes

    +

    v2.4.2

    +
    +

    Minor Changes

    • New parameter keycloak_quarkus_download_path #239

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Add wait_for_port number parameter #237

    -

    v2.4.1

    +

    v2.4.1

    -

    Release Summary

    +

    Release Summary

    Internal release, documentation or test changes only.

    -

    v2.4.0

    -
    -

    Major Changes

    +

    v2.4.0

    +
    +

    Major Changes

    • Enable by default health check on restart #234

    • Update minimum ansible-core version > 2.15 #232

      • @@ -737,16 +745,16 @@
    -

    v2.3.0

    -
    -

    Major Changes

    +

    v2.3.0

    +
    +

    Major Changes

    • Allow for custom providers hosted on maven repositories #223

    • Restart handler strategy behaviour #231

    -
    -

    Minor Changes

    +
    +

    Minor Changes

    • Add support for policy files #225

    • Allow to add extra custom env vars in sysconfig file #229

      • @@ -755,52 +763,52 @@

    • proxy-header enhancement #227

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • kc.sh build uses configured jdk #211

    -

    v2.2.2

    -
    -

    Minor Changes

    +

    v2.2.2

    +
    +

    Minor Changes

    • Copying of key material for TLS configuration #210

    • Validate certs parameter for JDBC driver downloads #207

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Turn off controller privilege escalation #209

    -

    v2.2.1

    -
    -

    Release Summary

    +

    v2.2.1

    +
    +

    Release Summary

    Internal release, documentation or test changes only.

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • JDBC provider: fix clause in argument validation #204

    -

    v2.2.0

    -
    -

    Major Changes

    +

    v2.2.0

    +
    +

    Major Changes

    • Support java keystore for configuration of sensitive options #189

    -
    -

    Minor Changes

    +
    +

    Minor Changes

    • Add wait_for_port and wait_for_log systemd unit logic #199

    • Customize jdbc driver downloads, optional authentication #202

      • @@ -813,24 +821,24 @@
    -

    v2.1.2

    -
    -

    Release Summary

    +

    v2.1.2

    +
    +

    Release Summary

    Internal release, documentation or test changes only.

    -

    v2.1.1

    -
    -

    Minor Changes

    +

    v2.1.1

    +
    +

    Minor Changes

    • Add reverse proxy_headers config, supersedes proxy_mode #187

    • Debian/Ubuntu compatibility #178

    • Use keycloak_realm as default for sub-entities #180

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Fix permissions on controller-side downloaded artifacts #184

    • JVM args moved to JAVA_OPTS envvar (instead of JAVA_OPTS_APPEND) #186

      • @@ -840,46 +848,46 @@
    -

    v2.1.0

    -
    -

    Major Changes

    +

    v2.1.0

    +
    +

    Major Changes

    • Implement infinispan TCPPING discovery protocol #159

    -
    -

    Minor Changes

    +
    +

    Minor Changes

    • Set enable-recovery when xa transactions are enabled #167

    • keycloak_quarkus: Allow configuring log rotate options in quarkus configuration #161

    • keycloak_quarkus: sticky-session for infinispan routes #163

    -
    -

    Breaking Changes / Porting Guide

    +
    +

    Breaking Changes / Porting Guide

    • keycloak_quarkus: renamed infinispan host list configuration #157

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • keycloak_quarkus: fix custom JAVA_HOME parameter name #171

    -

    v2.0.2

    -
    -

    Minor Changes

    +

    v2.0.2

    +
    +

    Minor Changes

    • keycloak_quarkus: Add support for sqlserver jdbc driver #148

    • keycloak_quarkus: allow configuration of hostname-strict-backchannel #152

    • keycloak_quarkus: systemd restart behavior #145

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • keycloak_quarkus: Use keycloak_quarkus_java_opts #154

    • keycloak_quarkus: allow ports <1024 (e.g. :443) in systemd unit #150

      • @@ -887,32 +895,32 @@
    -

    v2.0.1

    -
    -

    Minor Changes

    +

    v2.0.1

    +
    +

    Minor Changes

    • keycloak_quarkus: add hostname-strict parameter #139

    • keycloak_quarkus: update to version 23.0.1 #133

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • keycloak_quarkus: template requires lowercase boolean values #138

    -

    v2.0.0

    -
    -

    Minor Changes

    +

    v2.0.0

    +
    +

    Minor Changes

    • Add new parameter for port offset configuration #124

    • Update Keycloak to version 22.0.5 #122

    -
    -

    Breaking Changes / Porting Guide

    +
    +

    Breaking Changes / Porting Guide

    • Add support for more http-related configs #115

    • Update minimum ansible-core version > 2.14 #119

      • @@ -921,39 +929,39 @@
    -

    v1.3.0

    -
    -

    Major Changes

    +

    v1.3.0

    +
    +

    Major Changes

    • Run service as keycloak_service_user #106

    -
    -

    Minor Changes

    +
    +

    Minor Changes

    • keycloak_quarkus: Update Keycloak to version 22.0.3 #112

    • keycloak_quarkus: fix admin console redirect when running locally #111

    • keycloak_quarkus: skip proxy config if keycloak_quarkus_proxy_mode is none #109

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • keycloak_quarkus: fix validation failure upon port configuration change #113

    -

    v1.2.8

    -
    -

    Minor Changes

    +

    v1.2.8

    +
    +

    Minor Changes

    • keycloak_quarkus: set openjdk 17 as default #103

    • keycloak_quarkus: update to version 22.0.1 #107

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Fix incorrect checks for keycloak_jgroups_subnet #98

    • Undefine keycloak_db_valid_conn_sql default #91

      • @@ -962,9 +970,9 @@
    -

    v1.2.7

    -
    -

    Minor Changes

    +

    v1.2.7

    +
    +

    Minor Changes

    • Allow to override jgroups subnet #93

    • keycloak-quarkus: update keycloakx to v21.1.1 #92

      • @@ -972,26 +980,26 @@
    -

    v1.2.6

    -
    -

    Minor Changes

    +

    v1.2.6

    +
    +

    Minor Changes

    • Add profile features enabling/disabling #87

    • Improve service restart behavior configuration #88

    • Update default xa_datasource_class value for mariadb jdbc configuration #89

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Handle WFLYCTL0117 when background validation millis is 0 #90

    -

    v1.2.5

    -
    -

    Minor Changes

    +

    v1.2.5

    +
    +

    Minor Changes

    • Add configuration for database connection pool validation #85

    • Allow to configure administration endpoint URL #86

      • @@ -1001,16 +1009,16 @@
    -

    v1.2.4

    -
    -

    Minor Changes

    +

    v1.2.4

    +
    +

    Minor Changes

    • Add sqlserver to keycloak role jdbc configurations #78

    • Add configurability for XA transactions #73

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Fix deprecation warning for ipaddr #77

    • Fix undefined facts when offline patching sso #71

      • @@ -1018,30 +1026,30 @@
    -

    v1.2.1

    -
    -

    Minor Changes

    +

    v1.2.1

    +
    +

    Minor Changes

    • Allow to setup keycloak HA cluster without remote cache store #68

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Pass attributes to realm clients #69

    -

    v1.2.0

    -
    -

    Major Changes

    +

    v1.2.0

    +
    +

    Major Changes

    • Provide config for multiple modcluster proxies #60

    -
    -

    Minor Changes

    +
    +

    Minor Changes

    • Allow to configure TCPPING for cluster discovery #62

    • Drop community.general from dependencies #61

      • @@ -1051,18 +1059,18 @@
    -

    v1.1.1

    -
    -

    Bugfixes

    +

    v1.1.1

    +
    +

    Bugfixes

    • keycloak-quarkus: fix cache-config-file path in keycloak.conf.j2 template #53

    -

    v1.1.0

    -
    -

    Minor Changes

    +

    v1.1.0

    +
    +

    Minor Changes

    • Update keycloak to 18.0.2 - sso to 7.6.1 #46

    • Variable keycloak_no_log controls ansible no_log parameter (for debugging purposes) #47

      • @@ -1070,38 +1078,38 @@

    • keycloak_quarkus: variable to enable development mode #45

    -
    -

    Breaking Changes / Porting Guide

    +
    +

    Breaking Changes / Porting Guide

    • Rename variables from infinispan_ prefix to keycloak_infinispan_ #42

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • keycloak_quarkus: fix /var/log/keycloak symlink to keycloak log directory #44

    -

    v1.0.7

    -
    -

    Breaking Changes / Porting Guide

    +

    v1.0.7

    +
    +

    Breaking Changes / Porting Guide

    • keycloak_quarkus: use absolute path for certificate files #39

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • keycloak_quarkus: use become for tasks that will otherwise fail #38

    -

    v1.0.6

    -
    -

    Bugfixes

    +

    v1.0.6

    +
    +

    Bugfixes

    • keycloak_quarkus: add selected java to PATH in systemd unit #34

    • keycloak_quarkus: set logfile path correctly under keycloak home #35

      • @@ -1109,81 +1117,81 @@
    -

    v1.0.5

    -
    -

    Minor Changes

    +

    v1.0.5

    +
    +

    Minor Changes

    • Update config options: keycloak and quarkus #32

    -

    v1.0.4

    -
    -

    Release Summary

    +

    v1.0.4

    +
    +

    Release Summary

    Internal release, documentation or test changes only.

    -

    v1.0.3

    -
    -

    Major Changes

    +

    v1.0.3

    +
    +

    Major Changes

    • New role for installing keycloak >= 17.0.0 (quarkus) #29

    -
    -

    Minor Changes

    +
    +

    Minor Changes

    • Add keycloak_config_override_template parameter for passing a custom xml config template #30

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Make sure systemd unit starts with selected java JVM #31

    -

    v1.0.2

    -
    -

    Minor Changes

    +

    v1.0.2

    +
    +

    Minor Changes

    • Make keycloak_admin_password a default with assert (was: role variable) #26

    • Simplify dependency install logic and reduce play execution time #19

    -
    -

    Bugfixes

    +
    +

    Bugfixes

    • Set keycloak_frontend_url default according to other defaults #25

    -

    v1.0.1

    -
    -

    Release Summary

    +

    v1.0.1

    +
    +

    Release Summary

    Minor enhancements, bug and documentation fixes.

    -
    -

    Major Changes

    +
    +

    Major Changes

    • Apply latest cumulative patch of RH-SSO automatically when new parameter keycloak_rhsso_apply_patches is true #18

    -
    -

    Minor Changes

    +
    +

    Minor Changes

    • Clustered installs now perform database initialization on first node to avoid locking issues #17

    -

    v1.0.0

    -
    -

    Release Summary

    +

    v1.0.0

    +
    +

    Release Summary

    This is the first stable release of the middleware_automation.keycloak collection.

    diff --git a/main/README.html b/main/README.html index 8ad97c6..2bd35e7 100644 --- a/main/README.html +++ b/main/README.html @@ -55,17 +55,17 @@
  • Usage
      -
    • Install Playbook
        +
      • Install Keycloak
        • -
      • Example installation command
        • +
      • Configure with roles
        • -
      • Configuration
      • Support
        • @@ -176,28 +176,54 @@

        Included modules

        +

        All Keycloak administration modules from community.general are provided in this collection for Keycloak 17+ (Quarkus). Use auth_keycloak_url without the legacy /auth context path (for example http://localhost:8080). Set keycloak_context to /auth only when automating WildFly-based Keycloak with the keycloak role.

          -

        • keycloak_realm: module for managing Keycloak realms (create/update/delete).

          • -

        • keycloak_client: module for managing Keycloak clients (create/update/delete).

          • -

        • keycloak_role: module for managing Keycloak roles — realm roles and client roles (create/update/delete).

          • -

        • keycloak_user_federation: module for managing user federations such as LDAP/AD (create/update/delete).

          • -

        • keycloak_client_scope: module for managing client scopes and protocol mappers (create/update/delete).

          • -

        • keycloak_authentication_flow: module for managing authentication flows and execution steps (create/delete, copy existing flows).

          • +

        • keycloak_authentication: manage authentication flows and executions using Keycloak Admin REST API.

          • +

        • keycloak_authentication_flow: manage custom authentication flows and flow executions.

          • +

        • keycloak_authentication_required_actions: manage required actions available in realm authentication.

          • +

        • keycloak_authentication_v2: manage authentication flows with newer Keycloak API handling.

          • +

        • keycloak_authz_authorization_scope: manage authorization scopes for a client resource server.

          • +

        • keycloak_authz_custom_policy: manage custom authorization policies for a client resource server.

          • +

        • keycloak_authz_permission: manage authorization permissions for a client resource server.

          • +

        • keycloak_authz_permission_info: retrieve authorization permission information for a client resource server.

          • +

        • keycloak_client: manage Keycloak clients (create/update/delete).

          • +

        • keycloak_client_rolemapping: manage client role mappings for users and groups.

          • +

        • keycloak_client_rolescope: manage client role scope mappings.

          • +

        • keycloak_client_scope: manage client scopes and protocol mappers (replaces community.general.keycloak_clientscope).

          • +

        • keycloak_clientscope_type: manage default and optional client scope assignments.

          • +

        • keycloak_clientsecret_info: retrieve client secret information.

          • +

        • keycloak_clientsecret_regenerate: regenerate a client secret.

          • +

        • keycloak_clienttemplate: manage legacy client templates.

          • +

        • keycloak_component: manage realm components.

          • +

        • keycloak_component_info: retrieve realm component information.

          • +

        • keycloak_group: manage realm groups and subgroups.

          • +

        • keycloak_identity_provider: manage identity provider instances and configuration.

          • +

        • keycloak_realm: manage realms (create/update/delete).

          • +

        • keycloak_realm_info: retrieve realm information.

          • +

        • keycloak_realm_key: manage realm key providers.

          • +

        • keycloak_realm_keys_metadata_info: retrieve realm keys metadata.

          • +

        • keycloak_realm_localization: manage realm localization texts.

          • +

        • keycloak_realm_rolemapping: manage realm role mappings for users and groups.

          • +

        • keycloak_role: manage realm and client roles.

          • +

        • keycloak_user: manage users (create/update/delete).

          • +

        • keycloak_user_execute_actions_email: trigger execute-actions emails for users.

          • +

        • keycloak_user_federation: manage user federation providers (for example LDAP/AD).

          • +

        • keycloak_user_rolemapping: manage user role mappings.

          • +

        • keycloak_userprofile: manage user profile configuration.

        Usage

        -
        -

        Install Playbook

        - +

        The collection provides roles to install Keycloak and modules to manage realms, clients, users, and related settings via the Keycloak Admin REST API.

        +

        For Quarkus-based Keycloak (17+), set auth_keycloak_url to the server root URL without the legacy /auth path, for example http://localhost:8080. When using the legacy keycloak role with WildFly-based Keycloak, set keycloak_context to /auth in the keycloak_realm role.

        +
        +

        Install Keycloak

        -

        Both playbooks include the keycloak role, with different settings, as described in the following sections.

        -

        For full service configuration details, refer to the keycloak role README.

        - +

        For full service configuration details, refer to the keycloak_quarkus role README or the keycloak role README.

        Install from controller node (offline)

        Making the keycloak zip archive available to the playbook working directory, and setting keycloak_offline_install to true, allows to skip @@ -212,15 +238,14 @@ the download tasks. The local path for the archive does match the downloaded arc

        Install from alternate sources (like corporate Nexus, artifactory, proxy, etc)

        It is possible to perform downloads from alternate sources, using the keycloak_download_url variable; make sure the final downloaded filename matches with the source filename (ie. keycloak-legacy-x.y.zip or rh-sso-x.y.z-server-dist.zip).

        -
        -

        Example installation command

        -

        Execute the following command from the source root directory

        -
        ansible-playbook -i <ansible_hosts> -e @rhn-creds.yml playbooks/keycloak.yml -e keycloak_admin_password=<changeme>
+
        Example installation command
        
+
        Execute the following command from the source root directory:
        
+
        ansible-playbook -i <ansible_hosts> playbooks/keycloak_quarkus.yml -e keycloak_quarkus_bootstrap_admin_password=<changeme>
 
        
 
        
 
          
-
        • keycloak_admin_password Password for the administration console user account.
          • 
+
        • keycloak_quarkus_bootstrap_admin_password password for the administration console user account.
          • 
 
        • ansible_hosts is the inventory, below is an example inventory for deploying to localhost
          
 
          [keycloak]
 localhost ansible_connection=local
@@ -231,10 +256,8 @@ the download tasks. The local path for the archive does match the downloaded arc
 
          Note: when deploying clustered configurations, all hosts belonging to the cluster must be present in ansible_play_batch; ie. they must be targeted by the same ansible-playbook execution.
        -
        -

        Configuration

        -
        -

        Config Playbooks

        +
        +

        Configure with roles

        -

        Example configuration command

        +

        Example configuration command

        Execute the following command from the source root directory:

        ansible-playbook -i <ansible_hosts> playbooks/keycloak_realm.yml -e keycloak_admin_password=<changeme> -e keycloak_realm=test
        @@ -267,6 +288,36 @@ the download tasks. The local path for the archive does match the downloaded arc
        +
        +

        Configure with modules

        +

        Module playbooks target an already running Keycloak instance. All modules use the middleware_automation.keycloak collection namespace.

        + +

        Example task using shared authentication defaults:

        +
        - hosts: localhost
+  module_defaults:
+    group/middleware_automation.keycloak.keycloak:
+      auth_keycloak_url: http://localhost:8080
+      auth_realm: master
+      auth_username: admin
+      auth_password: "{{ keycloak_admin_password }}"
+  tasks:
+    - name: Create a user in a realm
+      middleware_automation.keycloak.keycloak_user:
+        realm: TestRealm
+        username: testuser
+        first_name: Test
+        last_name: User
+        email: testuser@example.com
+        enabled: true
+        state: present
+
        +
        +

        When migrating from community.general, replace the collection prefix in playbooks (for example community.general.keycloak_user becomes middleware_automation.keycloak.keycloak_user) and use keycloak_client_scope instead of keycloak_clientscope.

        +
        +

        Support

        diff --git a/main/_sources/CHANGELOG.rst.txt b/main/_sources/CHANGELOG.rst.txt index 6fc4f4e..41c287f 100644 --- a/main/_sources/CHANGELOG.rst.txt +++ b/main/_sources/CHANGELOG.rst.txt @@ -9,6 +9,11 @@ This changelog describes changes after version 0.2.6. v3.0.7-devel ============ +Major Changes +------------- + +- Migrate Keycloak modules from the community.general collection to Keycloak collection. `#341 `_ + Minor Changes ------------- diff --git a/main/_sources/README.md.txt b/main/_sources/README.md.txt index e481cd2..9d44836 100644 --- a/main/_sources/README.md.txt +++ b/main/_sources/README.md.txt @@ -57,25 +57,53 @@ A requirement file is provided to install: ### Included modules -* `keycloak_realm`: module for managing Keycloak realms (create/update/delete). -* `keycloak_client`: module for managing Keycloak clients (create/update/delete). -* `keycloak_role`: module for managing Keycloak roles — realm roles and client roles (create/update/delete). -* `keycloak_user_federation`: module for managing user federations such as LDAP/AD (create/update/delete). -* `keycloak_client_scope`: module for managing client scopes and protocol mappers (create/update/delete). -* `keycloak_authentication_flow`: module for managing authentication flows and execution steps (create/delete, copy existing flows). +All Keycloak administration modules from `community.general` are provided in this collection for Keycloak 17+ (Quarkus). Use `auth_keycloak_url` without the legacy `/auth` context path (for example `http://localhost:8080`). Set `keycloak_context` to `/auth` only when automating WildFly-based Keycloak with the `keycloak` role. + +* `keycloak_authentication`: manage authentication flows and executions using Keycloak Admin REST API. +* `keycloak_authentication_flow`: manage custom authentication flows and flow executions. +* `keycloak_authentication_required_actions`: manage required actions available in realm authentication. +* `keycloak_authentication_v2`: manage authentication flows with newer Keycloak API handling. +* `keycloak_authz_authorization_scope`: manage authorization scopes for a client resource server. +* `keycloak_authz_custom_policy`: manage custom authorization policies for a client resource server. +* `keycloak_authz_permission`: manage authorization permissions for a client resource server. +* `keycloak_authz_permission_info`: retrieve authorization permission information for a client resource server. +* `keycloak_client`: manage Keycloak clients (create/update/delete). +* `keycloak_client_rolemapping`: manage client role mappings for users and groups. +* `keycloak_client_rolescope`: manage client role scope mappings. +* `keycloak_client_scope`: manage client scopes and protocol mappers (replaces `community.general.keycloak_clientscope`). +* `keycloak_clientscope_type`: manage default and optional client scope assignments. +* `keycloak_clientsecret_info`: retrieve client secret information. +* `keycloak_clientsecret_regenerate`: regenerate a client secret. +* `keycloak_clienttemplate`: manage legacy client templates. +* `keycloak_component`: manage realm components. +* `keycloak_component_info`: retrieve realm component information. +* `keycloak_group`: manage realm groups and subgroups. +* `keycloak_identity_provider`: manage identity provider instances and configuration. +* `keycloak_realm`: manage realms (create/update/delete). +* `keycloak_realm_info`: retrieve realm information. +* `keycloak_realm_key`: manage realm key providers. +* `keycloak_realm_keys_metadata_info`: retrieve realm keys metadata. +* `keycloak_realm_localization`: manage realm localization texts. +* `keycloak_realm_rolemapping`: manage realm role mappings for users and groups. +* `keycloak_role`: manage realm and client roles. +* `keycloak_user`: manage users (create/update/delete). +* `keycloak_user_execute_actions_email`: trigger execute-actions emails for users. +* `keycloak_user_federation`: manage user federation providers (for example LDAP/AD). +* `keycloak_user_rolemapping`: manage user role mappings. +* `keycloak_userprofile`: manage user profile configuration. ## Usage +The collection provides roles to install Keycloak and modules to manage realms, clients, users, and related settings via the [Keycloak Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/index.html). -### Install Playbook - -* [`playbooks/keycloak_quarkus.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_quarkus.yml) installs keycloak >= 17 based on the defined variables (using most defaults). -* [`playbooks/keycloak.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak.yml) installs keycloak legacy based on the defined variables (using most defaults). +For Quarkus-based Keycloak (17+), set `auth_keycloak_url` to the server root URL without the legacy `/auth` path, for example `http://localhost:8080`. When using the legacy `keycloak` role with WildFly-based Keycloak, set `keycloak_context` to `/auth` in the `keycloak_realm` role. -Both playbooks include the `keycloak` role, with different settings, as described in the following sections. +### Install Keycloak -For full service configuration details, refer to the [keycloak role README](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak/README.md). - +* [`playbooks/keycloak_quarkus.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_quarkus.yml) installs Keycloak >= 17 using the `keycloak_quarkus` role. +* [`playbooks/keycloak.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak.yml) installs legacy Keycloak (<= 19) using the `keycloak` role. + +For full service configuration details, refer to the [keycloak_quarkus role README](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_quarkus/README.md) or the [keycloak role README](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak/README.md). #### Install from controller node (offline) @@ -96,15 +124,15 @@ keycloak_offline_install: true It is possible to perform downloads from alternate sources, using the `keycloak_download_url` variable; make sure the final downloaded filename matches with the source filename (ie. keycloak-legacy-x.y.zip or rh-sso-x.y.z-server-dist.zip). -### Example installation command +#### Example installation command -Execute the following command from the source root directory +Execute the following command from the source root directory: -``` -ansible-playbook -i -e @rhn-creds.yml playbooks/keycloak.yml -e keycloak_admin_password= +```bash +ansible-playbook -i playbooks/keycloak_quarkus.yml -e keycloak_quarkus_bootstrap_admin_password= ``` -- `keycloak_admin_password` Password for the administration console user account. +- `keycloak_quarkus_bootstrap_admin_password` password for the administration console user account. - `ansible_hosts` is the inventory, below is an example inventory for deploying to localhost ``` @@ -114,19 +142,15 @@ ansible-playbook -i -e @rhn-creds.yml playbooks/keycloak.yml -e Note: when deploying clustered configurations, all hosts belonging to the cluster must be present in `ansible_play_batch`; ie. they must be targeted by the same ansible-playbook execution. +### Configure with roles -## Configuration - - -### Config Playbooks * [`playbooks/keycloak_realm.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_realm.yml) creates or updates provided realm, user federation(s), client(s), client role(s) and client user(s). * [`playbooks/keycloak_realm_client.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_realm_client.yml) creates a realm with clients, roles and users using the `keycloak_realm` role. -* [`playbooks/keycloak_client_scope.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_client_scope.yml) creates a client scope with protocol mappers using the `keycloak_client_scope` module. -* [`playbooks/keycloak_authentication_flow.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_authentication_flow.yml) creates a custom authentication flow with execution steps using the `keycloak_authentication_flow` module. +* [`playbooks/keycloak_federation.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_federation.yml) configures user federation providers. -### Example configuration command +#### Example configuration command Execute the following command from the source root directory: @@ -146,6 +170,37 @@ ansible-playbook -i playbooks/keycloak_realm.yml -e keycloak_adm For full configuration details, refer to the [keycloak_realm role README](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_realm/README.md). +### Configure with modules + +Module playbooks target an already running Keycloak instance. All modules use the `middleware_automation.keycloak` collection namespace. + +* [`playbooks/keycloak_client_scope.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_client_scope.yml) creates a client scope with protocol mappers using the `keycloak_client_scope` module. +* [`playbooks/keycloak_authentication_flow.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_authentication_flow.yml) creates a custom authentication flow with execution steps using the `keycloak_authentication_flow` module. + +Example task using shared authentication defaults: + +```yaml +- hosts: localhost + module_defaults: + group/middleware_automation.keycloak.keycloak: + auth_keycloak_url: http://localhost:8080 + auth_realm: master + auth_username: admin + auth_password: "{{ keycloak_admin_password }}" + tasks: + - name: Create a user in a realm + middleware_automation.keycloak.keycloak_user: + realm: TestRealm + username: testuser + first_name: Test + last_name: User + email: testuser@example.com + enabled: true + state: present +``` + +When migrating from `community.general`, replace the collection prefix in playbooks (for example `community.general.keycloak_user` becomes `middleware_automation.keycloak.keycloak_user`) and use `keycloak_client_scope` instead of `keycloak_clientscope`. + ## Support diff --git a/main/_sources/plugins/index.rst.txt b/main/_sources/plugins/index.rst.txt index 2583b6d..a378996 100644 --- a/main/_sources/plugins/index.rst.txt +++ b/main/_sources/plugins/index.rst.txt @@ -5,10 +5,37 @@ Plugin Index :caption: modules plugins :maxdepth: 0 + keycloak_authentication keycloak_authentication_flow + keycloak_authentication_required_actions + keycloak_authentication_v2 + keycloak_authz_authorization_scope + keycloak_authz_custom_policy + keycloak_authz_permission + keycloak_authz_permission_info keycloak_client + keycloak_client_rolemapping + keycloak_client_rolescope keycloak_client_scope + keycloak_clientscope_rolemappings + keycloak_clientscope_type + keycloak_clientsecret_info + keycloak_clientsecret_regenerate + keycloak_clienttemplate + keycloak_component + keycloak_component_info + keycloak_group + keycloak_identity_provider keycloak_realm + keycloak_realm_info + keycloak_realm_key + keycloak_realm_keys_metadata_info + keycloak_realm_localization + keycloak_realm_rolemapping keycloak_role + keycloak_user + keycloak_user_execute_actions_email keycloak_user_federation + keycloak_user_rolemapping + keycloak_userprofile diff --git a/main/_sources/plugins/keycloak_authentication.rst.txt b/main/_sources/plugins/keycloak_authentication.rst.txt new file mode 100644 index 0000000..81f473f --- /dev/null +++ b/main/_sources/plugins/keycloak_authentication.rst.txt @@ -0,0 +1,779 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_authentication -- Configure authentication in Keycloak ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_authentication`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module actually can only make a copy of an existing authentication flow, add an execution to it and configure it. +- It can also delete the flow. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        alias

        + +

        + string + / required +

        +
        +

        Alias for the authentication flow.

        +
        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        authenticationExecutions

        + +

        + list + / elements=dictionary +

        +
        +

        Configuration structure for the executions.

        +
        +
        +

        authenticationConfig

        + +

        + dictionary +

        +
        +

        Describe the config of the authentication.

        +
        +
        +

        displayName

        + +

        + string +

        +
        +

        Name of the execution or subflow to create or update.

        +
        +
        +

        flowAlias

        + +

        + string +

        +
        +

        Alias of parent flow.

        +
        +
        +

        index

        + +

        + integer +

        +
        +

        Priority order of the execution.

        +
        +
        +

        providerId

        + +

        + string +

        +
        +

        providerID for the new flow when not copied from an existing flow.

        +
        +
        +

        requirement

        + +

        + string +

        +
        +

        Control status of the subflow or execution.

        +

        Choices:

        +
          +

        • "REQUIRED"

          • +

        • "ALTERNATIVE"

          • +

        • "DISABLED"

          • +

        • "CONDITIONAL"

          • +
        + +
        +
        +

        subFlowType

        + +

        + string +

        +
        +

        For new subflows, optionally specify the type.

        +

        Is only used at creation.

        +

        Choices:

        +
          +

        • "basic-flow" ← (default)

          • +

        • "form-flow"

          • +
        + +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        copyFrom

        + +

        + string +

        +
        +

        flowAlias of the authentication flow to use for the copy.

        +
        +
        +

        description

        + +

        + string +

        +
        +

        Description of the flow.

        +
        +
        +

        force

        + +

        + boolean +

        +
        +

        If true, allows to remove the authentication flow and recreate it.

        +

        Choices:

        +
          +

        • false ← (default)

          • +

        • true

          • +
        + +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        providerId

        + +

        + string +

        +
        +

        providerId for the new flow when not copied from an existing flow.

        +

        Choices:

        +
          +

        • "basic-flow"

          • +

        • "client-flow"

          • +
        + +
        +
        +

        realm

        + +

        + string + / required +

        +
        +

        The name of the realm in which is the authentication.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        Control if the authentication flow must exists or not.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Create an authentication flow from first broker login and add an execution to it. + middleware_automation.keycloak.keycloak_authentication: + auth_keycloak_url: http://localhost:8080 + auth_realm: master + auth_username: admin + auth_password: password + realm: master + alias: "Copy of first broker login" + copyFrom: "first broker login" + authenticationExecutions: + - providerId: "test-execution1" + requirement: "REQUIRED" + authenticationConfig: + alias: "test.execution1.property" + config: + test1.property: "value" + - providerId: "test-execution2" + requirement: "REQUIRED" + authenticationConfig: + alias: "test.execution2.property" + config: + test2.property: "value" + state: present + + - name: Re-create the authentication flow + middleware_automation.keycloak.keycloak_authentication: + auth_keycloak_url: http://localhost:8080 + auth_realm: master + auth_username: admin + auth_password: password + realm: master + alias: "Copy of first broker login" + copyFrom: "first broker login" + authenticationExecutions: + - providerId: "test-provisioning" + requirement: "REQUIRED" + authenticationConfig: + alias: "test.provisioning.property" + config: + test.provisioning.property: "value" + state: present + force: true + + - name: Create an authentication flow with subflow containing an execution. + middleware_automation.keycloak.keycloak_authentication: + auth_keycloak_url: http://localhost:8080 + auth_realm: master + auth_username: admin + auth_password: password + realm: master + alias: "Copy of first broker login" + copyFrom: "first broker login" + authenticationExecutions: + - providerId: "test-execution1" + requirement: "REQUIRED" + - displayName: "New Subflow" + requirement: "REQUIRED" + - providerId: "auth-cookie" + requirement: "REQUIRED" + flowAlias: "New Sublow" + state: present + + - name: Remove authentication. + middleware_automation.keycloak.keycloak_authentication: + auth_keycloak_url: http://localhost:8080 + auth_realm: master + auth_username: admin + auth_password: password + realm: master + alias: "Copy of first broker login" + state: absent + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of the authentication after module execution.

        +

        Returned: on success

        +

        Sample: {"alias": "Copy of first broker login", "authenticationExecutions": [{"alias": "review profile config", "authenticationConfig": {"alias": "review profile config", "config": {"update.profile.on.first.login": "missing"}, "id": "6f09e4fb-aad4-496a-b873-7fa9779df6d7"}, "configurable": true, "displayName": "Review Profile", "id": "8f77dab8-2008-416f-989e-88b09ccf0b4c", "index": 0, "level": 0, "providerId": "idp-review-profile", "requirement": "REQUIRED", "requirementChoices": ["REQUIRED", "ALTERNATIVE", "DISABLED"]}], "builtIn": false, "description": "Actions taken after first broker login with identity provider account, which is not yet linked to any Keycloak account", "id": "bc228863-5887-4297-b898-4d988f8eaa5c", "providerId": "basic-flow", "topLevel": true}

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Philippe Gauthier (@elfelip) +- Gaëtan Daubresse (@Gaetan2907) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_authentication_flow.rst.txt b/main/_sources/plugins/keycloak_authentication_flow.rst.txt index 728939e..1300b93 100644 --- a/main/_sources/plugins/keycloak_authentication_flow.rst.txt +++ b/main/_sources/plugins/keycloak_authentication_flow.rst.txt @@ -33,6 +33,9 @@ keycloak_authentication_flow -- Allows administration of Keycloak authentication .. version_added +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 .. contents:: :local: @@ -183,7 +186,6 @@ Parameters

        integer

        -

        added in middleware_automation.keycloak 4.5.0

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        @@ -284,7 +286,6 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 5.4.0

        Configures the HTTP User-Agent header.

        @@ -322,6 +323,19 @@ Parameters
        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +
        +

        Authentication refresh token for Keycloak API.

        +
        + +

        state

        @@ -342,7 +356,7 @@ Parameters
        - +

        token

        @@ -350,13 +364,12 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 3.0.0

        Authentication token for Keycloak API.

        - +

        validate_certs

        @@ -398,6 +411,48 @@ Attributes - Support - Description + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_flow_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + * - .. raw:: html
        diff --git a/main/_sources/plugins/keycloak_authentication_required_actions.rst.txt b/main/_sources/plugins/keycloak_authentication_required_actions.rst.txt new file mode 100644 index 0000000..57d8f45 --- /dev/null +++ b/main/_sources/plugins/keycloak_authentication_required_actions.rst.txt @@ -0,0 +1,772 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_required_actions_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_authentication_required_actions -- Allows administration of Keycloak authentication required actions ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_authentication_required_actions`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module can register, update and delete required actions. +- It also filters out any duplicate required actions by their alias. The first occurrence is preserved. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        realm

        + +

        + string + / required +

        +
        +

        The name of the realm in which are the authentication required actions.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        required_actions

        + +

        + list + / elements=dictionary +

        +
        +

        Authentication required action.

        +
        +
        +

        alias

        + +

        + string + / required +

        +
        +

        Unique name of the required action.

        +
        +
        +

        config

        + +

        + dictionary +

        +
        +

        Configuration for the required action.

        +
        +
        +

        defaultAction

        + +

        + boolean +

        +
        +

        Indicates whether new users have the required action assigned to them.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        enabled

        + +

        + boolean +

        +
        +

        Indicates, if the required action is enabled or not.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        name

        + +

        + string +

        +
        +

        Displayed name of the required action. Required for registration.

        +
        +
        +

        priority

        + +

        + integer +

        +
        +

        Priority of the required action.

        +
        +
        +

        providerId

        + +

        + string +

        +
        +

        Provider ID of the required action. Required for registration.

        +
        +
        +

        state

        + +

        + string + / required +

        +
        +

        Control if the realm authentication required actions are going to be registered/updated (present) or deleted (absent).

        +

        Choices:

        +
          +

        • "absent"

          • +

        • "present"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_required_actions_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_required_actions_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_required_actions_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Register a new required action. + middleware_automation.keycloak.keycloak_authentication_required_actions: + auth_client_id: "admin-cli" + auth_keycloak_url: "http://localhost:8080" + auth_password: "password" + auth_realm: "master" + auth_username: "admin" + realm: "master" + required_actions: + - alias: "TERMS_AND_CONDITIONS" + name: "Terms and conditions" + providerId: "TERMS_AND_CONDITIONS" + enabled: true + state: "present" + + - name: Update the newly registered required action. + middleware_automation.keycloak.keycloak_authentication_required_actions: + auth_client_id: "admin-cli" + auth_keycloak_url: "http://localhost:8080" + auth_password: "password" + auth_realm: "master" + auth_username: "admin" + realm: "master" + required_actions: + - alias: "TERMS_AND_CONDITIONS" + enabled: false + state: "present" + + - name: Delete the updated registered required action. + middleware_automation.keycloak.keycloak_authentication_required_actions: + auth_client_id: "admin-cli" + auth_keycloak_url: "http://localhost:8080" + auth_password: "password" + auth_realm: "master" + auth_username: "admin" + realm: "master" + required_actions: + - alias: "TERMS_AND_CONDITIONS" + state: "absent" + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + complex +

        +
        +

        Representation of the authentication required actions after module execution.

        +

        Returned: on success

        +
        +
        +

        alias

        + +

        + string +

        +
        +

        Unique name of the required action.

        +

        Returned: success

        +

        Sample: "test-provider-id"

        +
        +
        +

        config

        + +

        + dictionary +

        +
        +

        Configuration for the required action.

        +

        Returned: success

        +

        Sample: {}

        +
        +
        +

        defaultAction

        + +

        + boolean +

        +
        +

        Indicates whether new users have the required action assigned to them.

        +

        Returned: success

        +

        Sample: false

        +
        +
        +

        enabled

        + +

        + boolean +

        +
        +

        Indicates, if the required action is enabled or not.

        +

        Returned: success

        +

        Sample: false

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Displayed name of the required action. Required for registration.

        +

        Returned: success

        +

        Sample: "Test provider ID"

        +
        +
        +

        priority

        + +

        + integer +

        +
        +

        Priority of the required action.

        +

        Returned: success

        +

        Sample: 90

        +
        +
        +

        providerId

        + +

        + string +

        +
        +

        Provider ID of the required action. Required for registration.

        +

        Returned: success

        +

        Sample: "test-provider-id"

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Skrekulko (@Skrekulko) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_authentication_v2.rst.txt b/main/_sources/plugins/keycloak_authentication_v2.rst.txt new file mode 100644 index 0000000..4c1f96e --- /dev/null +++ b/main/_sources/plugins/keycloak_authentication_v2.rst.txt @@ -0,0 +1,1216 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_v2_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_authentication_v2 -- Configure authentication flows in Keycloak in an idempotent and safe manner. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_authentication_v2`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows the creation, deletion, and modification of Keycloak authentication flows using the Keycloak REST API. +- Rather than modifying an existing flow in place, the module re\-creates the flow using the :strong:`Safe Swap` mechanism described below. +- :strong:`Safe Swap mechanism` \- When an authentication flow needs to be updated, the module never modifies the existing flow in place. Instead it follows a multi\-step swap procedure to ensure the flow is never left in an intermediate or unsafe state during the update. This is especially important when the flow is actively bound to a realm binding, a client override, or as an identity\-provider login\-flow or post\-flow, because a partially\-updated flow could inadvertently allow unauthorised access. +- The :strong:`Safe Swap mechanism` is as follows. 1. A new flow is created under a temporary name (the original alias plus a configurable suffix, for example :literal:`myflow\_tmp\_for\_swap`\ ). 2. All executions and their configurations are added to the new temporary flow. 3. If the existing flow is currently bound to a realm or a client, all bindings are redirected to the new temporary flow. This ensures continuity and avoids any gap in active authentication coverage. 4. The old flow is deleted. 5. The temporary flow is renamed to the original alias, restoring the expected name. +- :strong:`Handling pre\-existing temporary swap flows` \- If a temporary swap flow already exists (for example, from a previously interrupted run), the module can optionally delete it before proceeding. This behaviour is controlled by the :ansopt:`middleware\_automation.keycloak.keycloak\_authentication\_v2#module:force\_temporary\_swap\_flow\_deletion` option. If the option is :ansval:`false` and a temporary flow already exists, the module will fail to prevent accidental data loss. +- :strong:`Idempotency` \- If the existing flow already matches the desired configuration, no changes are made. The module compares a normalised representation of the existing flow against the desired state before deciding whether to trigger the Safe Swap procedure. +- A depth of 4 sub\-flows is supported. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        alias

        + +

        + string + / required +

        +
        +

        The name of the authentication flow.

        +
        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        authenticationExecutions

        + +

        + list + / elements=dictionary +

        +
        +

        The desired execution configuration for the flow.

        +

        Executions at root level.

        +
        +
        +

        authenticationConfig

        + +

        + dictionary +

        +
        +

        The configuration for the execution.

        +
        +
        +

        alias

        + +

        + string + / required +

        +
        +

        Name of the execution config.

        +
        +
        +

        config

        + +

        + dictionary + / required +

        +
        +

        Options for the execution config.

        +
        +
        +

        authenticationExecutions

        + +

        + list + / elements=dictionary +

        +
        +

        The execution configuration for executions within the sub-flow.

        +

        Executions at sub level 1.

        +
        +
        +

        authenticationConfig

        + +

        + dictionary +

        +
        +

        The configuration for the execution.

        +
        +
        +

        alias

        + +

        + string + / required +

        +
        +

        Name of the execution config.

        +
        +
        +

        config

        + +

        + dictionary + / required +

        +
        +

        Options for the execution config.

        +
        +
        +

        authenticationExecutions

        + +

        + list + / elements=dictionary +

        +
        +

        The execution configuration for executions within the sub-flow.

        +

        Executions at sub level 2.

        +
        +
        +

        authenticationConfig

        + +

        + dictionary +

        +
        +

        The configuration for the execution.

        +
        +
        +

        alias

        + +

        + string + / required +

        +
        +

        Name of the execution config.

        +
        +
        +

        config

        + +

        + dictionary + / required +

        +
        +

        Options for the execution config.

        +
        +
        +

        authenticationExecutions

        + +

        + list + / elements=dictionary +

        +
        +

        The execution configuration for executions within the sub-flow.

        +

        Executions at sub level 3.

        +
        +
        +

        authenticationConfig

        + +

        + dictionary +

        +
        +

        The configuration for the execution.

        +
        +
        +

        alias

        + +

        + string + / required +

        +
        +

        Name of the execution config.

        +
        +
        +

        config

        + +

        + dictionary + / required +

        +
        +

        Options for the execution config.

        +
        +
        +

        authenticationExecutions

        + +

        + list + / elements=dictionary +

        +
        +

        The execution configuration for executions within the sub-flow.

        +

        Executions at sub level 4 (last sub level).

        +
        +
        +

        authenticationConfig

        + +

        + dictionary +

        +
        +

        The configuration for the execution.

        +
        +
        +

        alias

        + +

        + string + / required +

        +
        +

        Name of the execution config.

        +
        +
        +

        config

        + +

        + dictionary + / required +

        +
        +

        Options for the execution config.

        +
        +
        +

        providerId

        + +

        + string + / required +

        +
        +

        The providerId of the execution.

        +
        +
        +

        requirement

        + +

        + string + / required +

        +
        +

        The requirement status of the execution or sub-flow.

        +

        Choices:

        +
          +

        • "REQUIRED"

          • +

        • "ALTERNATIVE"

          • +

        • "DISABLED"

          • +

        • "CONDITIONAL"

          • +
        + +
        +
        +

        providerId

        + +

        + string +

        +
        +

        The providerId of the execution.

        +
        +
        +

        requirement

        + +

        + string + / required +

        +
        +

        The requirement status of the execution or sub-flow.

        +

        Choices:

        +
          +

        • "REQUIRED"

          • +

        • "ALTERNATIVE"

          • +

        • "DISABLED"

          • +

        • "CONDITIONAL"

          • +
        + +
        +
        +

        subFlow

        + +

        + string +

        +
        +

        The name of the sub-flow.

        +
        +
        +

        subFlowType

        + +

        + string +

        +
        +

        The type of the sub-flow.

        +

        Choices:

        +
          +

        • "basic-flow" ← (default)

          • +

        • "form-flow"

          • +
        + +
        +
        +

        providerId

        + +

        + string +

        +
        +

        The providerId of the execution.

        +
        +
        +

        requirement

        + +

        + string + / required +

        +
        +

        The requirement status of the execution or sub-flow.

        +

        Choices:

        +
          +

        • "REQUIRED"

          • +

        • "ALTERNATIVE"

          • +

        • "DISABLED"

          • +

        • "CONDITIONAL"

          • +
        + +
        +
        +

        subFlow

        + +

        + string +

        +
        +

        The name of the sub-flow.

        +
        +
        +

        subFlowType

        + +

        + string +

        +
        +

        The type of the sub-flow.

        +

        Choices:

        +
          +

        • "basic-flow" ← (default)

          • +

        • "form-flow"

          • +
        + +
        +
        +

        providerId

        + +

        + string +

        +
        +

        The providerId of the execution.

        +
        +
        +

        requirement

        + +

        + string + / required +

        +
        +

        The requirement status of the execution or sub-flow.

        +

        Choices:

        +
          +

        • "REQUIRED"

          • +

        • "ALTERNATIVE"

          • +

        • "DISABLED"

          • +

        • "CONDITIONAL"

          • +
        + +
        +
        +

        subFlow

        + +

        + string +

        +
        +

        The name of the sub-flow.

        +
        +
        +

        subFlowType

        + +

        + string +

        +
        +

        The type of the sub-flow.

        +

        Choices:

        +
          +

        • "basic-flow" ← (default)

          • +

        • "form-flow"

          • +
        + +
        +
        +

        providerId

        + +

        + string +

        +
        +

        The providerId of the execution.

        +
        +
        +

        requirement

        + +

        + string + / required +

        +
        +

        The requirement status of the execution or sub-flow.

        +

        Choices:

        +
          +

        • "REQUIRED"

          • +

        • "ALTERNATIVE"

          • +

        • "DISABLED"

          • +

        • "CONDITIONAL"

          • +
        + +
        +
        +

        subFlow

        + +

        + string +

        +
        +

        The name of the sub-flow.

        +
        +
        +

        subFlowType

        + +

        + string +

        +
        +

        The type of the sub-flow.

        +

        Choices:

        +
          +

        • "basic-flow" ← (default)

          • +

        • "form-flow"

          • +
        + +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        description

        + +

        + string +

        +
        +

        A human-readable description of the flow.

        +
        +
        +

        force_temporary_swap_flow_deletion

        + +

        + boolean +

        +
        +

        If true, any pre-existing temporary swap flow (identified by the original alias plus temporary_swap_flow_suffix) is deleted before the Safe Swap procedure begins.

        +

        Set this to false to cause the module to fail instead of silently removing a pre-existing temporary flow, for example to avoid accidental data loss after an interrupted run.

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        providerId

        + +

        + string +

        +
        +

        The providerId for the new flow.

        +

        Choices:

        +
          +

        • "basic-flow" ← (default)

          • +

        • "client-flow"

          • +
        + +
        +
        +

        realm

        + +

        + string + / required +

        +
        +

        The name of the realm in which the authentication flow resides.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        Whether the authentication flow should exist or not.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        temporary_swap_flow_suffix

        + +

        + string +

        +
        +

        The suffix appended to the alias of the temporary flow created during a Safe Swap update.

        +

        The temporary flow exists only for the duration of the swap procedure and is renamed to the original alias once all bindings have been successfully transferred.

        +

        Default: "_tmp_for_swap"

        +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_v2_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_v2_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_v2_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Create or modify the 'My Login Flow'. + middleware_automation.keycloak.keycloak_authentication_v2: + auth_keycloak_url: http://localhost:8080 + auth_realm: master + auth_username: admin + auth_password: password + realm: master + alias: My Login Flow + authenticationExecutions: + - providerId: idp-review-profile + requirement: REQUIRED + authenticationConfig: + alias: My Login Flow - review profile config + config: + update.profile.on.first.login: "missing" + - subFlow: My Login Flow - User creation or linking + requirement: REQUIRED + authenticationExecutions: + - providerId: idp-create-user-if-unique + requirement: ALTERNATIVE + authenticationConfig: + alias: My Login Flow - create unique user config + config: + require.password.update.after.registration: "true" + - providerId: auth-cookie + requirement: REQUIRED + - subFlow: My Login Flow - Handle Existing Account + requirement: ALTERNATIVE + authenticationExecutions: + - providerId: idp-confirm-link + requirement: REQUIRED + - providerId: auth-cookie + requirement: DISABLED + state: present + + - name: Remove an authentication flow. + middleware_automation.keycloak.keycloak_authentication_v2: + auth_keycloak_url: http://localhost:8080 + auth_realm: master + auth_username: admin + auth_password: password + realm: master + alias: My Login Flow + state: absent + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of the authentication flow after module execution.

        +

        Returned: on success

        +

        Sample: {"alias": "My Login Flow", "authenticationExecutions": [{"alias": "review profile config", "authenticationConfig": {"alias": "review profile config", "config": {"update.profile.on.first.login": "missing"}, "id": "6f09e4fb-aad4-496a-b873-7fa9779df6d7"}, "configurable": true, "displayName": "Review Profile", "id": "8f77dab8-2008-416f-989e-88b09ccf0b4c", "index": 0, "level": 0, "providerId": "idp-review-profile", "requirement": "REQUIRED", "requirementChoices": ["REQUIRED", "ALTERNATIVE", "DISABLED"]}], "builtIn": false, "description": "Actions taken after first broker login with identity provider account, which is not yet linked to any Keycloak account", "id": "bc228863-5887-4297-b898-4d988f8eaa5c", "providerId": "basic-flow", "topLevel": true}

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Thomas Bargetz (@thomasbargetz) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_authz_authorization_scope.rst.txt b/main/_sources/plugins/keycloak_authz_authorization_scope.rst.txt new file mode 100644 index 0000000..45da5ac --- /dev/null +++ b/main/_sources/plugins/keycloak_authz_authorization_scope.rst.txt @@ -0,0 +1,637 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_authz_authorization_scope_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_authz_authorization_scope -- Allows administration of Keycloak client authorization scopes using Keycloak API +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_authz_authorization_scope`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows the administration of Keycloak client Authorization Scopes using the Keycloak REST API. Authorization Scopes are only available if a client has Authorization enabled. +- This module requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate realm definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase options used by Keycloak. The Authorization Services paths and payloads have not officially been documented by the Keycloak project. \ `https://www.puppeteers.net/blog/keycloak\-authorization\-services\-rest\-api\-paths\-and\-payload/ `__. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        client_id

        + +

        + string + / required +

        +
        +

        The clientId of the Keycloak client that should have the authorization scope.

        +

        This is usually a human-readable name of the Keycloak client.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        display_name

        + +

        + string +

        +
        +

        The display name of the authorization scope.

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        icon_uri

        + +

        + string +

        +
        +

        The icon URI for the authorization scope.

        +
        +
        +

        name

        + +

        + string + / required +

        +
        +

        Name of the authorization scope to create.

        +
        +
        +

        realm

        + +

        + string + / required +

        +
        +

        The name of the Keycloak realm the Keycloak client is in.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the authorization scope.

        +

        On present, the authorization scope is created (or updated if it exists already).

        +

        On absent, the authorization scope is removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_authorization_scope_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_authorization_scope_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_authorization_scope_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Manage Keycloak file:delete authorization scope + keycloak_authz_authorization_scope: + name: file:delete + state: present + display_name: File delete + client_id: myclient + realm: myrealm + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + complex +

        +
        +

        Representation of the authorization scope after module execution.

        +

        Returned: on success

        +
        +
        +

        display_name

        + +

        + string +

        +
        +

        Display name of the authorization scope.

        +

        Returned: when state=present

        +

        Sample: "File delete"

        +
        +
        +

        icon_uri

        + +

        + string +

        +
        +

        Icon URI for the authorization scope.

        +

        Returned: when state=present

        +

        Sample: "http://localhost/icon.png"

        +
        +
        +

        id

        + +

        + string +

        +
        +

        ID of the authorization scope.

        +

        Returned: when state=present

        +

        Sample: "a6ab1cf2-1001-40ec-9f39-48f23b6a0a41"

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the authorization scope.

        +

        Returned: when state=present

        +

        Sample: "file:delete"

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Samuli Seppänen (@mattock) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_authz_custom_policy.rst.txt b/main/_sources/plugins/keycloak_authz_custom_policy.rst.txt new file mode 100644 index 0000000..4660e2d --- /dev/null +++ b/main/_sources/plugins/keycloak_authz_custom_policy.rst.txt @@ -0,0 +1,596 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_authz_custom_policy_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_authz_custom_policy -- Allows administration of Keycloak client custom Javascript policies using Keycloak API +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_authz_custom_policy`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows the administration of Keycloak client custom Javascript using the Keycloak REST API. Custom Javascript policies are only available if a client has Authorization enabled and if they have been deployed to the Keycloak server as JAR files. +- This module requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate realm definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase options used by Keycloak. The Authorization Services paths and payloads have not officially been documented by the Keycloak project. \ `https://www.puppeteers.net/blog/keycloak\-authorization\-services\-rest\-api\-paths\-and\-payload/ `__. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        client_id

        + +

        + string + / required +

        +
        +

        The clientId of the Keycloak client that should have the custom policy attached to it.

        +

        This is usually a human-readable name of the Keycloak client.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        name

        + +

        + string + / required +

        +
        +

        Name of the custom policy to create.

        +
        +
        +

        policy_type

        + +

        + string + / required +

        +
        +

        The type of the policy. This must match the name of the custom policy deployed to the server.

        +

        Multiple policies pointing to the same policy type can be created, but their names have to differ.

        +
        +
        +

        realm

        + +

        + string + / required +

        +
        +

        The name of the Keycloak realm the Keycloak client is in.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the custom policy.

        +

        On present, the custom policy is created (or updated if it exists already).

        +

        On absent, the custom policy is removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_custom_policy_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_custom_policy_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_custom_policy_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-none:`none` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Manage Keycloak custom authorization policy + middleware_automation.keycloak.keycloak_authz_custom_policy: + name: OnlyOwner + state: present + policy_type: script-policy.js + client_id: myclient + realm: myrealm + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of the custom policy after module execution.

        +

        Returned: on success

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the custom policy.

        +

        Returned: when state=present

        +

        Sample: "file:delete"

        +
        +
        +

        policy_type

        + +

        + string +

        +
        +

        Type of custom policy.

        +

        Returned: when state=present

        +

        Sample: "File delete"

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Samuli Seppänen (@mattock) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_authz_permission.rst.txt b/main/_sources/plugins/keycloak_authz_permission.rst.txt new file mode 100644 index 0000000..afaa097 --- /dev/null +++ b/main/_sources/plugins/keycloak_authz_permission.rst.txt @@ -0,0 +1,815 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_authz_permission_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_authz_permission -- Allows administration of Keycloak client authorization permissions using Keycloak API +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_authz_permission`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows the administration of Keycloak client authorization permissions using the Keycloak REST API. Authorization permissions are only available if a client has Authorization enabled. +- There are some peculiarities in JSON paths and payloads for authorization permissions. In particular POST and PUT operations are targeted at permission endpoints, whereas GET requests go to policies endpoint. To make matters more interesting the JSON responses from GET requests return data in a different format than what is expected for POST and PUT. The end result is that it is not possible to detect changes to things like policies, scopes or resources \- at least not without a large number of additional API calls. Therefore this module always updates authorization permissions instead of attempting to determine if changes are truly needed. +- This module requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate realm definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase options used by Keycloak. The Authorization Services paths and payloads have not officially been documented by the Keycloak project. \ `https://www.puppeteers.net/blog/keycloak\-authorization\-services\-rest\-api\-paths\-and\-payload/ `__. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        client_id

        + +

        + string + / required +

        +
        +

        The clientId of the keycloak client that should have the authorization scope.

        +

        This is usually a human-readable name of the Keycloak client.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        decision_strategy

        + +

        + string +

        +
        +

        The decision strategy to use with this permission.

        +

        Choices:

        +
          +

        • "UNANIMOUS" ← (default)

          • +

        • "AFFIRMATIVE"

          • +

        • "CONSENSUS"

          • +
        + +
        +
        +

        description

        + +

        + string +

        +
        +

        The description of the authorization permission.

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        name

        + +

        + string + / required +

        +
        +

        Name of the authorization permission to create.

        +
        +
        +

        permission_type

        + +

        + string + / required +

        +
        +

        The type of authorization permission.

        +

        On scope create a scope-based permission.

        +

        On resource create a resource-based permission.

        +

        Choices:

        +
          +

        • "resource"

          • +

        • "scope"

          • +
        + +
        +
        +

        policies

        + +

        + list + / elements=string +

        +
        +

        Policy names to attach to this permission.

        +

        Default: []

        +
        +
        +

        realm

        + +

        + string + / required +

        +
        +

        The name of the Keycloak realm the Keycloak client is in.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        resources

        + +

        + list + / elements=string +

        +
        +

        Resource names to attach to this permission.

        +

        Scope-based permissions can only include one resource.

        +

        Resource-based permissions can include multiple resources.

        +

        Default: []

        +
        +
        +

        scopes

        + +

        + list + / elements=string +

        +
        +

        Scope names to attach to this permission.

        +

        Resource-based permissions cannot have scopes attached to them.

        +

        Default: []

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the authorization permission.

        +

        On present, the authorization permission is created (or updated if it exists already).

        +

        On absent, the authorization permission is removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_permission_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_permission_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_permission_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-none:`none` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Manage scope-based Keycloak authorization permission + middleware_automation.keycloak.keycloak_authz_permission: + name: ScopePermission + state: present + description: Scope permission + permission_type: scope + scopes: + - file:delete + policies: + - Default Policy + client_id: myclient + realm: myrealm + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + + - name: Manage resource-based Keycloak authorization permission + middleware_automation.keycloak.keycloak_authz_permission: + name: ResourcePermission + state: present + description: Resource permission + permission_type: resource + resources: + - Default Resource + policies: + - Default Policy + client_id: myclient + realm: myrealm + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + complex +

        +
        +

        Representation of the authorization permission after module execution.

        +

        Returned: on success

        +
        +
        +

        decisionStrategy

        + +

        + string +

        +
        +

        The decision strategy to use.

        +

        Returned: when state=present

        +

        Sample: "UNANIMOUS"

        +
        +
        +

        description

        + +

        + string +

        +
        +

        Description of the authorization permission.

        +

        Returned: when state=present

        +

        Sample: "Resource Permission"

        +
        +
        +

        id

        + +

        + string +

        +
        +

        ID of the authorization permission.

        +

        Returned: when state=present

        +

        Sample: "9da05cd2-b273-4354-bbd8-0c133918a454"

        +
        +
        +

        logic

        + +

        + string +

        +
        +

        The logic used for the permission (part of the payload, but has a fixed value).

        +

        Returned: when state=present

        +

        Sample: "POSITIVE"

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the authorization permission.

        +

        Returned: when state=present

        +

        Sample: "ResourcePermission"

        +
        +
        +

        policies

        + +

        + list + / elements=string +

        +
        +

        IDs of policies attached to this permission.

        +

        Returned: when state=present

        +

        Sample: ["9da05cd2-b273-4354-bbd8-0c133918a454"]

        +
        +
        +

        resources

        + +

        + list + / elements=string +

        +
        +

        IDs of resources attached to this permission.

        +

        Returned: when state=present

        +

        Sample: ["49e052ff-100d-4b79-a9dd-52669ed3c11d"]

        +
        +
        +

        scopes

        + +

        + list + / elements=string +

        +
        +

        IDs of scopes attached to this permission.

        +

        Returned: when state=present

        +

        Sample: ["9da05cd2-b273-4354-bbd8-0c133918a454"]

        +
        +
        +

        type

        + +

        + string +

        +
        +

        Type of the authorization permission.

        +

        Returned: when state=present

        +

        Sample: "resource"

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Samuli Seppänen (@mattock) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_authz_permission_info.rst.txt b/main/_sources/plugins/keycloak_authz_permission_info.rst.txt new file mode 100644 index 0000000..214dd31 --- /dev/null +++ b/main/_sources/plugins/keycloak_authz_permission_info.rst.txt @@ -0,0 +1,637 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_authz_permission_info_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_authz_permission_info -- Query Keycloak client authorization permissions information ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_authz_permission_info`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows querying information about Keycloak client authorization permissions from the resources endpoint using the Keycloak REST API. Authorization permissions are only available if a client has Authorization enabled. +- This module requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate realm definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase options used by Keycloak. The Authorization Services paths and payloads have not officially been documented by the Keycloak project. \ `https://www.puppeteers.net/blog/keycloak\-authorization\-services\-rest\-api\-paths\-and\-payload/ `__. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        client_id

        + +

        + string + / required +

        +
        +

        The clientId of the keycloak client that should have the authorization scope.

        +

        This is usually a human-readable name of the Keycloak client.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        name

        + +

        + string + / required +

        +
        +

        Name of the authorization permission to create.

        +
        +
        +

        realm

        + +

        + string + / required +

        +
        +

        The name of the Keycloak realm the Keycloak client is in.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_permission_info_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_permission_info_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + This action does not modify state. + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_authz_permission_info_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ ` \ :ansible-attribute-support-na:`N/A` + + This action does not modify state. + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Query Keycloak authorization permission + middleware_automation.keycloak.keycloak_authz_permission_info: + name: ScopePermission + client_id: myclient + realm: myrealm + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +
        +
        +

        queried_state

        + +

        + complex +

        +
        +

        State of the resource (a policy) as seen by Keycloak.

        +

        Returned: on success

        +
        +
        +

        config

        + +

        + dictionary +

        +
        +

        Configuration of the permission (empty in all observed cases).

        +

        Returned: success

        +

        Sample: {}

        +
        +
        +

        decisionStrategy

        + +

        + string +

        +
        +

        The decision strategy.

        +

        Returned: success

        +

        Sample: "UNANIMOUS"

        +
        +
        +

        description

        + +

        + string +

        +
        +

        Description of the authorization permission.

        +

        Returned: success

        +

        Sample: "Resource Permission"

        +
        +
        +

        id

        + +

        + string +

        +
        +

        ID of the authorization permission.

        +

        Returned: success

        +

        Sample: "9da05cd2-b273-4354-bbd8-0c133918a454"

        +
        +
        +

        logic

        + +

        + string +

        +
        +

        The logic used for the permission (part of the payload, but has a fixed value).

        +

        Returned: success

        +

        Sample: "POSITIVE"

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the authorization permission.

        +

        Returned: success

        +

        Sample: "ResourcePermission"

        +
        +
        +

        type

        + +

        + string +

        +
        +

        Type of the authorization permission.

        +

        Returned: success

        +

        Sample: "resource"

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Samuli Seppänen (@mattock) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_client.rst.txt b/main/_sources/plugins/keycloak_client.rst.txt index b323771..76b0045 100644 --- a/main/_sources/plugins/keycloak_client.rst.txt +++ b/main/_sources/plugins/keycloak_client.rst.txt @@ -16,8 +16,8 @@ .. Title -keycloak_client -- Allows administration of Keycloak clients via Keycloak API -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +keycloak_client -- Allows administration of Keycloak clients using Keycloak API ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. Collection note @@ -33,6 +33,9 @@ keycloak_client -- Allows administration of Keycloak clients via Keycloak API .. version_added +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 .. contents:: :local: @@ -46,9 +49,9 @@ Synopsis .. Description -- This module allows the administration of Keycloak clients via the Keycloak REST API. It requires access to the REST API via OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. -- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/8.0/rest\-api/index.html `__. Aliases are provided so camelCased versions can be used as well. -- The Keycloak API does not always sanity check inputs e.g. you can set SAML\-specific settings on an OpenID Connect client for instance and vice versa. Be careful. If you do not specify a setting, usually a sensible default is chosen. +- This module allows the administration of Keycloak clients using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/latest/rest\-api/index.html `__. Aliases are provided so camelCased versions can be used as well. +- The Keycloak API does not always sanity check inputs, for example you can set SAML\-specific settings on an OpenID Connect client for instance and the other way around. Be careful. If you do not specify a setting, usually a sensible default is chosen. .. Aliases @@ -88,7 +91,7 @@ Parameters

        -

        URL to the admin interface of the client. This is 'adminUrl' in the Keycloak REST API.

        +

        URL to the admin interface of the client. This is adminUrl in the Keycloak REST API.

        @@ -101,7 +104,6 @@ Parameters

        boolean

        -

        added in middleware_automation.keycloak 4.7.0

        Whether or not to display this client in account console, even if the user does not have an active session.

        @@ -123,7 +125,7 @@ Parameters

        -

        A dict of further attributes for this client. This can contain various configuration settings; an example is given in the examples section. While an exhaustive list of permissible options is not available; possible options as of Keycloak 3.4 are listed below. The Keycloak API does not validate whether a given option is appropriate for the protocol used; if specified anyway, Keycloak will simply not use it.

        +

        A dict of further attributes for this client. This can contain various configuration settings; an example is given in the examples section. While an exhaustive list of permissible options is not available; possible options as of Keycloak 3.4 are listed below. The Keycloak API does not validate whether a given option is appropriate for the protocol used; if specified anyway, Keycloak does not use it.

        @@ -253,7 +255,7 @@ Parameters

        -

        For SAML clients, boolean specifying whether REDIRECT signing key lookup should be optimized through inclusion of the signing key id in the SAML Extensions element.

        +

        For SAML clients, boolean specifying whether REDIRECT signing key lookup should be optimized through inclusion of the signing key ID in the SAML Extensions element.

        @@ -344,7 +346,7 @@ Parameters

        -

        For SAML clients, the NameID format to use (one of username, email, transient, or persistent)

        +

        For SAML clients, the NameID format to use (one of username, email, transient, or persistent).

        @@ -370,7 +372,7 @@ Parameters

        -

        SAML POST binding url for the client's single logout service.

        +

        SAML POST binding URL for the client's single logout service.

        @@ -383,7 +385,7 @@ Parameters

        -

        SAML redirect binding url for the client's single logout service.

        +

        SAML redirect binding URL for the client's single logout service.

        @@ -420,7 +422,6 @@ Parameters

        boolean

        -

        added in middleware_automation.keycloak 9.5.0

        For OpenID-Connect clients, boolean specifying whether to allow x509.subjectdn as regular expression.

        @@ -440,10 +441,9 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 9.5.0

        -

        For OpenID-Connect clients, subject which will be used to authenticate the client.

        +

        For OpenID-Connect clients, subject which is used to authenticate the client.

        @@ -543,7 +543,6 @@ Parameters

        dictionary

        -

        added in middleware_automation.keycloak 3.4.0

        Override realm authentication flow bindings.

        @@ -576,7 +575,6 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 9.1.0

        Flow name of the browser authentication flow.

        @@ -613,7 +611,6 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 9.1.0

        Flow name of the direct grant authentication flow.

        @@ -633,7 +630,7 @@ Parameters

        -

        Are authorization services enabled for this client or not (OpenID connect). This is 'authorizationServicesEnabled' in the Keycloak REST API.

        +

        Are authorization services enabled for this client or not (OpenID connect). This is authorizationServicesEnabled in the Keycloak REST API.

        Choices:

        • false

          • @@ -654,10 +651,26 @@ Parameters

        -

        a data structure defining the authorization settings for this client. For reference, please see the Keycloak API docs at https://www.keycloak.org/docs-api/8.0/rest-api/index.html#_resourceserverrepresentation. This is 'authorizationSettings' in the Keycloak REST API.

        +

        A data structure defining the authorization settings for this client. For reference, please see the Keycloak API docs at https://www.keycloak.org/docs-api/latest/rest-api/index.html#_resourceserverrepresentation. This is authorizationSettings in the Keycloak REST API.

        +
        +
        +
        +

        backchannel_logout_url

        + +

        aliases: backchannelLogoutUrl

        +

        + string +

        +
        +
        +

        URL that will cause the client to log itself out when a logout request is sent to this realm.

        +

        This is stored as backchannel.logout.url in the client attributes.

        +
        + +
        @@ -669,10 +682,10 @@ Parameters

        -

        Default URL to use when the auth server needs to redirect or link back to the client This is 'baseUrl' in the Keycloak REST API.

        +

        Default URL to use when the auth server needs to redirect or link back to the client This is baseUrl in the Keycloak REST API.

        - +
        @@ -684,7 +697,7 @@ Parameters

        -

        The access type of this client is bearer-only. This is 'bearerOnly' in the Keycloak REST API.

        +

        The access type of this client is bearer-only. This is bearerOnly in the Keycloak REST API.

        Choices:

        • false

          • @@ -693,7 +706,7 @@ Parameters
        - +
        @@ -706,7 +719,7 @@ Parameters

        How do clients authenticate with the auth server? Either client-secret, client-jwt, or client-x509 can be chosen. When using client-secret, the module parameter secret can set it, for client-jwt, you can use the keys use.jwks.url, jwks.url, and jwt.credential.certificate in the attributes module parameter to configure its behavior. For client-x509 you can use the keys x509.allow.regex.pattern.comparison and x509.subjectdn in the attributes module parameter to configure which certificate(s) to accept.

        -

        This is 'clientAuthenticatorType' in the Keycloak REST API.

        +

        This is clientAuthenticatorType in the Keycloak REST API.

        Choices:

        • "client-secret"

          • @@ -716,7 +729,7 @@ Parameters
        - +
        @@ -728,7 +741,32 @@ Parameters

        -

        Client id of client to be worked on. This is usually an alphanumeric name chosen by you. Either this or id is required. If you specify both, id takes precedence. This is 'clientId' in the Keycloak REST API.

        +

        Client ID of client to be worked on. This is usually an alphanumeric name chosen by you. Either this or id is required. If you specify both, id takes precedence. This is clientId in the Keycloak REST API.

        +
        + + +
        +
        +
        +

        client_scopes_behavior

        + +

        aliases: clientScopesBehavior

        +

        + string +

        +
        +
        +

        Determine how default_client_scopes and optional_client_scopes behave when updating an existing client.

        +

        ignore: Do not change the client scopes of an existing client. This is the default for backward compatibility.

        +

        patch: Add missing scopes, do not remove any missing scopes.

        +

        idempotent: Make the client scopes exactly as specified, adding and removing scopes as needed.

        +

        Choices:

        +
          +

        • "ignore" ← (default)

          • +

        • "patch"

          • +

        • "idempotent"

          • +
        +
        @@ -743,7 +781,7 @@ Parameters

        -

        Client template to use for this client. If it does not exist this field will silently be dropped. This is 'clientTemplate' in the Keycloak REST API.

        +

        Client template to use for this client. If it does not exist this field is silently dropped. This is clientTemplate in the Keycloak REST API.

        @@ -754,7 +792,6 @@ Parameters

        integer

        -

        added in middleware_automation.keycloak 4.5.0

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        @@ -773,7 +810,7 @@ Parameters

        -

        If enabled, users have to consent to client access. This is 'consentRequired' in the Keycloak REST API.

        +

        If enabled, users have to consent to client access. This is consentRequired in the Keycloak REST API.

        Choices:

        • false

          • @@ -793,10 +830,10 @@ Parameters list / elements=string

          -

          added in middleware_automation.keycloak 4.7.0

        List of default client scopes.

        +

        See client_scopes_behavior for how this behaves when updating an existing client.

        @@ -812,7 +849,7 @@ Parameters

        -

        list of default roles for this client. If the client roles referenced do not exist yet, they will be created. This is 'defaultRoles' in the Keycloak REST API.

        +

        List of default roles for this client. If the client roles referenced do not exist yet, they are created. This is defaultRoles in the Keycloak REST API.

        @@ -840,7 +877,7 @@ Parameters

        -

        Are direct access grants enabled for this client or not (OpenID connect). This is 'directAccessGrantsEnabled' in the Keycloak REST API.

        +

        Are direct access grants enabled for this client or not (OpenID connect). This is directAccessGrantsEnabled in the Keycloak REST API.

        Choices:

        • false

          • @@ -880,7 +917,7 @@ Parameters

        -

        Is frontchannel logout enabled for this client or not. This is 'frontchannelLogout' in the Keycloak REST API.

        +

        Is frontchannel logout enabled for this client or not. This is frontchannelLogout in the Keycloak REST API.

        Choices:

        • false

          • @@ -901,7 +938,7 @@ Parameters

        -

        Is the "Full Scope Allowed" feature set for this client or not. This is 'fullScopeAllowed' in the Keycloak REST API.

        +

        Is the "Full Scope Allowed" feature set for this client or not. This is fullScopeAllowed in the Keycloak REST API.

        Choices:

        • false

          • @@ -918,7 +955,6 @@ Parameters

          string

          -

          added in middleware_automation.keycloak 5.4.0

        Configures the HTTP User-Agent header.

        @@ -935,7 +971,7 @@ Parameters

        -

        Id of client to be worked on. This is usually an UUID. Either this or client_id is required. If you specify both, this takes precedence.

        +

        ID of client to be worked on. This is usually an UUID. Either this or client_id is required. If you specify both, this takes precedence.

        @@ -950,7 +986,7 @@ Parameters

        -

        Enable implicit flow for this client or not (OpenID connect). This is 'implicitFlowEnabled' in the Keycloak REST API.

        +

        Enable implicit flow for this client or not (OpenID connect). This is implicitFlowEnabled in the Keycloak REST API.

        Choices:

        • false

          • @@ -984,7 +1020,7 @@ Parameters

        -

        Cluster node re-registration timeout for this client. This is 'nodeReRegistrationTimeout' in the Keycloak REST API.

        +

        Cluster node re-registration timeout for this client. This is nodeReRegistrationTimeout in the Keycloak REST API.

        @@ -999,7 +1035,7 @@ Parameters

        -

        Revoke any tokens issued before this date for this client (this is a UNIX timestamp). This is 'notBefore' in the Keycloak REST API.

        +

        Revoke any tokens issued before this date for this client (this is a UNIX timestamp). This is notBefore in the Keycloak REST API.

        @@ -1013,10 +1049,10 @@ Parameters list / elements=string

        -

        added in middleware_automation.keycloak 4.7.0

        List of optional client scopes.

        +

        See client_scopes_behavior for how this behaves when updating an existing client.

        @@ -1030,8 +1066,8 @@ Parameters

        Type of client.

        -

        At creation only, default value will be openid-connect if protocol is omitted.

        -

        The docker-v2 value was added in community.general 8.6.0.

        +

        At creation only, default value is openid-connect if protocol is omitted.

        +

        The docker-v2 value was added in middleware_automation.keycloak 8.6.0.

        Choices:

        • "openid-connect"

          • @@ -1054,7 +1090,7 @@ Parameters

        -

        a list of dicts defining protocol mappers for this client. This is 'protocolMappers' in the Keycloak REST API.

        +

        A list of dicts defining protocol mappers for this client. This is protocolMappers in the Keycloak REST API.

        @@ -1166,28 +1202,28 @@ Parameters

        The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide since this may be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:

        -

        docker-v2-allow-all-mapper

        -

        oidc-address-mapper

        -

        oidc-full-name-mapper

        -

        oidc-group-membership-mapper

        -

        oidc-hardcoded-claim-mapper

        -

        oidc-hardcoded-role-mapper

        -

        oidc-role-name-mapper

        -

        oidc-script-based-protocol-mapper

        -

        oidc-sha256-pairwise-sub-mapper

        -

        oidc-usermodel-attribute-mapper

        -

        oidc-usermodel-client-role-mapper

        -

        oidc-usermodel-property-mapper

        -

        oidc-usermodel-realm-role-mapper

        -

        oidc-usersessionmodel-note-mapper

        -

        saml-group-membership-mapper

        -

        saml-hardcode-attribute-mapper

        -

        saml-hardcode-role-mapper

        -

        saml-role-list-mapper

        -

        saml-role-name-mapper

        -

        saml-user-attribute-mapper

        -

        saml-user-property-mapper

        -

        saml-user-session-note-mapper

        +

        docker-v2-allow-all-mapper.

        +

        oidc-address-mapper.

        +

        oidc-full-name-mapper.

        +

        oidc-group-membership-mapper.

        +

        oidc-hardcoded-claim-mapper.

        +

        oidc-hardcoded-role-mapper.

        +

        oidc-role-name-mapper.

        +

        oidc-script-based-protocol-mapper.

        +

        oidc-sha256-pairwise-sub-mapper.

        +

        oidc-usermodel-attribute-mapper.

        +

        oidc-usermodel-client-role-mapper.

        +

        oidc-usermodel-property-mapper.

        +

        oidc-usermodel-realm-role-mapper.

        +

        oidc-usersessionmodel-note-mapper.

        +

        saml-group-membership-mapper.

        +

        saml-hardcode-attribute-mapper.

        +

        saml-hardcode-role-mapper.

        +

        saml-role-list-mapper.

        +

        saml-role-name-mapper.

        +

        saml-user-attribute-mapper.

        +

        saml-user-property-mapper.

        +

        saml-user-session-note-mapper.

        An exhaustive list of available mappers on your installation can be obtained on the admin console by going to Server Info -> Providers and looking under 'protocol-mapper'.

        @@ -1204,7 +1240,7 @@ Parameters

        -

        Is the access type for this client public or not. This is 'publicClient' in the Keycloak REST API.

        +

        Is the access type for this client public or not. This is publicClient in the Keycloak REST API.

        Choices:

        • false

          • @@ -1240,10 +1276,23 @@ Parameters

        -

        Acceptable redirect URIs for this client. This is 'redirectUris' in the Keycloak REST API.

        +

        Acceptable redirect URIs for this client. This is redirectUris in the Keycloak REST API.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +
        +

        Authentication refresh token for Keycloak API.

        +
        + +
        @@ -1255,10 +1304,10 @@ Parameters

        -

        dict of registered cluster nodes (with nodename as the key and last registration time as the value). This is 'registeredNodes' in the Keycloak REST API.

        +

        Dict of registered cluster nodes (with nodename as the key and last registration time as the value). This is registeredNodes in the Keycloak REST API.

        - +
        @@ -1270,10 +1319,10 @@ Parameters

        -

        The registration access token provides access for clients to the client registration service. This is 'registrationAccessToken' in the Keycloak REST API.

        +

        The registration access token provides access for clients to the client registration service. This is registrationAccessToken in the Keycloak REST API.

        - +
        @@ -1285,10 +1334,10 @@ Parameters

        -

        Root URL appended to relative URLs for this client. This is 'rootUrl' in the Keycloak REST API.

        +

        Root URL appended to relative URLs for this client. This is rootUrl in the Keycloak REST API.

        - +

        secret

        @@ -1298,10 +1347,10 @@ Parameters

        -

        When using client_authenticator_type=client-secret (the default), you can specify a secret here (otherwise one will be generated if it does not exit). If changing this secret, the module will not register a change currently (but the changed secret will be saved).

        +

        When using client_authenticator_type=client-secret (the default), you can specify a secret here (otherwise one is generated if it does not exit). If changing this secret, the module does not register a change currently (but the changed secret is saved).

        - +
        @@ -1313,7 +1362,7 @@ Parameters

        -

        Are service accounts enabled for this client or not (OpenID connect). This is 'serviceAccountsEnabled' in the Keycloak REST API.

        +

        Are service accounts enabled for this client or not (OpenID connect). This is serviceAccountsEnabled in the Keycloak REST API.

        Choices:

        • false

          • @@ -1322,7 +1371,7 @@ Parameters
        - +
        @@ -1334,7 +1383,7 @@ Parameters

        -

        Enable standard flow for this client or not (OpenID connect). This is 'standardFlowEnabled' in the Keycloak REST API.

        +

        Enable standard flow for this client or not (OpenID connect). This is standardFlowEnabled in the Keycloak REST API.

        Choices:

        • false

          • @@ -1343,7 +1392,7 @@ Parameters
        - +

        state

        @@ -1353,9 +1402,9 @@ Parameters

        -

        State of the client

        -

        On present, the client will be created (or updated if it exists already).

        -

        On absent, the client will be removed if it exists

        +

        State of the client.

        +

        On present, the client are created (or updated if it exists already).

        +

        On absent, the client are removed if it exists.

        Choices:

        • "present" ← (default)

          • @@ -1364,7 +1413,7 @@ Parameters
        - +
        @@ -1376,7 +1425,7 @@ Parameters

        -

        Whether or not surrogate auth is required. This is 'surrogateAuthRequired' in the Keycloak REST API.

        +

        Whether or not surrogate auth is required. This is surrogateAuthRequired in the Keycloak REST API.

        Choices:

        • false

          • @@ -1385,7 +1434,7 @@ Parameters
        - +

        token

        @@ -1393,13 +1442,12 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 3.0.0

        Authentication token for Keycloak API.

        - +
        @@ -1411,7 +1459,7 @@ Parameters

        -

        Whether or not to use configuration from the client_template. This is 'useTemplateConfig' in the Keycloak REST API.

        +

        Whether or not to use configuration from the client_template. This is useTemplateConfig in the Keycloak REST API.

        Choices:

        • false

          • @@ -1420,7 +1468,7 @@ Parameters
        - +
        @@ -1432,7 +1480,7 @@ Parameters

        -

        Whether or not to use mapper configuration from the client_template. This is 'useTemplateMappers' in the Keycloak REST API.

        +

        Whether or not to use mapper configuration from the client_template. This is useTemplateMappers in the Keycloak REST API.

        Choices:

        • false

          • @@ -1441,7 +1489,7 @@ Parameters
        - +
        @@ -1453,7 +1501,7 @@ Parameters

        -

        Whether or not to use scope configuration from the client_template. This is 'useTemplateScope' in the Keycloak REST API.

        +

        Whether or not to use scope configuration from the client_template. This is useTemplateScope in the Keycloak REST API.

        Choices:

        • false

          • @@ -1462,6 +1510,24 @@ Parameters
        + +
        +
        +
        +

        valid_post_logout_redirect_uris

        + +

        aliases: postLogoutRedirectUris

        +

        + list + / elements=string +

        +
        +
        +

        Valid post logout redirect URIs for this client.

        +

        This is stored as post.logout.redirect.uris in the client attributes.

        +

        Use + as a single list element to allow all redirect URIs.

        +
        +
        @@ -1494,7 +1560,7 @@ Parameters

        -

        List of allowed CORS origins. This is 'webOrigins' in the Keycloak REST API.

        +

        List of allowed CORS origins. This is webOrigins in the Keycloak REST API.

        @@ -1520,6 +1586,50 @@ Attributes - Support - Description + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_client_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + * - .. raw:: html
        @@ -1620,7 +1730,7 @@ Examples - name: Create or update Keycloak client (minimal example), authentication with credentials middleware_automation.keycloak.keycloak_client: - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com auth_realm: master auth_username: USERNAME auth_password: PASSWORD @@ -1632,7 +1742,7 @@ Examples - name: Create or update Keycloak client (minimal example), authentication with token middleware_automation.keycloak.keycloak_client: auth_client_id: admin-cli - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com auth_realm: master token: TOKEN client_id: test @@ -1643,7 +1753,7 @@ Examples - name: Delete a Keycloak client middleware_automation.keycloak.keycloak_client: auth_client_id: admin-cli - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com auth_realm: master auth_username: USERNAME auth_password: PASSWORD @@ -1655,7 +1765,7 @@ Examples - name: Create or update a Keycloak client (minimal example), with x509 authentication middleware_automation.keycloak.keycloak_client: auth_client_id: admin-cli - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com auth_realm: master auth_username: USERNAME auth_password: PASSWORD @@ -1671,7 +1781,7 @@ Examples - name: Create or update a Keycloak client (with all the bells and whistles) middleware_automation.keycloak.keycloak_client: auth_client_id: admin-cli - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com auth_realm: master auth_username: USERNAME auth_password: PASSWORD @@ -1718,7 +1828,7 @@ Examples - test01 - test02 authentication_flow_binding_overrides: - browser: 4c90336b-bf1d-4b87-916d-3677ba4e5fbb + browser: 4c90336b-bf1d-4b87-916d-3677ba4e5fbb protocol_mappers: - config: access.token.claim: true @@ -1853,6 +1963,7 @@ Authors ~~~~~~~ - Eike Frost (@eikef) +- Ivan Kokalović (@koke1997) .. Extra links diff --git a/main/_sources/plugins/keycloak_client_rolemapping.rst.txt b/main/_sources/plugins/keycloak_client_rolemapping.rst.txt new file mode 100644 index 0000000..504658b --- /dev/null +++ b/main/_sources/plugins/keycloak_client_rolemapping.rst.txt @@ -0,0 +1,761 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_client_rolemapping_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_client_rolemapping -- Allows administration of Keycloak client\_rolemapping with the Keycloak API +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_client_rolemapping`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to add, remove or modify Keycloak client\_rolemapping with the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/latest/rest\-api/index.html `__. +- Attributes are multi\-valued in the Keycloak API. All attributes are lists of individual values and are returned that way by this module. You may pass single values for attributes when calling the module, and this is translated into a list suitable for the API. +- When updating a client\_rolemapping, where possible provide the role ID to the module. This removes a lookup to the API to translate the name into the role ID. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        cid

        + +

        + string +

        +
        +

        ID of the client to be mapped.

        +

        This parameter is not required for updating or deleting the rolemapping but providing it reduces the number of API calls required.

        +
        +
        +

        client_id

        + +

        + string +

        +
        +

        Name of the client to be mapped (different than cid).

        +

        This parameter is required (can be replaced by cid for less API call).

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        gid

        + +

        + string +

        +
        +

        ID of the group to be mapped.

        +

        This parameter is not required for updating or deleting the rolemapping but providing it reduces the number of API calls required.

        +
        +
        +

        group_name

        + +

        + string +

        +
        +

        Name of the group to be mapped.

        +

        This parameter is required (can be replaced by gid for less API call).

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        parents

        + +

        + list + / elements=dictionary +

        +
        +

        List of parent groups for the group to handle sorted top to bottom.

        +

        Set this if your group is a subgroup and you do not provide the GID in gid.

        +
        +
        +

        id

        + +

        + string +

        +
        +

        Identify parent by ID.

        +

        Needs less API calls than using parents[].name.

        +

        A deep parent chain can be started at any point when first given parent is given as ID.

        +

        Note that in principle both ID and name can be specified at the same time but current implementation only always use just one of them, with ID being preferred.

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Identify parent by name.

        +

        Needs more internal API calls than using parents[].id to map names to ID's under the hood.

        +

        When giving a parent chain with only names it must be complete up to the top.

        +

        Note that in principle both ID and name can be specified at the same time but current implementation only always use just one of them, with ID being preferred.

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        They Keycloak realm under which this role_representation resides.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        roles

        + +

        + list + / elements=dictionary +

        +
        +

        Roles to be mapped to the group.

        +
        +
        +

        id

        + +

        + string +

        +
        +

        The unique identifier for this role_representation.

        +

        This parameter is not required for updating or deleting a role_representation but providing it reduces the number of API calls required.

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the role_representation.

        +

        This parameter is required only when creating or updating the role_representation.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the client_rolemapping.

        +

        On present, the client_rolemapping is created if it does not yet exist, or updated with the parameters you provide.

        +

        On absent, the client_rolemapping is removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_client_rolemapping_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_client_rolemapping_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_client_rolemapping_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Map a client role to a group, authentication with credentials + middleware_automation.keycloak.keycloak_client_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + state: present + client_id: client1 + group_name: group1 + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + - name: Map a client role to a group, authentication with token + middleware_automation.keycloak.keycloak_client_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + state: present + client_id: client1 + group_name: group1 + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + - name: Map a client role to a subgroup, authentication with token + middleware_automation.keycloak.keycloak_client_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + state: present + client_id: client1 + group_name: subgroup1 + parents: + - name: parent-group + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + - name: Unmap client role from a group + middleware_automation.keycloak.keycloak_client_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + state: absent + client_id: client1 + group_name: group1 + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of client role mapping after module execution.

        +

        The sample is truncated.

        +

        Returned: on success

        +

        Sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}

        +
        +
        +

        existing

        + +

        + dictionary +

        +
        +

        Representation of existing client role mapping.

        +

        The sample is truncated.

        +

        Returned: always

        +

        Sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +

        Sample: "Role role1 assigned to group group1."

        +
        +
        +

        proposed

        + +

        + dictionary +

        +
        +

        Representation of proposed client role mapping.

        +

        Returned: always

        +

        Sample: {"clientId": "test"}

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Gaëtan Daubresse (@Gaetan2907) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_client_rolescope.rst.txt b/main/_sources/plugins/keycloak_client_rolescope.rst.txt new file mode 100644 index 0000000..7b061d1 --- /dev/null +++ b/main/_sources/plugins/keycloak_client_rolescope.rst.txt @@ -0,0 +1,595 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_client_rolescope_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_client_rolescope -- Allows administration of Keycloak client roles scope to restrict the usage of certain roles to a other specific client applications +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_client_rolescope`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to add or remove Keycloak roles from clients scope using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- Client :ansopt:`middleware\_automation.keycloak.keycloak\_client\_rolescope#module:client\_id` must have :ansopt:`middleware\_automation.keycloak.keycloak\_client#module:full\_scope\_allowed` set to :ansval:`false`. +- Attributes are multi\-valued in the Keycloak API. All attributes are lists of individual values and are returned that way by this module. You may pass single values for attributes when calling the module, and this is translated into a list suitable for the API. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        client_id

        + +

        + string + / required +

        +
        +

        Roles provided in role_names while be added to this client scope.

        +
        +
        +

        client_scope_id

        + +

        + string +

        +
        +

        If the role_names are client role, the client ID under which it resides.

        +

        If this parameter is absent, the roles are considered a realm role.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        The Keycloak realm under which clients resides.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        role_names

        + +

        + list + / elements=string + / required +

        +
        +

        Names of roles to manipulate.

        +

        If client_scope_id is present, all roles must be under this client.

        +

        If client_scope_id is absent, all roles must be under the realm.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the role mapping.

        +

        On present, all roles in role_names are mapped if not exist yet.

        +

        On absent, all roles mapping in role_names are removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_client_rolescope_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_client_rolescope_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_client_rolescope_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Add roles to public client scope + middleware_automation.keycloak.keycloak_client_rolescope: + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + realm: MyCustomRealm + client_id: frontend-client-public + client_scope_id: backend-client-private + role_names: + - backend-role-admin + - backend-role-user + + - name: Remove roles from public client scope + middleware_automation.keycloak.keycloak_client_rolescope: + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + realm: MyCustomRealm + client_id: frontend-client-public + client_scope_id: backend-client-private + role_names: + - backend-role-admin + state: absent + + - name: Add realm roles to public client scope + middleware_automation.keycloak.keycloak_client_rolescope: + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + realm: MyCustomRealm + client_id: frontend-client-public + role_names: + - realm-role-admin + - realm-role-user + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + list + / elements=dictionary +

        +
        +

        Representation of role role scope after module execution.

        +

        Returned: on success

        +

        Sample: [{"clientRole": false, "composite": false, "containerId": "MyCustomRealm", "id": "47293104-59a6-46f0-b460-2e9e3c9c424c", "name": "backend-role-admin"}, {"clientRole": false, "composite": false, "containerId": "MyCustomRealm", "id": "39c62a6d-542c-4715-92d2-41021eb33967", "name": "backend-role-user"}]

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +

        Sample: "Client role scope for frontend-client-public has been updated"

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Andre Desrosiers (@desand01) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_client_scope.rst.txt b/main/_sources/plugins/keycloak_client_scope.rst.txt index d04c7f2..f146675 100644 --- a/main/_sources/plugins/keycloak_client_scope.rst.txt +++ b/main/_sources/plugins/keycloak_client_scope.rst.txt @@ -33,6 +33,9 @@ keycloak_client_scope -- Allows administration of Keycloak client scopes via Key .. version_added +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 .. contents:: :local: @@ -182,7 +185,6 @@ Parameters

        integer

        -

        added in middleware_automation.keycloak 4.5.0

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        @@ -211,7 +213,6 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 5.4.0

        Configures the HTTP User-Agent header.

        @@ -341,6 +342,19 @@ Parameters
        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +
        +

        Authentication refresh token for Keycloak API.

        +
        + +

        state

        @@ -361,7 +375,7 @@ Parameters
        - +

        token

        @@ -369,13 +383,12 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 3.0.0

        Authentication token for Keycloak API.

        - +

        validate_certs

        @@ -417,6 +430,48 @@ Attributes - Support - Description + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_client_scope_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + * - .. raw:: html
        diff --git a/main/_sources/plugins/keycloak_clientscope_rolemappings.rst.txt b/main/_sources/plugins/keycloak_clientscope_rolemappings.rst.txt new file mode 100644 index 0000000..aa53f82 --- /dev/null +++ b/main/_sources/plugins/keycloak_clientscope_rolemappings.rst.txt @@ -0,0 +1,579 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_clientscope_rolemappings_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_clientscope_rolemappings -- Allows administration of Keycloak clientscope scope mappings to restrict the usage of certain roles to specific clientscopes ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_clientscope_rolemappings`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to add or remove Keycloak roles from clientscopes using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, :literal:`admin\-cli` and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- Attributes are multi\-valued in the Keycloak API. All attributes are lists of individual values and are returned that way by this module. You may pass single values for attributes when calling the module, and this is translated into a list suitable for the API. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        client_id

        + +

        + string +

        +
        +

        If the role_names are client roles, the client ID under which it resides.

        +

        If this parameter is absent, the roles are considered realm roles.

        +
        +
        +

        clientscope_id

        + +

        + string + / required +

        +
        +

        Roles provided in role_names will be added to this clientscope.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        The Keycloak realm under which clients resides.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        role_names

        + +

        + list + / elements=string + / required +

        +
        +

        Names of roles to add.

        +

        If client_id is present, all roles must be under this client.

        +

        If client_id is absent, all roles must be under the realm.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the role mapping.

        +

        On present, all roles in role_names are mapped if not exist yet.

        +

        On absent, all roles mapping in role_names are removed if they exist.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientscope_rolemappings_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientscope_rolemappings_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientscope_rolemappings_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Add roles to clientscope + middleware_automation.keycloak.keycloak_clientscope_rolemappings: + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + realm: MyCustomRealm + client_id: frontend-client-public + clientscope_id: frontend-clientscope + role_names: + - backend-role-admin + - backend-role-user + + - name: Remove roles from clientscope + middleware_automation.keycloak.keycloak_clientscope_rolemappings: + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + realm: MyCustomRealm + client_id: frontend-client-public + clientscope_id: frontend-clientscope + role_names: + - backend-role-admin + state: absent + + - name: Add realm roles to clientscope + middleware_automation.keycloak.keycloak_clientscope_rolemappings: + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + realm: MyCustomRealm + clientscope_id: frontend-clientscope + role_names: + - realm-role-admin + - realm-role-user + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + list + / elements=dictionary +

        +
        +

        Representation of clientscope scope mappings after module execution.

        +

        Returned: on success

        +

        Sample: [{"clientRole": false, "composite": false, "containerId": "77f9bd4e-13a6-451e-9c72-ee6997299c1f", "description": "User role", "id": "9e155ef7-86f5-4def-b507-581ce7b87013", "name": "realm-role-user"}, {"clientRole": false, "composite": false, "containerId": "77f9bd4e-13a6-451e-9c72-ee6997299c1f", "description": "Admin role", "id": "9e155ef7-86f5-4def-b507-581ce7b87013", "name": "realm-role-admin"}]

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Felix Grzelka (@felix-grzelka) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_clientscope_type.rst.txt b/main/_sources/plugins/keycloak_clientscope_type.rst.txt new file mode 100644 index 0000000..0350ce0 --- /dev/null +++ b/main/_sources/plugins/keycloak_clientscope_type.rst.txt @@ -0,0 +1,585 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_clientscope_type_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_clientscope_type -- Set the type of aclientscope in realm or client using Keycloak API ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_clientscope_type`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to set the type (optional, default) of clientscopes using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +
        +

        client_id

        + +

        aliases: clientId

        +

        + string +

        +
        +

        The client_id of the client. If not set the clientscope types are set as a default for the realm.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        default_clientscopes

        + +

        + list + / elements=string +

        +
        +

        Client scopes that should be of type default.

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        optional_clientscopes

        + +

        + list + / elements=string +

        +
        +

        Client scopes that should be of type optional.

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        The Keycloak realm.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientscope_type_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientscope_type_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientscope_type_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Set default client scopes on realm level + middleware_automation.keycloak.keycloak_clientscope_type: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + realm: "MyCustomRealm" + default_clientscopes: ['profile', 'roles'] + delegate_to: localhost + + + - name: Set default and optional client scopes on client level with token auth + middleware_automation.keycloak.keycloak_clientscope_type: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + realm: "MyCustomRealm" + client_id: "MyCustomClient" + default_clientscopes: ['profile', 'roles'] + optional_clientscopes: ['phone'] + delegate_to: localhost + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of client scopes after module execution.

        +

        The sample is truncated.

        +

        Returned: on success

        +

        Sample: {"default_clientscopes": ["profile", "role"], "optional_clientscopes": []}

        +
        +
        +

        existing

        + +

        + dictionary +

        +
        +

        Representation of client scopes before module execution.

        +

        Returned: always

        +

        Sample: {"default_clientscopes": ["profile", "role"], "optional_clientscopes": ["phone"]}

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +

        Sample: ""

        +
        +
        +

        proposed

        + +

        + dictionary +

        +
        +

        Representation of proposed client-scope types mapping.

        +

        Returned: always

        +

        Sample: {"default_clientscopes": ["profile", "role"], "optional_clientscopes": []}

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Simon Pahl (@simonpahl) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_clientsecret_info.rst.txt b/main/_sources/plugins/keycloak_clientsecret_info.rst.txt new file mode 100644 index 0000000..4b018fe --- /dev/null +++ b/main/_sources/plugins/keycloak_clientsecret_info.rst.txt @@ -0,0 +1,595 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_clientsecret_info_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_clientsecret_info -- Retrieve client secret using Keycloak API ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_clientsecret_info`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to get a Keycloak client secret using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- When retrieving a new client secret, where possible provide the client's :ansopt:`middleware\_automation.keycloak.keycloak\_clientsecret\_info#module:id` (not :ansopt:`middleware\_automation.keycloak.keycloak\_clientsecret\_info#module:client\_id`\ ) to the module. This removes a lookup to the API to translate the :ansopt:`middleware\_automation.keycloak.keycloak\_clientsecret\_info#module:client\_id` into the client ID. +- Note that this module returns the client secret. To avoid this showing up in the logs, please add :literal:`no\_log: true` to the task. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +
        +

        client_id

        + +

        aliases: clientId

        +

        + string +

        +
        +

        The client_id of the client. Passing this instead of id results in an extra API call.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        id

        + +

        + string +

        +
        +

        The unique identifier for this client.

        +

        This parameter is not required for getting or generating a client secret but providing it reduces the number of API calls required.

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        They Keycloak realm under which this client resides.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientsecret_info_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientsecret_info_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + This action does not modify state. + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientsecret_info_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ ` \ :ansible-attribute-support-na:`N/A` + + This action does not modify state. + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Get a Keycloak client secret, authentication with credentials + middleware_automation.keycloak.keycloak_clientsecret_info: + id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd' + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + delegate_to: localhost + no_log: true + + - name: Get a new Keycloak client secret, authentication with token + middleware_automation.keycloak.keycloak_clientsecret_info: + id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd' + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + delegate_to: localhost + no_log: true + + - name: Get a new Keycloak client secret, passing client_id instead of id + middleware_automation.keycloak.keycloak_clientsecret_info: + client_id: 'myClientId' + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + delegate_to: localhost + no_log: true + + - name: Get a new Keycloak client secret, authentication with auth_client_id and auth_client_secret + middleware_automation.keycloak.keycloak_clientsecret_info: + id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd' + realm: MyCustomRealm + auth_client_id: admin-cli + auth_client_secret: SECRET + auth_keycloak_url: https://auth.example.com + delegate_to: localhost + no_log: true + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        clientsecret_info

        + +

        + complex +

        +
        +

        Representation of the client secret.

        +

        Returned: on success

        +
        +
        +

        type

        + +

        + string +

        +
        +

        Credential type.

        +

        Returned: always

        +

        Sample: "secret"

        +
        +
        +

        value

        + +

        + string +

        +
        +

        Client secret.

        +

        Returned: always

        +

        Sample: "cUGnX1EIeTtPPAkcyGMv0ncyqDPu68P1"

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Textual description of whether we succeeded or failed.

        +

        Returned: always

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Fynn Chen (@fynncfchen) +- John Cant (@johncant) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_clientsecret_regenerate.rst.txt b/main/_sources/plugins/keycloak_clientsecret_regenerate.rst.txt new file mode 100644 index 0000000..49b226c --- /dev/null +++ b/main/_sources/plugins/keycloak_clientsecret_regenerate.rst.txt @@ -0,0 +1,591 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_clientsecret_regenerate_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_clientsecret_regenerate -- Regenerate Keycloak client secret using Keycloak API +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_clientsecret_regenerate`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to regenerate a Keycloak client secret using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- When regenerating a client secret, where possible provide the client's ID (not client\_id) to the module. This removes a lookup to the API to translate the client\_id into the client ID. +- Note that this module returns the client secret. To avoid this showing up in the logs, please add :literal:`no\_log: true` to the task. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +
        +

        client_id

        + +

        aliases: clientId

        +

        + string +

        +
        +

        The client_id of the client. Passing this instead of ID results in an extra API call.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        id

        + +

        + string +

        +
        +

        The unique identifier for this client.

        +

        This parameter is not required for getting or generating a client secret but providing it reduces the number of API calls required.

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        They Keycloak realm under which this client resides.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientsecret_regenerate_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientsecret_regenerate_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clientsecret_regenerate_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-none:`none` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Regenerate a Keycloak client secret, authentication with credentials + middleware_automation.keycloak.keycloak_clientsecret_regenerate: + id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd' + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + delegate_to: localhost + no_log: true + + - name: Regenerate a Keycloak client secret, authentication with token + middleware_automation.keycloak.keycloak_clientsecret_regenerate: + id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd' + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + delegate_to: localhost + no_log: true + + - name: Regenerate a Keycloak client secret, passing client_id instead of id + middleware_automation.keycloak.keycloak_clientsecret_info: + client_id: 'myClientId' + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + delegate_to: localhost + no_log: true + + - name: Regenerate a new Keycloak client secret, authentication with auth_client_id and auth_client_secret + middleware_automation.keycloak.keycloak_clientsecret_regenerate: + id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd' + realm: MyCustomRealm + auth_client_id: admin-cli + auth_client_secret: SECRET + auth_keycloak_url: https://auth.example.com + delegate_to: localhost + no_log: true + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + complex +

        +
        +

        Representation of the client credential after module execution.

        +

        Returned: on success

        +
        +
        +

        type

        + +

        + string +

        +
        +

        Credential type.

        +

        Returned: always

        +

        Sample: "secret"

        +
        +
        +

        value

        + +

        + string +

        +
        +

        Client secret.

        +

        Returned: always

        +

        Sample: "cUGnX1EIeTtPPAkcyGMv0ncyqDPu68P1"

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Fynn Chen (@fynncfchen) +- John Cant (@johncant) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_clienttemplate.rst.txt b/main/_sources/plugins/keycloak_clienttemplate.rst.txt new file mode 100644 index 0000000..19589d1 --- /dev/null +++ b/main/_sources/plugins/keycloak_clienttemplate.rst.txt @@ -0,0 +1,839 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_clienttemplate_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_clienttemplate -- Allows administration of Keycloak client templates using Keycloak API +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_clienttemplate`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows the administration of Keycloak client templates using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/latest/rest\-api/index.html `__. +- The Keycloak API does not always enforce for only sensible settings to be used \-\- you can set SAML\-specific settings on an OpenID Connect client for instance and the other way around. Be careful. If you do not specify a setting, usually a sensible default is chosen. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        attributes

        + +

        + dictionary +

        +
        +

        A dict of further attributes for this client template. This can contain various configuration settings, though in the default installation of Keycloak as of 3.4, none are documented or known, so this is usually empty.

        +
        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        description

        + +

        + string +

        +
        +

        Description of the client template in Keycloak.

        +
        +
        +

        full_scope_allowed

        + +

        + boolean +

        +
        +

        Is the "Full Scope Allowed" feature set for this client template or not. This is fullScopeAllowed in the Keycloak REST API.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        id

        + +

        + string +

        +
        +

        ID of client template to be worked on. This is usually a UUID.

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the client template.

        +
        +
        +

        protocol

        + +

        + string +

        +
        +

        Type of client template.

        +

        The docker-v2 value was added in middleware_automation.keycloak 8.6.0.

        +

        Choices:

        +
          +

        • "openid-connect"

          • +

        • "saml"

          • +

        • "docker-v2"

          • +
        + +
        +
        +

        protocol_mappers

        + +

        + list + / elements=dictionary +

        +
        +

        A list of dicts defining protocol mappers for this client template. This is protocolMappers in the Keycloak REST API.

        +
        +
        +

        config

        + +

        + dictionary +

        +
        +

        Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value of protocol_mappers[].protocolMapper and are not documented other than by the source of the mappers and its parent class(es). An example is given below. It is easiest to obtain valid config values by dumping an already-existing protocol mapper configuration through check-mode in the existing field.

        +
        +
        +

        consentRequired

        + +

        + boolean +

        +
        +

        Specifies whether a user needs to provide consent to a client for this mapper to be active.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        consentText

        + +

        + string +

        +
        +

        The human-readable name of the consent the user is presented to accept.

        +
        +
        +

        id

        + +

        + string +

        +
        +

        Usually a UUID specifying the internal ID of this protocol mapper instance.

        +
        +
        +

        name

        + +

        + string +

        +
        +

        The name of this protocol mapper.

        +
        +
        +

        protocol

        + +

        + string +

        +
        +

        This specifies for which protocol this protocol mapper is active.

        +

        Choices:

        +
          +

        • "openid-connect"

          • +

        • "saml"

          • +

        • "docker-v2"

          • +
        + +
        +
        +

        protocolMapper

        + +

        + string +

        +
        +

        The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide since this may be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:

        +

        docker-v2-allow-all-mapper.

        +

        oidc-address-mapper.

        +

        oidc-full-name-mapper.

        +

        oidc-group-membership-mapper.

        +

        oidc-hardcoded-claim-mapper.

        +

        oidc-hardcoded-role-mapper.

        +

        oidc-role-name-mapper.

        +

        oidc-script-based-protocol-mapper.

        +

        oidc-sha256-pairwise-sub-mapper.

        +

        oidc-usermodel-attribute-mapper.

        +

        oidc-usermodel-client-role-mapper.

        +

        oidc-usermodel-property-mapper.

        +

        oidc-usermodel-realm-role-mapper.

        +

        oidc-usersessionmodel-note-mapper.

        +

        saml-group-membership-mapper.

        +

        saml-hardcode-attribute-mapper.

        +

        saml-hardcode-role-mapper.

        +

        saml-role-list-mapper.

        +

        saml-role-name-mapper.

        +

        saml-user-attribute-mapper.

        +

        saml-user-property-mapper.

        +

        saml-user-session-note-mapper.

        +

        An exhaustive list of available mappers on your installation can be obtained on the admin console by going to Server Info -> Providers and looking under 'protocol-mapper'.

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        Realm this client template is found in.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the client template.

        +

        On present, the client template is created (or updated if it exists already).

        +

        On absent, the client template is removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clienttemplate_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clienttemplate_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_clienttemplate_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + +Notes +----- + +.. note:: + - The Keycloak REST API defines further fields (namely :literal:`bearerOnly`\ , :literal:`consentRequired`\ , :literal:`standardFlowEnabled`\ , :literal:`implicitFlowEnabled`\ , :literal:`directAccessGrantsEnabled`\ , :literal:`serviceAccountsEnabled`\ , :literal:`publicClient`\ , and :literal:`frontchannelLogout`\ ) which, while available with keycloak\_client, do not have any effect on Keycloak client\-templates and are discarded if supplied with an API request changing client\-templates. As such, they are not available through this module. + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Create or update Keycloak client template (minimal), authentication with credentials + middleware_automation.keycloak.keycloak_client: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + realm: master + name: this_is_a_test + delegate_to: localhost + + - name: Create or update Keycloak client template (minimal), authentication with token + middleware_automation.keycloak.keycloak_clienttemplate: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + token: TOKEN + realm: master + name: this_is_a_test + delegate_to: localhost + + - name: Delete Keycloak client template + middleware_automation.keycloak.keycloak_client: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + realm: master + state: absent + name: test01 + delegate_to: localhost + + - name: Create or update Keycloak client template (with a protocol mapper) + middleware_automation.keycloak.keycloak_client: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + realm: master + name: this_is_a_test + protocol_mappers: + - config: + access.token.claim: true + claim.name: "family_name" + id.token.claim: true + jsonType.label: String + user.attribute: lastName + userinfo.token.claim: true + consentRequired: true + consentText: "${familyName}" + name: family name + protocol: openid-connect + protocolMapper: oidc-usermodel-property-mapper + full_scope_allowed: false + id: bce6f5e9-d7d3-4955-817e-c5b7f8d65b3f + delegate_to: localhost + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of client template after module execution (sample is truncated).

        +

        Returned: on success

        +

        Sample: {"description": "test01", "fullScopeAllowed": false, "id": "9c3712ab-decd-481e-954f-76da7b006e5f", "name": "test01", "protocol": "saml"}

        +
        +
        +

        existing

        + +

        + dictionary +

        +
        +

        Representation of existing client template (sample is truncated).

        +

        Returned: always

        +

        Sample: {"description": "test01", "fullScopeAllowed": false, "id": "9c3712ab-decd-481e-954f-76da7b006e5f", "name": "test01", "protocol": "saml"}

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +

        Sample: "Client template testclient has been updated"

        +
        +
        +

        proposed

        + +

        + dictionary +

        +
        +

        Representation of proposed client template.

        +

        Returned: always

        +

        Sample: {"name": "test01"}

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Eike Frost (@eikef) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_component.rst.txt b/main/_sources/plugins/keycloak_component.rst.txt new file mode 100644 index 0000000..fa5f2f4 --- /dev/null +++ b/main/_sources/plugins/keycloak_component.rst.txt @@ -0,0 +1,656 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_component_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_component -- Allows administration of Keycloak components using Keycloak API ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_component`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows the administration of Keycloak components using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default Keycloak installation, :literal:`admin\-cli` and an :literal:`admin` user would work, as would a separate realm definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/latest/rest\-api/index.html `__. Aliases are provided so camelCased versions can be used as well. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        config

        + +

        + dictionary +

        +
        +

        Configuration properties for the provider.

        +

        Contents vary depending on the provider type.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        name

        + +

        + string + / required +

        +
        +

        Name of the component to create.

        +
        +
        +

        parent_id

        + +

        + string + / required +

        +
        +

        The parent_id of the component. In practice the ID (name) of the realm.

        +
        +
        +

        provider_id

        + +

        + string + / required +

        +
        +

        The name of the "provider ID" for the key.

        +
        +
        +

        provider_type

        + +

        + string + / required +

        +
        +

        The name of the "provider type" for the key. That is, org.keycloak.storage.UserStorageProvider, org.keycloak.userprofile.UserProfileProvider, ...

        +

        See https://www.keycloak.org/docs/latest/server_development/index.html#_providers.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the Keycloak component.

        +

        On present, the component is created (or updated if it exists already).

        +

        On absent, the component is removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_component_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_component_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_component_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Manage Keycloak User Storage Provider + middleware_automation.keycloak.keycloak_component: + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + name: my storage provider + state: present + parent_id: some_realm + provider_id: my storage + provider_type: "org.keycloak.storage.UserStorageProvider" + config: + myCustomKey: "my_custom_key" + cachePolicy: "NO_CACHE" + enabled: true + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of the keycloak_component after module execution.

        +

        Returned: on success

        +
        +
        +

        config

        + +

        + dictionary +

        +
        +

        Component configuration.

        +

        Returned: success

        +
        +
        +

        id

        + +

        + string +

        +
        +

        ID of the component.

        +

        Returned: when state=present

        +

        Sample: "5b7ec13f-99da-46ad-8326-ab4c73cf4ce4"

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the component.

        +

        Returned: when state=present

        +

        Sample: "mykey"

        +
        +
        +

        parentId

        + +

        + string +

        +
        +

        ID of the realm this key belongs to.

        +

        Returned: when state=present

        +

        Sample: "myrealm"

        +
        +
        +

        providerId

        + +

        + string +

        +
        +

        The ID of the key provider.

        +

        Returned: when state=present

        +

        Sample: "rsa"

        +
        +
        +

        providerType

        + +

        + string +

        +
        +

        The type of provider.

        +

        Returned: when state=present

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Björn Bösel (@fivetide) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_component_info.rst.txt b/main/_sources/plugins/keycloak_component_info.rst.txt new file mode 100644 index 0000000..08d9314 --- /dev/null +++ b/main/_sources/plugins/keycloak_component_info.rst.txt @@ -0,0 +1,555 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_component_info_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_component_info -- Retrieve component info in Keycloak +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_component_info`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module retrieve information on component from Keycloak. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the Component.

        +
        +
        +

        parent_id

        + +

        + string +

        +
        +

        Container ID of the components.

        +
        +
        +

        provider_type

        + +

        + string +

        +
        +

        Provider type of components.

        +

        Examples: org.keycloak.storage.UserStorageProvider, org.keycloak.services.clientregistration.policy.ClientRegistrationPolicy, org.keycloak.keys.KeyProvider, org.keycloak.userprofile.UserProfileProvider, org.keycloak.storage.ldap.mappers.LDAPStorageMapper.

        +
        +
        +

        realm

        + +

        + string + / required +

        +
        +

        The name of the realm.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_component_info_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_component_info_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + This action does not modify state. + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_component_info_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ ` \ :ansible-attribute-support-na:`N/A` + + This action does not modify state. + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Retrive info of a UserStorageProvider named myldap + middleware_automation.keycloak.keycloak_component_info: + auth_keycloak_url: http://localhost:8080 + auth_username: admin + auth_password: password + auth_realm: master + realm: myrealm + name: myldap + provider_type: org.keycloak.storage.UserStorageProvider + + - name: Retrive key info component + middleware_automation.keycloak.keycloak_component_info: + auth_keycloak_url: http://localhost:8080 + auth_username: admin + auth_password: password + auth_realm: master + realm: myrealm + name: rsa-enc-generated + provider_type: org.keycloak.keys.KeyProvider + + - name: Retrive all component from realm master + middleware_automation.keycloak.keycloak_component_info: + auth_keycloak_url: http://localhost:8080 + auth_username: admin + auth_password: password + auth_realm: master + realm: myrealm + + - name: Retrive all sub components of parent component filter by type + middleware_automation.keycloak.keycloak_component_info: + auth_keycloak_url: http://localhost:8080 + auth_username: admin + auth_password: password + auth_realm: master + realm: myrealm + parent_id: "075ef2fa-19fc-4a6d-bf4c-249f57365fd2" + provider_type: "org.keycloak.storage.ldap.mappers.LDAPStorageMapper" + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        components

        + +

        + list + / elements=dictionary +

        +
        +

        JSON representation of components.

        +

        Returned: always

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Andre Desrosiers (@desand01) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_group.rst.txt b/main/_sources/plugins/keycloak_group.rst.txt new file mode 100644 index 0000000..65ff1d3 --- /dev/null +++ b/main/_sources/plugins/keycloak_group.rst.txt @@ -0,0 +1,864 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_group_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_group -- Allows administration of Keycloak groups using Keycloak API ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_group`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to add, remove or modify Keycloak groups using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/20.0.2/rest\-api/index.html `__. +- Attributes are multi\-valued in the Keycloak API. All attributes are lists of individual values and are returned that way by this module. You may pass single values for attributes when calling the module, and this is translated into a list suitable for the API. +- When updating a group, where possible provide the group ID to the module. This removes a lookup to the API to translate the name into the group ID. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        attributes

        + +

        + dictionary +

        +
        +

        A dict of key/value pairs to set as custom attributes for the group.

        +

        Values may be single values (for example a string) or a list of strings.

        +
        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        id

        + +

        + string +

        +
        +

        The unique identifier for this group.

        +

        This parameter is not required for updating or deleting a group but providing it reduces the number of API calls required.

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the group.

        +

        This parameter is required only when creating or updating the group.

        +
        +
        +

        parents

        + +

        + list + / elements=dictionary +

        +
        +

        List of parent groups for the group to handle sorted top to bottom.

        +

        Set this to create a group as a subgroup of another group or groups (parents) or when accessing an existing subgroup by name.

        +

        Not necessary to set when accessing an existing subgroup by its ID because in that case the group can be directly queried without necessarily knowing its parent(s).

        +
        +
        +

        id

        + +

        + string +

        +
        +

        Identify parent by ID.

        +

        Needs less API calls than using parents[].name.

        +

        A deep parent chain can be started at any point when first given parent is given as ID.

        +

        Note that in principle both ID and name can be specified at the same time but current implementation only always use just one of them, with ID being preferred.

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Identify parent by name.

        +

        Needs more internal API calls than using parents[].id to map names to ID's under the hood.

        +

        When giving a parent chain with only names it must be complete up to the top.

        +

        Note that in principle both ID and name can be specified at the same time but current implementation only always use just one of them, with ID being preferred.

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        They Keycloak realm under which this group resides.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the group.

        +

        On present, the group is created if it does not yet exist, or updated with the parameters you provide.

        +

        On absent, the group is removed if it exists. Be aware that absenting a group with subgroups automatically deletes all its subgroups too.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_group_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_group_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_group_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + +Notes +----- + +.. note:: + - Presently, the :ansretval:`middleware\_automation.keycloak.keycloak\_group#module:end\_state.realmRoles`\ , :ansretval:`middleware\_automation.keycloak.keycloak\_group#module:end\_state.clientRoles`\ , and :ansretval:`middleware\_automation.keycloak.keycloak\_group#module:end\_state.access` attributes returned by the Keycloak API are read\-only for groups. This limitation will be removed in a later version of this module. + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Create a Keycloak group, authentication with credentials + middleware_automation.keycloak.keycloak_group: + name: my-new-kc-group + realm: MyCustomRealm + state: present + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + register: result_new_kcgrp + delegate_to: localhost + + - name: Create a Keycloak group, authentication with token + middleware_automation.keycloak.keycloak_group: + name: my-new-kc-group + realm: MyCustomRealm + state: present + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + delegate_to: localhost + + - name: Delete a keycloak group + middleware_automation.keycloak.keycloak_group: + id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd' + state: absent + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + delegate_to: localhost + + - name: Delete a Keycloak group based on name + middleware_automation.keycloak.keycloak_group: + name: my-group-for-deletion + state: absent + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + delegate_to: localhost + + - name: Update the name of a Keycloak group + middleware_automation.keycloak.keycloak_group: + id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd' + name: an-updated-kc-group-name + state: present + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + delegate_to: localhost + + - name: Create a keycloak group with some custom attributes + middleware_automation.keycloak.keycloak_group: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + name: my-new_group + attributes: + attrib1: value1 + attrib2: value2 + attrib3: + - with + - numerous + - individual + - list + - items + delegate_to: localhost + + - name: Create a Keycloak subgroup of a base group (using parent name) + middleware_automation.keycloak.keycloak_group: + name: my-new-kc-group-sub + realm: MyCustomRealm + state: present + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + parents: + - name: my-new-kc-group + register: result_new_kcgrp_sub + delegate_to: localhost + + - name: Create a Keycloak subgroup of a base group (using parent id) + middleware_automation.keycloak.keycloak_group: + name: my-new-kc-group-sub2 + realm: MyCustomRealm + state: present + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + parents: + - id: "{{ result_new_kcgrp.end_state.id }}" + delegate_to: localhost + + - name: Create a Keycloak subgroup of a subgroup (using parent names) + middleware_automation.keycloak.keycloak_group: + name: my-new-kc-group-sub-sub + realm: MyCustomRealm + state: present + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + parents: + - name: my-new-kc-group + - name: my-new-kc-group-sub + delegate_to: localhost + + - name: Create a Keycloak subgroup of a subgroup (using direct parent id) + middleware_automation.keycloak.keycloak_group: + name: my-new-kc-group-sub-sub + realm: MyCustomRealm + state: present + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + parents: + - id: "{{ result_new_kcgrp_sub.end_state.id }}" + delegate_to: localhost + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + complex +

        +
        +

        Representation of the group after module execution (sample is truncated).

        +

        Returned: on success

        +
        +
        +

        access

        + +

        + dictionary +

        +
        +

        A dict describing the accesses you have to this group based on the credentials used.

        +

        Returned: always

        +

        Sample: {"manage": true, "manageMembership": true, "view": true}

        +
        +
        +

        attributes

        + +

        + dictionary +

        +
        +

        Attributes applied to this group.

        +

        Returned: always

        +

        Sample: {"attr1": ["val1", "val2", "val3"]}

        +
        +
        +

        clientRoles

        + +

        + list + / elements=string +

        +
        +

        A list of client-level roles granted to this group.

        +

        Returned: always

        +

        Sample: []

        +
        +
        +

        id

        + +

        + string +

        +
        +

        GUID that identifies the group.

        +

        Returned: always

        +

        Sample: "23f38145-3195-462c-97e7-97041ccea73e"

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the group.

        +

        Returned: always

        +

        Sample: "grp-test-123"

        +
        +
        +

        path

        + +

        + string +

        +
        +

        URI path to the group.

        +

        Returned: always

        +

        Sample: "/grp-test-123"

        +
        +
        +

        realmRoles

        + +

        + list + / elements=string +

        +
        +

        An array of the realm-level roles granted to this group.

        +

        Returned: always

        +

        Sample: []

        +
        +
        +

        subGroups

        + +

        + list + / elements=string +

        +
        +

        A list of groups that are children of this group. These groups have the same parameters as documented here.

        +

        Returned: always

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Adam Goossens (@adamgoossens) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_identity_provider.rst.txt b/main/_sources/plugins/keycloak_identity_provider.rst.txt new file mode 100644 index 0000000..e1b710e --- /dev/null +++ b/main/_sources/plugins/keycloak_identity_provider.rst.txt @@ -0,0 +1,1252 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_identity_provider_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_identity_provider -- Allows administration of Keycloak identity providers using Keycloak API ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_identity_provider`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to add, remove or modify Keycloak identity providers using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/15.0/rest\-api/index.html `__. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +
        +

        add_read_token_role_on_create

        + +

        aliases: addReadTokenRoleOnCreate

        +

        + boolean +

        +
        +

        Enable/disable whether new users can read any stored tokens. This assigns the broker.read-token role.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        alias

        + +

        + string + / required +

        +
        +

        The alias uniquely identifies an identity provider and it is also used to build the redirect URI.

        +
        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +
        +

        authenticate_by_default

        + +

        aliases: authenticateByDefault

        +

        + boolean +

        +
        +

        Specifies if this identity provider should be used by default for authentication even before displaying login screen.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        config

        + +

        + dictionary +

        +
        +

        Dict specifying the configuration options for the provider; the contents differ depending on the value of provider_id. Examples are given below for oidc and saml. It is easiest to obtain valid config values by dumping an already-existing identity provider configuration through check-mode in the existing field.

        +
        +
        +

        authorizationUrl

        + +

        + string +

        +
        +

        The Authorization URL.

        +
        +
        +

        backchannelSupported

        + +

        + string +

        +
        +

        Does the external IDP support backchannel logout?

        +
        +
        +

        clientAuthMethod

        + +

        + string +

        +
        +

        The client authentication method.

        +
        +
        +

        clientId

        + +

        + string +

        +
        +

        The client or client identifier registered within the identity provider.

        +
        +
        +

        clientSecret

        + +

        + string +

        +
        +

        The client or client secret registered within the identity provider.

        +
        +
        +

        defaultScope

        + +

        + string +

        +
        +

        The scopes to be sent when asking for authorization.

        +
        +
        +

        entityId

        + +

        + string +

        +
        +

        The Entity ID that is used to uniquely identify this SAML Service Provider.

        +
        +
        +

        fromUrl

        + +

        + string +

        +
        +

        IDP well-known OpenID Connect configuration URL.

        +

        Support only provider_id=oidc.

        +

        config.fromUrl is mutually exclusive with config.userInfoUrl, config.authorizationUrl, config.tokenUrl, config.logoutUrl, config.issuer and config.jwksUrl.

        +
        +
        +
        +

        gui_order

        + +

        aliases: guiOrder

        +

        + integer +

        +
        +

        Number defining order of the provider in GUI (for example, on Login page).

        +
        +
        +
        +

        hide_on_login_page

        + +

        aliases: hideOnLoginPage

        +

        + boolean +

        +
        +

        If hidden, login with this provider is possible only if requested explicitly, for example using the kc_idp_hint parameter.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        issuer

        + +

        + string +

        +
        +

        The issuer identifier for the issuer of the response. If not provided, no validation is performed.

        +
        +
        +

        jwksUrl

        + +

        + string +

        +
        +

        URL where identity provider keys in JWK format are stored. See JWK specification for more details.

        +
        +
        +

        logoutUrl

        + +

        + string +

        +
        +

        End session endpoint to use to logout user from external IDP.

        +
        +
        +

        nameIDPolicyFormat

        + +

        + string +

        +
        +

        Specifies the URI reference corresponding to a name identifier format.

        +
        +
        +

        principalType

        + +

        + string +

        +
        +

        Way to identify and track external users from the assertion.

        +
        +
        +

        singleLogoutServiceUrl

        + +

        + string +

        +
        +

        The URL that must be used to send logout requests.

        +
        +
        +

        singleSignOnServiceUrl

        + +

        + string +

        +
        +

        The URL that must be used to send authentication requests (SAML AuthnRequest).

        +
        +
        +
        +

        sync_mode

        + +

        aliases: syncMode

        +

        + string +

        +
        +

        Default sync mode for all mappers. The sync mode determines when user data is synced using the mappers.

        +
        +
        +

        tokenUrl

        + +

        + string +

        +
        +

        The Token URL.

        +
        +
        +

        useJwksUrl

        + +

        + boolean +

        +
        +

        If true, identity provider public keys are downloaded from given JWKS URL.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        userInfoUrl

        + +

        + string +

        +
        +

        The User Info URL.

        +
        +
        +

        validateSignature

        + +

        + boolean +

        +
        +

        Enable/disable signature validation of external IDP signatures.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +
        +

        display_name

        + +

        aliases: displayName

        +

        + string +

        +
        +

        Friendly name for identity provider.

        +
        +
        +

        enabled

        + +

        + boolean +

        +
        +

        Enable/disable this identity provider.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +
        +

        first_broker_login_flow_alias

        + +

        aliases: firstBrokerLoginFlowAlias

        +

        + string +

        +
        +

        Alias of authentication flow, which is triggered after first login with this identity provider.

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        + +
        +

        link_only

        + +

        aliases: linkOnly

        +

        + boolean +

        +
        +

        If true, users cannot log in through this provider. They can only link to this provider. This is useful if you do not want to allow login from the provider, but want to integrate with a provider.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        mappers

        + +

        + list + / elements=dictionary +

        +
        +

        A list of dicts defining mappers associated with this Identity Provider.

        +
        +
        +

        config

        + +

        + dictionary +

        +
        +

        Dict specifying the configuration options for the mapper; the contents differ depending on the value of mappers[].identityProviderMapper.

        +
        +
        +

        id

        + +

        + string +

        +
        +

        Unique ID of this mapper.

        +
        +
        +

        identityProviderAlias

        + +

        + string +

        +
        +

        Alias of the identity provider for this mapper.

        +
        +
        +

        identityProviderMapper

        + +

        + string +

        +
        +

        Type of mapper.

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the mapper.

        +
        +
        +
        +

        post_broker_login_flow_alias

        + +

        aliases: postBrokerLoginFlowAlias

        +

        + string +

        +
        +

        Alias of authentication flow, which is triggered after each login with this identity provider.

        +
        +
        +
        +

        provider_id

        + +

        aliases: providerId

        +

        + string +

        +
        +

        Protocol used by this provider (supported values are oidc or saml).

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        The Keycloak realm under which this identity provider resides.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the identity provider.

        +

        On present, the identity provider is created if it does not yet exist, or updated with the parameters you provide.

        +

        On absent, the identity provider is removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +
        +

        store_token

        + +

        aliases: storeToken

        +

        + boolean +

        +
        +

        Enable/disable whether tokens must be stored after authenticating users.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +
        +

        trust_email

        + +

        aliases: trustEmail

        +

        + boolean +

        +
        +

        If enabled, email provided by this provider is not verified even if verification is enabled for the realm.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_identity_provider_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_identity_provider_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_identity_provider_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Create OIDC identity provider, authentication with credentials + middleware_automation.keycloak.keycloak_identity_provider: + state: present + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: admin + auth_password: admin + realm: myrealm + alias: oidc-idp + display_name: OpenID Connect IdP + enabled: true + provider_id: oidc + config: + issuer: https://idp.example.com + authorizationUrl: https://idp.example.com + tokenUrl: https://idp.example.com/token + userInfoUrl: https://idp.example.com/userinfo + clientAuthMethod: client_secret_post + clientId: my-client + clientSecret: secret + syncMode: FORCE + mappers: + - name: first_name + identityProviderMapper: oidc-user-attribute-idp-mapper + config: + claim: first_name + user.attribute: first_name + syncMode: INHERIT + - name: last_name + identityProviderMapper: oidc-user-attribute-idp-mapper + config: + claim: last_name + user.attribute: last_name + syncMode: INHERIT + + - name: Create OIDC identity provider, with well-known configuration URL + middleware_automation.keycloak.keycloak_identity_provider: + state: present + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: admin + auth_password: admin + realm: myrealm + alias: oidc-idp + display_name: OpenID Connect IdP + enabled: true + provider_id: oidc + config: + fromUrl: https://the-idp.example.com/realms/idprealm/.well-known/openid-configuration + clientAuthMethod: client_secret_post + clientId: my-client + clientSecret: secret + + - name: Create SAML identity provider, authentication with credentials + middleware_automation.keycloak.keycloak_identity_provider: + state: present + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: admin + auth_password: admin + realm: myrealm + alias: saml-idp + display_name: SAML IdP + enabled: true + provider_id: saml + config: + entityId: https://auth.example.com/realms/myrealm + singleSignOnServiceUrl: https://idp.example.com/login + wantAuthnRequestsSigned: true + wantAssertionsSigned: true + mappers: + - name: roles + identityProviderMapper: saml-user-attribute-idp-mapper + config: + user.attribute: roles + attribute.friendly.name: User Roles + attribute.name: roles + syncMode: INHERIT + + - name: Create OIDC identity provider, authentication with credentials and advanced claim to group + middleware_automation.keycloak.keycloak_identity_provider: + state: present + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: admin + auth_password: admin + realm: myrealm + alias: oidc-idp + display_name: OpenID Connect IdP + enabled: true + provider_id: oidc + config: + issuer: https://idp.example.com + authorizationUrl: https://idp.example.com + tokenUrl: https://idp.example.com/token + userInfoUrl: https://idp.example.com/userinfo + clientAuthMethod: client_secret_post + clientId: my-client + clientSecret: secret + syncMode: FORCE + mappers: + - name: group_name + identityProviderMapper: oidc-advanced-group-idp-mapper + config: + claims: '[{"key":"my_key","value":"my_value"}]' + group: group_name + syncMode: INHERIT + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of identity provider after module execution.

        +

        Returned: on success

        +

        Sample: {"addReadTokenRoleOnCreate": false, "alias": "my-idp", "authenticateByDefault": false, "config": {"authorizationUrl": "https://idp.example.com", "clientAuthMethod": "client_secret_post", "clientId": "my-client", "clientSecret": "**********", "issuer": "https://idp.example.com", "tokenUrl": "https://idp.example.com/token", "userInfoUrl": "https://idp.example.com/userinfo"}, "displayName": "OpenID Connect IdP", "enabled": true, "firstBrokerLoginFlowAlias": "first broker login", "internalId": "4d28d7e3-1b80-45bb-8a30-5822bf55aa1c", "linkOnly": false, "providerId": "oidc", "storeToken": false, "trustEmail": false}

        +
        +
        +

        existing

        + +

        + dictionary +

        +
        +

        Representation of existing identity provider.

        +

        Returned: always

        +

        Sample: {"addReadTokenRoleOnCreate": false, "alias": "my-idp", "authenticateByDefault": false, "config": {"authorizationUrl": "https://old.example.com", "clientAuthMethod": "client_secret_post", "clientId": "my-client", "clientSecret": "**********", "issuer": "https://old.example.com", "syncMode": "FORCE", "tokenUrl": "https://old.example.com/token", "userInfoUrl": "https://old.example.com/userinfo"}, "displayName": "OpenID Connect IdP", "enabled": true, "firstBrokerLoginFlowAlias": "first broker login", "internalId": "4d28d7e3-1b80-45bb-8a30-5822bf55aa1c", "linkOnly": false, "providerId": "oidc", "storeToken": false, "trustEmail": false}

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +

        Sample: "Identity provider my-idp has been created"

        +
        +
        +

        proposed

        + +

        + dictionary +

        +
        +

        Representation of proposed identity provider.

        +

        Returned: always

        +

        Sample: {"config": {"authorizationUrl": "https://idp.example.com", "clientAuthMethod": "client_secret_post", "clientId": "my-client", "clientSecret": "secret", "issuer": "https://idp.example.com", "tokenUrl": "https://idp.example.com/token", "userInfoUrl": "https://idp.example.com/userinfo"}, "displayName": "OpenID Connect IdP", "providerId": "oidc"}

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Laurent Paumier (@laurpaum) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_realm.rst.txt b/main/_sources/plugins/keycloak_realm.rst.txt index 5620921..29a9058 100644 --- a/main/_sources/plugins/keycloak_realm.rst.txt +++ b/main/_sources/plugins/keycloak_realm.rst.txt @@ -16,8 +16,8 @@ .. Title -keycloak_realm -- Allows administration of Keycloak realm via Keycloak API -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +keycloak_realm -- Allows administration of Keycloak realm using Keycloak API +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. Collection note @@ -49,9 +49,9 @@ Synopsis .. Description -- This module allows the administration of Keycloak realm via the Keycloak REST API. It requires access to the REST API via OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate realm definition with the scope tailored to your needs and a user having the expected roles. -- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/8.0/rest\-api/index.html `__. Aliases are provided so camelCased versions can be used as well. -- The Keycloak API does not always sanity check inputs e.g. you can set SAML\-specific settings on an OpenID Connect client for instance and vice versa. Be careful. If you do not specify a setting, usually a sensible default is chosen. +- This module allows the administration of Keycloak realm using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate realm definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/latest/rest\-api/index.html `__. Aliases are provided so camelCased versions can be used as well. +- The Keycloak API does not always sanity check inputs, for example you can set SAML\-specific settings on an OpenID Connect client for instance and also the other way around. :strong:`Be careful`. If you do not specify a setting, usually a sensible default is chosen. .. Aliases @@ -242,6 +242,27 @@ Parameters
        +
        +
        +
        +

        admin_permissions_enabled

        + +

        aliases: adminPermissionsEnabled

        +

        + boolean +

        +
        +
        +

        The realm admin permissions enabled.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        + +
        @@ -256,7 +277,7 @@ Parameters

        The realm admin theme.

        - +

        attributes

        @@ -269,7 +290,7 @@ Parameters

        The realm attributes.

        - +

        auth_client_id

        @@ -283,7 +304,7 @@ Parameters

        Default: "admin-cli"

        - +

        auth_client_secret

        @@ -296,7 +317,7 @@ Parameters

        Client Secret to use in conjunction with auth_client_id (if required).

        - +
        @@ -312,7 +333,7 @@ Parameters

        URL to the Keycloak instance.

        - +
        @@ -327,7 +348,7 @@ Parameters

        Password to authenticate for API access with.

        - +

        auth_realm

        @@ -340,7 +361,7 @@ Parameters

        Keycloak realm name to authenticate to for API access.

        - +
        @@ -355,7 +376,7 @@ Parameters

        Username to authenticate for API access with.

        - +
        @@ -370,7 +391,7 @@ Parameters

        The realm browser flow.

        - +
        @@ -385,7 +406,7 @@ Parameters

        The realm browser security headers.

        - +
        @@ -406,6 +427,27 @@ Parameters
        + +
        +
        +
        +

        brute_force_strategy

        + +

        aliases: bruteForceStrategy

        +

        + string +

        +
        +
        +

        The realm brute force strategy.

        +

        Choices:

        +
          +

        • "LINEAR"

          • +

        • "MULTIPLE"

          • +
        + +
        +
        @@ -421,6 +463,36 @@ Parameters

        The realm client authentication flow.

        + +
        +
        +
        +

        client_offline_session_idle_timeout

        + +

        aliases: clientOfflineSessionIdleTimeout

        +

        + integer +

        +
        +
        +

        All Clients inherit from this setting, time an offline session is allowed to be idle before it expires.

        +
        + + +
        +
        +
        +

        client_offline_session_max_lifespan

        + +

        aliases: clientOfflineSessionMaxLifespan

        +

        + integer +

        +
        +
        +

        All Clients inherit from this setting, max time before an offline session is expired regardless of activity.

        +
        +
        @@ -436,6 +508,36 @@ Parameters

        The realm client scope mappings.

        + +
        +
        +
        +

        client_session_idle_timeout

        + +

        aliases: clientSessionIdleTimeout

        +

        + integer +

        +
        +
        +

        All Clients inherit from this setting, time a session is allowed to be idle before it expires.

        +
        + + +
        +
        +
        +

        client_session_max_lifespan

        + +

        aliases: clientSessionMaxLifespan

        +

        + integer +

        +
        +
        +

        All Clients inherit from this setting, max time before a session is expired.

        +
        +
        @@ -444,7 +546,6 @@ Parameters

        integer

        -

        added in middleware_automation.keycloak 4.5.0

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        @@ -707,7 +808,6 @@ Parameters

        boolean

        -

        added in middleware_automation.keycloak 3.6.0

        Enables or disables login events for this realm.

        @@ -766,6 +866,21 @@ Parameters
        +
        +
        +
        +

        first_broker_login_flow

        + +

        aliases: firstBrokerLoginFlow

        +

        + string +

        +
        +
        +

        The realm first broker login flow.

        +
        + +

        http_agent

        @@ -773,14 +888,13 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 5.4.0

        Configures the HTTP User-Agent header.

        Default: "Ansible"

        - +

        id

        @@ -793,7 +907,7 @@ Parameters

        The realm to create.

        - +
        @@ -814,6 +928,21 @@ Parameters
        + +
        +
        +
        +

        localization_texts

        + +

        aliases: localizationTexts

        +

        + dictionary +

        +
        +
        +

        The custom localization texts for a realm.

        +
        +
        @@ -881,6 +1010,21 @@ Parameters
        +
        +
        +
        +

        max_temporary_lockouts

        + +

        aliases: maxTemporaryLockouts

        +

        + integer +

        +
        +
        +

        The realm max temporary lockouts.

        +
        + +
        @@ -895,7 +1039,7 @@ Parameters

        The realm minimum quick login wait in seconds.

        - +
        @@ -910,7 +1054,37 @@ Parameters

        The realm not before.

        + +
        +
        +
        +

        oauth2_device_code_lifespan

        + +

        aliases: oauth2DeviceCodeLifespan

        +

        + integer +

        +
        +
        +

        Max time before the device code and user code are expired.

        +
        + +
        +
        +
        +

        oauth2_device_polling_interval

        + +

        aliases: oauth2DevicePollingInterval

        +

        + integer +

        +
        +
        +

        The minimum amount of time in seconds that the client should wait between polling requests to the token endpoint.

        +
        + +
        @@ -925,7 +1099,7 @@ Parameters

        The realm offline session idle timeout.

        - +
        @@ -940,7 +1114,7 @@ Parameters

        The realm offline session max lifespan.

        - +
        @@ -961,6 +1135,27 @@ Parameters
        + +
        +
        +
        +

        organizations_enabled

        + +

        aliases: organizationsEnabled

        +

        + boolean +

        +
        +
        +

        Enables support for experimental organization feature.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        @@ -1132,6 +1327,19 @@ Parameters
        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +
        +

        Authentication refresh token for Keycloak API.

        +
        + +
        @@ -1146,7 +1354,7 @@ Parameters

        The realm refresh token max reuse.

        - +
        @@ -1167,7 +1375,7 @@ Parameters
        - +
        @@ -1188,7 +1396,7 @@ Parameters
        - +
        @@ -1203,7 +1411,7 @@ Parameters

        The realm registration flow.

        - +
        @@ -1224,7 +1432,7 @@ Parameters
        - +
        @@ -1239,7 +1447,7 @@ Parameters

        The realm reset credentials flow.

        - +
        @@ -1260,7 +1468,7 @@ Parameters
        - +
        @@ -1281,7 +1489,7 @@ Parameters
        - +
        @@ -1296,7 +1504,7 @@ Parameters

        The realm smtp server.

        - +
        @@ -1318,7 +1526,7 @@ Parameters
        - +
        @@ -1333,7 +1541,7 @@ Parameters

        The realm sso session idle timeout.

        - +
        @@ -1348,7 +1556,7 @@ Parameters

        The realm sso session idle timeout remember me.

        - +
        @@ -1363,7 +1571,7 @@ Parameters

        The realm sso session max lifespan.

        - +
        @@ -1378,7 +1586,7 @@ Parameters

        The realm sso session max lifespan remember me.

        - +

        state

        @@ -1389,8 +1597,8 @@ Parameters

        State of the realm.

        -

        On present, the realm will be created (or updated if it exists already).

        -

        On absent, the realm will be removed if it exists.

        +

        On present, the realm is created (or updated if it exists already).

        +

        On absent, the realm is removed if it exists.

        Choices:

        • "present" ← (default)

          • @@ -1399,7 +1607,7 @@ Parameters
        - +
        @@ -1415,7 +1623,7 @@ Parameters

        The realm supported locales.

        - +

        token

        @@ -1423,13 +1631,12 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 3.0.0

        Authentication token for Keycloak API.

        - +
        @@ -1450,7 +1657,7 @@ Parameters
        - +

        validate_certs

        @@ -1469,7 +1676,7 @@ Parameters
        - +
        @@ -1490,7 +1697,7 @@ Parameters
        - +
        @@ -1505,6 +1712,375 @@ Parameters

        The realm wait increment in seconds.

        + +
        +
        +
        +

        web_authn_policy_acceptable_aaguids

        + +

        aliases: webAuthnPolicyAcceptableAaguids

        +

        + list + / elements=string +

        +
        +
        +

        List of acceptable AAGUIDs for WebAuthn authenticators.

        +
        + + +
        +
        +
        +

        web_authn_policy_attestation_conveyance_preference

        + +

        aliases: webAuthnPolicyAttestationConveyancePreference

        +

        + string +

        +
        +
        +

        Attestation conveyance preference for WebAuthn.

        +
        + + +
        +
        +
        +

        web_authn_policy_authenticator_attachment

        + +

        aliases: webAuthnPolicyAuthenticatorAttachment

        +

        + string +

        +
        +
        +

        Authenticator attachment preference for WebAuthn authenticators.

        +
        + + +
        +
        +
        +

        web_authn_policy_avoid_same_authenticator_register

        + +

        aliases: webAuthnPolicyAvoidSameAuthenticatorRegister

        +

        + boolean +

        +
        +
        +

        Avoid registering the same authenticator multiple times.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        + + +
        +
        +
        +

        web_authn_policy_create_timeout

        + +

        aliases: webAuthnPolicyCreateTimeout

        +

        + integer +

        +
        +
        +

        Timeout for WebAuthn credential creation (ms).

        +
        + + +
        +
        +
        +

        web_authn_policy_extra_origins

        + +

        aliases: webAuthnPolicyExtraOrigins

        +

        + list + / elements=string +

        +
        +
        +

        Additional acceptable origins for WebAuthn requests.

        +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_acceptable_aaguids

        + +

        aliases: webAuthnPolicyPasswordlessAcceptableAaguids

        +

        + list + / elements=string +

        +
        +
        +

        List of acceptable AAGUIDs for WebAuthn passwordless authenticators.

        +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_attestation_conveyance_preference

        + +

        aliases: webAuthnPolicyPasswordlessAttestationConveyancePreference

        +

        + string +

        +
        +
        +

        Attestation conveyance preference for WebAuthn passwordless.

        +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_authenticator_attachment

        + +

        aliases: webAuthnPolicyPasswordlessAuthenticatorAttachment

        +

        + string +

        +
        +
        +

        Authenticator attachment for WebAuthn passwordless.

        +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_avoid_same_authenticator_register

        + +

        aliases: webAuthnPolicyPasswordlessAvoidSameAuthenticatorRegister

        +

        + boolean +

        +
        +
        +

        Avoid registering the same authenticator multiple times for passwordless.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_create_timeout

        + +

        aliases: webAuthnPolicyPasswordlessCreateTimeout

        +

        + integer +

        +
        +
        +

        Timeout for WebAuthn passwordless credential creation (ms).

        +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_extra_origins

        + +

        aliases: webAuthnPolicyPasswordlessExtraOrigins

        +

        + list + / elements=string +

        +
        +
        +

        Additional acceptable origins for WebAuthn passwordless requests.

        +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_passkeys_enabled

        + +

        aliases: webAuthnPolicyPasswordlessPasskeysEnabled

        +

        + boolean +

        +
        +
        +

        Enable passkeys (conditional UI) authentication in the username forms.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_require_resident_key

        + +

        aliases: webAuthnPolicyPasswordlessRequireResidentKey

        +

        + string +

        +
        +
        +

        Whether resident keys are required for WebAuthn passwordless (Yes/No/not specified).

        +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_rp_entity_name

        + +

        aliases: webAuthnPolicyPasswordlessRpEntityName

        +

        + string +

        +
        +
        +

        WebAuthn Passwordless Relying Party Entity Name.

        +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_rp_id

        + +

        aliases: webAuthnPolicyPasswordlessRpId

        +

        + string +

        +
        +
        +

        WebAuthn Passwordless Relying Party ID (domain).

        +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_signature_algorithms

        + +

        aliases: webAuthnPolicyPasswordlessSignatureAlgorithms

        +

        + list + / elements=string +

        +
        +
        +

        List of acceptable WebAuthn signature algorithms for passwordless.

        +
        + + +
        +
        +
        +

        web_authn_policy_passwordless_user_verification_requirement

        + +

        aliases: webAuthnPolicyPasswordlessUserVerificationRequirement

        +

        + string +

        +
        +
        +

        User verification requirement for WebAuthn passwordless.

        +
        + + +
        +
        +
        +

        web_authn_policy_require_resident_key

        + +

        aliases: webAuthnPolicyRequireResidentKey

        +

        + string +

        +
        +
        +

        Whether resident keys are required for WebAuthn (Yes/No/not specified).

        +
        + + +
        +
        +
        +

        web_authn_policy_rp_entity_name

        + +

        aliases: webAuthnPolicyRpEntityName

        +

        + string +

        +
        +
        +

        WebAuthn Relying Party Entity Name.

        +
        + + +
        +
        +
        +

        web_authn_policy_rp_id

        + +

        aliases: webAuthnPolicyRpId

        +

        + string +

        +
        +
        +

        WebAuthn Relying Party ID (domain). Empty string means use request host.

        +
        + + +
        +
        +
        +

        web_authn_policy_signature_algorithms

        + +

        aliases: webAuthnPolicySignatureAlgorithms

        +

        + list + / elements=string +

        +
        +
        +

        List of acceptable WebAuthn signature algorithms.

        +
        + + +
        +
        +
        +

        web_authn_policy_user_verification_requirement

        + +

        aliases: webAuthnPolicyUserVerificationRequirement

        +

        + string +

        +
        +
        +

        User verification requirement for WebAuthn.

        +
        + @@ -1528,6 +2104,50 @@ Attributes - Support - Description + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + * - .. raw:: html
        @@ -1629,22 +2249,21 @@ Examples - name: Create or update Keycloak realm (minimal example) middleware_automation.keycloak.keycloak_realm: auth_client_id: admin-cli - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com auth_realm: master auth_username: USERNAME auth_password: PASSWORD - id: realm - realm: realm + realm: unique_realm_name state: present - name: Delete a Keycloak realm middleware_automation.keycloak.keycloak_realm: auth_client_id: admin-cli - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com auth_realm: master auth_username: USERNAME auth_password: PASSWORD - id: test + realm: unique_realm_name state: absent @@ -1725,7 +2344,7 @@ Common return values are documented :ref:`here `, the foll

        Representation of proposed realm.

        Returned: always

        -

        Sample: {"id": "test"}

        +

        Sample: {"realm": "test"}

        diff --git a/main/_sources/plugins/keycloak_realm_info.rst.txt b/main/_sources/plugins/keycloak_realm_info.rst.txt new file mode 100644 index 0000000..71d9a79 --- /dev/null +++ b/main/_sources/plugins/keycloak_realm_info.rst.txt @@ -0,0 +1,406 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_realm_info_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_realm_info -- Allows obtaining Keycloak realm public information using Keycloak API +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_realm_info`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to get Keycloak realm public information using the Keycloak REST API. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/latest/rest\-api/index.html `__. +- Attributes are multi\-valued in the Keycloak API. All attributes are lists of individual values and are returned that way by this module. You may pass single values for attributes when calling the module, and this is translated into a list suitable for the API. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        They Keycloak realm ID.

        +

        Default: "master"

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_info_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + This action does not modify state. + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_info_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ ` \ :ansible-attribute-support-na:`N/A` + + This action does not modify state. + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Get a Keycloak public key + middleware_automation.keycloak.keycloak_realm_info: + realm: MyCustomRealm + auth_keycloak_url: https://auth.example.com + delegate_to: localhost + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +
        +
        +

        realm_info

        + +

        + dictionary +

        +
        +

        Representation of the realm public information.

        +

        Returned: always

        +
        +
        +

        account-service

        + +

        + string +

        +
        +

        Account console URL.

        +

        Returned: always

        +

        Sample: "https://auth.example.com/realms/MyRealm/account"

        +
        +
        +

        public_key

        + +

        + string +

        +
        +

        Public key of the realm.

        +

        Returned: always

        +

        Sample: "MIIBIjANBgkqhkiG9w0BAQEFAAO..."

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        Realm ID.

        +

        Returned: always

        +

        Sample: "MyRealm"

        +
        +
        +

        token-service

        + +

        + string +

        +
        +

        Token endpoint URL.

        +

        Returned: always

        +

        Sample: "https://auth.example.com/realms/MyRealm/protocol/openid-connect"

        +
        +
        +

        tokens-not-before

        + +

        + integer +

        +
        +

        The token not before.

        +

        Returned: always

        +

        Sample: 0

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Fynn Chen (@fynncfchen) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_realm_key.rst.txt b/main/_sources/plugins/keycloak_realm_key.rst.txt new file mode 100644 index 0000000..e853bce --- /dev/null +++ b/main/_sources/plugins/keycloak_realm_key.rst.txt @@ -0,0 +1,1238 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_realm_key_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_realm_key -- Allows administration of Keycloak realm keys using Keycloak API ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_realm_key`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows the administration of Keycloak realm keys using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the realm being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate realm definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/latest/rest\-api/index.html `__. Aliases are provided so camelCased versions can be used as well. +- This module is unable to detect changes to the actual cryptographic key after importing it. However, if some other property is changed alongside the cryptographic key, then the key also changes as a side\-effect, as the JSON payload needs to include the private key. This can be considered either a bug or a feature, as the alternative would be to always update the realm key whether it has changed or not. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        config

        + +

        + dictionary +

        +
        +

        Dict specifying the key and its properties.

        +
        +
        +

        active

        + +

        + boolean +

        +
        +

        Whether they key is active or inactive. Not to be confused with the state of the Ansible resource managed by the state parameter.

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        +
        +

        algorithm

        + +

        + string +

        +
        +

        Key algorithm.

        +

        The values RS384, RS512, PS256, PS384, PS512, RSA1_5, RSA-OAEP, RSA-OAEP-256 have been added in middleware_automation.keycloak 8.2.0.

        +

        The values HS256, HS384, HS512 (for HMAC), ES256, ES384, ES512 (for ECDSA), and AES have been added in middleware_automation.keycloak 12.4.0.

        +

        The values ECDH_ES, ECDH_ES_A128KW, ECDH_ES_A192KW, ECDH_ES_A256KW (for ECDH key exchange), and Ed25519, Ed448 (for EdDSA signing) have been added in middleware_automation.keycloak 12.4.0.

        +

        For provider_id=rsa, provider_id=rsa-generated, and provider_id=java-keystore, defaults to RS256.

        +

        For provider_id=rsa-enc and provider_id=rsa-enc-generated, must be one of RSA1_5, RSA-OAEP, RSA-OAEP-256 (required, no default).

        +

        For provider_id=hmac-generated, must be one of HS256, HS384, HS512 (required, no default).

        +

        For provider_id=ecdsa-generated, must be one of ES256, ES384, ES512 (required, no default).

        +

        For provider_id=ecdh-generated, must be one of ECDH_ES, ECDH_ES_A128KW, ECDH_ES_A192KW, ECDH_ES_A256KW (required, no default).

        +

        For provider_id=eddsa-generated, this option is not used (the algorithm is determined by config.elliptic_curve).

        +

        For provider_id=aes-generated, this option is not used (AES is always used).

        +

        Choices:

        +
          +

        • "RS256" ← (default)

          • +

        • "RS384"

          • +

        • "RS512"

          • +

        • "PS256"

          • +

        • "PS384"

          • +

        • "PS512"

          • +

        • "RSA1_5"

          • +

        • "RSA-OAEP"

          • +

        • "RSA-OAEP-256"

          • +

        • "HS256"

          • +

        • "HS384"

          • +

        • "HS512"

          • +

        • "ES256"

          • +

        • "ES384"

          • +

        • "ES512"

          • +

        • "AES"

          • +

        • "ECDH_ES"

          • +

        • "ECDH_ES_A128KW"

          • +

        • "ECDH_ES_A192KW"

          • +

        • "ECDH_ES_A256KW"

          • +

        • "Ed25519"

          • +

        • "Ed448"

          • +
        + +
        +
        +

        certificate

        + +

        + string +

        +
        +

        A certificate signed with the private key as an ASCII string. Contents of the key must match config.algorithm and provider_id.

        +

        If you want Keycloak to automatically generate a certificate using your private key then set this to an empty string.

        +

        Required when provider_id is rsa or rsa-enc. Not used for auto-generated providers.

        +
        +
        +

        elliptic_curve

        + +

        + string +

        +
        +

        The elliptic curve to use for ECDSA, ECDH, or EdDSA keys.

        +

        For provider_id=ecdsa-generated and provider_id=ecdh-generated, valid values are P-256, P-384, P-521. Default is P-256.

        +

        For provider_id=eddsa-generated, valid values are Ed25519, Ed448. Default is Ed25519.

        +

        Choices:

        +
          +

        • "P-256"

          • +

        • "P-384"

          • +

        • "P-521"

          • +

        • "Ed25519"

          • +

        • "Ed448"

          • +
        + +
        +
        +

        enabled

        + +

        + boolean +

        +
        +

        Whether the key is enabled or disabled. Not to be confused with the state of the Ansible resource managed by the state parameter.

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        +
        +

        key_alias

        + +

        + string +

        +
        +

        Alias of the key within the keystore.

        +

        Required when provider_id=java-keystore.

        +
        +
        +

        key_password

        + +

        + string +

        +
        +

        Password for the key within the keystore.

        +

        If not specified, the config.keystore_password is used.

        +

        Only applicable to provider_id=java-keystore.

        +
        +
        +

        key_size

        + +

        + integer +

        +
        +

        The size of the generated key in bits.

        +

        Only applicable to provider_id=rsa-generated and provider_id=rsa-enc-generated.

        +

        Valid values are 1024, 2048, 4096. Default is 2048.

        +
        +
        +

        keystore

        + +

        + string +

        +
        +

        Path to the Java Keystore file on the Keycloak server filesystem.

        +

        Required when provider_id=java-keystore.

        +
        +
        +

        keystore_password

        + +

        + string +

        +
        +

        Password for the Java Keystore.

        +

        Required when provider_id=java-keystore.

        +
        +
        +

        priority

        + +

        + integer + / required +

        +
        +

        The priority of the key.

        +
        +
        +

        private_key

        + +

        + string +

        +
        +

        The private key as an ASCII string. Contents of the key must match config.algorithm and provider_id.

        +

        Please note that the module cannot detect whether the private key specified differs from the current state's private key. Use force=true to force the module to update the private key if you expect it to be updated.

        +

        Required when provider_id is rsa or rsa-enc. Not used for auto-generated providers.

        +
        +
        +

        secret_size

        + +

        + integer +

        +
        +

        The size of the generated secret key in bytes.

        +

        Only applicable to provider_id=hmac-generated and provider_id=aes-generated.

        +

        Valid values are 16, 24, 32, 64, 128, 256, 512.

        +

        Default is 64 for HMAC, 16 for AES.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        force

        + +

        + boolean +

        +
        +

        Enforce the state of the private key and certificate. This is not automatically the case as this module is unable to determine the current state of the private key and thus cannot trigger an update based on an actual divergence. That said, a private key update may happen even if force is false as a side-effect of other changes.

        +

        Choices:

        +
          +

        • false ← (default)

          • +

        • true

          • +
        + +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        name

        + +

        + string + / required +

        +
        +

        Name of the realm key to create.

        +
        +
        +

        parent_id

        + +

        + string + / required +

        +
        +

        The parent_id of the realm key. In practice the name of the realm.

        +
        +
        +

        provider_id

        + +

        + string +

        +
        +

        The name of the "provider ID" for the key.

        +

        The value rsa-enc has been added in middleware_automation.keycloak 8.2.0.

        +

        The value java-keystore has been added in middleware_automation.keycloak 12.4.0. This provider imports keys from a Java Keystore (JKS or PKCS12) file located on the Keycloak server filesystem.

        +

        The values rsa-generated, hmac-generated, aes-generated, and ecdsa-generated have been added in middleware_automation.keycloak 3.0.0. These are auto-generated key providers where Keycloak manages the key material.

        +

        The values rsa-enc-generated, ecdh-generated, and eddsa-generated have been added in middleware_automation.keycloak 3.0.0. These correspond to the auto-generated key providers available in Keycloak 26.

        +

        Choices:

        +
          +

        • "rsa" ← (default)

          • +

        • "rsa-enc"

          • +

        • "java-keystore"

          • +

        • "rsa-generated"

          • +

        • "rsa-enc-generated"

          • +

        • "hmac-generated"

          • +

        • "aes-generated"

          • +

        • "ecdsa-generated"

          • +

        • "ecdh-generated"

          • +

        • "eddsa-generated"

          • +
        + +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the keycloak realm key.

        +

        On present, the realm key is created (or updated if it exists already).

        +

        On absent, the realm key is removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        update_password

        + +

        + string +

        +
        +

        Controls when passwords are sent to Keycloak for java-keystore provider.

        +

        always - Always send passwords. Keycloak will update the component even if passwords have not changed. Use when you need to ensure passwords are updated.

        +

        on_create - Only send passwords when creating a new component. When updating an existing component, send the masked value to preserve existing passwords. This makes the module idempotent for password fields.

        +

        This is necessary because Keycloak masks passwords in API responses (returns **********), making comparison impossible.

        +

        Has no effect for providers other than java-keystore.

        +

        Choices:

        +
          +

        • "always" ← (default)

          • +

        • "on_create"

          • +
        + +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_key_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_key_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_key_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-partial:`partial` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + +Notes +----- + +.. note:: + - Current value of the private key cannot be fetched from Keycloak. Therefore comparing its desired state to the current state is not possible. + - If :ansopt:`middleware\_automation.keycloak.keycloak\_realm\_key#module:config.certificate` is not explicitly provided it is dynamically created by Keycloak. Therefore comparing the current state of the certificate to the desired state (which may be empty) is not possible. + - Due to the private key and certificate options the module is :strong:`not fully idempotent`. You can use :ansopt:`middleware\_automation.keycloak.keycloak\_realm\_key#module:force=true` to force the module to ensure updating if you know that the private key might have changed. + - For auto\-generated providers (\ :ansval:`rsa\-generated`\ , :ansval:`rsa\-enc\-generated`\ , :ansval:`hmac\-generated`\ , :ansval:`aes\-generated`\ , :ansval:`ecdsa\-generated`\ , :ansval:`ecdh\-generated`\ , :ansval:`eddsa\-generated`\ ), Keycloak manages the key material automatically. The :ansopt:`middleware\_automation.keycloak.keycloak\_realm\_key#module:config.private\_key` and :ansopt:`middleware\_automation.keycloak.keycloak\_realm\_key#module:config.certificate` options are not used. + - For :ansval:`java\-keystore` provider, the :ansopt:`middleware\_automation.keycloak.keycloak\_realm\_key#module:config.keystore\_password` and :ansopt:`middleware\_automation.keycloak.keycloak\_realm\_key#module:config.key\_password` values are returned masked by Keycloak. Therefore comparing their current state to the desired state is not possible. Use :ansopt:`middleware\_automation.keycloak.keycloak\_realm\_key#module:update\_password=on\_create` for idempotent playbooks, or use :ansopt:`middleware\_automation.keycloak.keycloak\_realm\_key#module:update\_password=always` (default) if you need to ensure passwords are updated. + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Manage Keycloak realm key (certificate autogenerated by Keycloak) + middleware_automation.keycloak.keycloak_realm_key: + name: custom + state: present + parent_id: master + provider_id: rsa + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + config: + private_key: "{{ private_key }}" + certificate: "" + enabled: true + active: true + priority: 120 + algorithm: RS256 + + - name: Manage Keycloak realm key and certificate + middleware_automation.keycloak.keycloak_realm_key: + name: custom + state: present + parent_id: master + provider_id: rsa + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + config: + private_key: "{{ private_key }}" + certificate: "{{ certificate }}" + enabled: true + active: true + priority: 120 + algorithm: RS256 + + - name: Create HMAC signing key (auto-generated) + middleware_automation.keycloak.keycloak_realm_key: + name: hmac-custom + state: present + parent_id: master + provider_id: hmac-generated + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + config: + enabled: true + active: true + priority: 100 + algorithm: HS256 + secret_size: 64 + + - name: Create AES encryption key (auto-generated) + middleware_automation.keycloak.keycloak_realm_key: + name: aes-custom + state: present + parent_id: master + provider_id: aes-generated + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + config: + enabled: true + active: true + priority: 100 + secret_size: 16 + + - name: Create ECDSA signing key (auto-generated) + middleware_automation.keycloak.keycloak_realm_key: + name: ecdsa-custom + state: present + parent_id: master + provider_id: ecdsa-generated + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + config: + enabled: true + active: true + priority: 100 + algorithm: ES256 + elliptic_curve: P-256 + + - name: Create RSA signing key (auto-generated) + middleware_automation.keycloak.keycloak_realm_key: + name: rsa-auto + state: present + parent_id: master + provider_id: rsa-generated + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + config: + enabled: true + active: true + priority: 100 + algorithm: RS256 + key_size: 2048 + + - name: Remove default HMAC key + middleware_automation.keycloak.keycloak_realm_key: + name: hmac-generated + state: absent + parent_id: myrealm + provider_id: hmac-generated + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + config: + priority: 100 + + - name: Create RSA encryption key (auto-generated) + middleware_automation.keycloak.keycloak_realm_key: + name: rsa-enc-auto + state: present + parent_id: master + provider_id: rsa-enc-generated + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + config: + enabled: true + active: true + priority: 100 + algorithm: RSA-OAEP + key_size: 2048 + + - name: Create ECDH key exchange key (auto-generated) + middleware_automation.keycloak.keycloak_realm_key: + name: ecdh-custom + state: present + parent_id: master + provider_id: ecdh-generated + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + config: + enabled: true + active: true + priority: 100 + algorithm: ECDH_ES + elliptic_curve: P-256 + + - name: Create EdDSA signing key (auto-generated) + middleware_automation.keycloak.keycloak_realm_key: + name: eddsa-custom + state: present + parent_id: master + provider_id: eddsa-generated + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + config: + enabled: true + active: true + priority: 100 + elliptic_curve: Ed25519 + + - name: Import key from Java Keystore (always update passwords) + middleware_automation.keycloak.keycloak_realm_key: + name: jks-imported + state: present + parent_id: master + provider_id: java-keystore + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + # update_password: always is the default - passwords are always sent to Keycloak + config: + enabled: true + active: true + priority: 100 + algorithm: RS256 + keystore: /opt/keycloak/conf/keystore.jks + keystore_password: "{{ keystore_password }}" + key_alias: mykey + key_password: "{{ key_password }}" + + - name: Import key from Java Keystore (idempotent - only set password on create) + middleware_automation.keycloak.keycloak_realm_key: + name: jks-idempotent + state: present + parent_id: master + provider_id: java-keystore + auth_keycloak_url: http://localhost:8080 + auth_username: keycloak + auth_password: keycloak + auth_realm: master + update_password: on_create # Only send passwords when creating, preserve existing on update + config: + enabled: true + active: true + priority: 100 + algorithm: RS256 + keystore: /opt/keycloak/conf/keystore.jks + keystore_password: "{{ keystore_password }}" + key_alias: mykey + key_password: "{{ key_password }}" + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of the keycloak_realm_key after module execution.

        +

        Returned: on success

        +
        +
        +

        config

        + +

        + dictionary +

        +
        +

        Realm key configuration.

        +

        Returned: when state=present

        +

        Sample: {"active": ["true"], "algorithm": ["RS256"], "enabled": ["true"], "priority": ["140"]}

        +
        +
        +

        id

        + +

        + string +

        +
        +

        ID of the realm key.

        +

        Returned: when state=present

        +

        Sample: "5b7ec13f-99da-46ad-8326-ab4c73cf4ce4"

        +
        +
        +

        key_info

        + +

        + dictionary +

        +
        +

        Cryptographic key metadata fetched from the realm keys endpoint.

        +

        Only returned for java-keystore provider when state=present and not in check mode.

        +

        This includes the key ID (kid) and certificate fingerprint, which can be used to detect if the actual cryptographic key changed.

        +

        Returned: when provider_id=java-keystore and state=present

        +
        +
        +

        certificate_fingerprint

        + +

        + string +

        +
        +

        SHA256 fingerprint of the certificate in colon-separated hex format.

        +

        Returned: success

        +

        Sample: "A1:B2:C3:D4:E5:F6:..."

        +
        +
        +

        kid

        + +

        + string +

        +
        +

        The key ID (kid) - unique identifier for the cryptographic key.

        +

        Returned: success

        +

        Sample: "bN7p5Nc_V2M7N_-mb5vVSRVPKq5qD_OuARInB9ofsJ0"

        +
        +
        +

        status

        + +

        + string +

        +
        +

        The key status (ACTIVE, PASSIVE, DISABLED).

        +

        Returned: success

        +

        Sample: "ACTIVE"

        +
        +
        +

        valid_to

        + +

        + integer +

        +
        +

        Certificate expiration timestamp in milliseconds since epoch.

        +

        Returned: success

        +

        Sample: 1801789047000

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the realm key.

        +

        Returned: when state=present

        +

        Sample: "mykey"

        +
        +
        +

        parentId

        + +

        + string +

        +
        +

        ID of the realm this key belongs to.

        +

        Returned: when state=present

        +

        Sample: "myrealm"

        +
        +
        +

        providerId

        + +

        + string +

        +
        +

        The ID of the key provider.

        +

        Returned: when state=present

        +

        Sample: "rsa"

        +
        +
        +

        providerType

        + +

        + string +

        +
        +

        The type of provider.

        +

        Returned: when state=present

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Samuli Seppänen (@mattock) +- Ivan Kokalović (@koke1997) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_realm_keys_metadata_info.rst.txt b/main/_sources/plugins/keycloak_realm_keys_metadata_info.rst.txt new file mode 100644 index 0000000..e9fc6eb --- /dev/null +++ b/main/_sources/plugins/keycloak_realm_keys_metadata_info.rst.txt @@ -0,0 +1,542 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_realm_keys_metadata_info_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_realm_keys_metadata_info -- Allows obtaining Keycloak realm keys metadata using Keycloak API ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_realm_keys_metadata_info`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to get Keycloak realm keys metadata using the Keycloak REST API. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/latest/rest\-api/index.html `__. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        They Keycloak realm to fetch keys metadata.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_keys_metadata_info_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_keys_metadata_info_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + This action does not modify state. + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_keys_metadata_info_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ ` \ :ansible-attribute-support-na:`N/A` + + This action does not modify state. + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Fetch Keys metadata + middleware_automation.keycloak.keycloak_realm_keys_metadata_info: + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + realm: MyCustomRealm + delegate_to: localhost + register: keycloak_keys_metadata + + - name: Write the Keycloak keys certificate into a file + ansible.builtin.copy: + dest: /tmp/keycloak.cert + content: | + {{ keys_metadata['keycloak_keys_metadata']['keys'] + | selectattr('algorithm', 'equalto', 'RS256') + | map(attribute='certificate') + | first + }} + delegate_to: localhost + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        keys_metadata

        + +

        + dictionary +

        +
        +

        Representation of the realm keys metadata (see https://www.keycloak.org/docs-api/latest/rest-api/index.html#KeysMetadataRepresentation).

        +

        Returned: always

        +
        +
        +

        active

        + +

        + dictionary +

        +
        +

        A mapping (that is, a dict) from key algorithms to UUIDs.

        +

        Returned: always

        +
        +
        +

        keys

        + +

        + list + / elements=dictionary +

        +
        +

        A list of dicts providing detailed information on the keys.

        +

        Returned: always

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Thomas Bach (@thomasbach-dev) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_realm_localization.rst.txt b/main/_sources/plugins/keycloak_realm_localization.rst.txt new file mode 100644 index 0000000..3ca8c4d --- /dev/null +++ b/main/_sources/plugins/keycloak_realm_localization.rst.txt @@ -0,0 +1,692 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_realm_localization_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_realm_localization -- Allows management of Keycloak realm localization overrides via the Keycloak API +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_realm_localization`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to manage per\-locale message overrides for a Keycloak realm using the Keycloak Admin REST API. +- Requires access via OpenID Connect; the connecting user/client must have sufficient privileges. +- The names of module options are snake\_cased versions of the names found in the Keycloak API. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        force

        + +

        + boolean +

        +
        +

        If false, only the keys listed in the overrides are modified by this module. Any other pre-existing keys are ignored.

        +

        If true, all locale overrides are made to match configuration of this module. For example any keys missing from the overrides are removed regardless of state value.

        +

        Choices:

        +
          +

        • false ← (default)

          • +

        • true

          • +
        + +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        locale

        + +

        + string + / required +

        +
        +

        Locale code for which the overrides apply (for example, en, fi, de).

        +
        +
        +

        overrides

        + +

        + list + / elements=dictionary +

        +
        +

        List of overrides to ensure for the locale when state=present. Each item is a mapping with the record's overrides[].key and its overrides[].value.

        +

        Ignored when state=absent.

        +

        Default: []

        +
        +
        +

        key

        + +

        + string + / required +

        +
        +

        The message key to override.

        +
        +
        +

        value

        + +

        + string +

        +
        +

        The override value for the message key. If omitted, value defaults to an empty string.

        +

        Default: ""

        +
        +
        +

        parent_id

        + +

        + string + / required +

        +
        +

        Name of the realm that owns the locale overrides.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        Desired state of localization overrides for the given locale.

        +

        On present, the set of overrides for the locale are made to match overrides. If force is true keys not listed in overrides are removed, and the listed keys are created or updated. If force is false keys not listed in overrides are ignored, and the listed keys are created or updated.

        +

        On absent, overrides for the locale is removed. If force is true, all keys are removed. If force is false, only the keys listed in overrides are removed.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_localization_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_localization_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_localization_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + +See Also +-------- + +.. seealso:: + + :ref:`middleware\_automation.keycloak.keycloak\_realm ` + You can specify list of supported locales using :ansopt:`middleware\_automation.keycloak.keycloak\_realm#module:supported\_locales`. + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Replace all overrides for locale "en" (credentials auth) + middleware_automation.keycloak.keycloak_realm_localization: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + parent_id: my-realm + locale: en + state: present + force: true + overrides: + - key: greeting + value: "Hello" + - key: farewell + value: "Bye" + delegate_to: localhost + + - name: Replace listed overrides for locale "en" (credentials auth) + middleware_automation.keycloak.keycloak_realm_localization: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + parent_id: my-realm + locale: en + state: present + force: false + overrides: + - key: greeting + value: "Hello" + - key: farewell + value: "Bye" + delegate_to: localhost + + - name: Ensure only one override exists for locale "fi" (token auth) + middleware_automation.keycloak.keycloak_realm_localization: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + parent_id: my-realm + locale: fi + state: present + force: true + overrides: + - key: app.title + value: "Sovellukseni" + delegate_to: localhost + + - name: Remove all overrides for locale "de" + middleware_automation.keycloak.keycloak_realm_localization: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + parent_id: my-realm + locale: de + state: absent + force: true + delegate_to: localhost + + - name: Remove only the listed overrides for locale "de" + middleware_automation.keycloak.keycloak_realm_localization: + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + parent_id: my-realm + locale: de + state: absent + force: false + overrides: + - key: app.title + - key: foo + - key: bar + delegate_to: localhost + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Final state of localization overrides for the locale after module execution.

        +

        Contains the locale and the list of overrides as key/value items.

        +

        Returned: on success

        +
        +
        +

        locale

        + +

        + string +

        +
        +

        The locale code affected.

        +

        Returned: success

        +

        Sample: "en"

        +
        +
        +

        overrides

        + +

        + list + / elements=dictionary +

        +
        +

        The list of overrides that exist after execution.

        +

        Returned: success

        +

        Sample: [{"key": "greeting", "value": "Hello"}, {"key": "farewell", "value": "Bye"}]

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Jakub Danek (@danekja) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_realm_rolemapping.rst.txt b/main/_sources/plugins/keycloak_realm_rolemapping.rst.txt new file mode 100644 index 0000000..7e9c228 --- /dev/null +++ b/main/_sources/plugins/keycloak_realm_rolemapping.rst.txt @@ -0,0 +1,731 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_realm_rolemapping_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_realm_rolemapping -- Allows administration of Keycloak realm role mappings into groups with the Keycloak API ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_realm_rolemapping`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to add, remove or modify Keycloak realm role mappings into groups with the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/18.0/rest\-api/index.html `__. +- Attributes are multi\-valued in the Keycloak API. All attributes are lists of individual values and are returned that way by this module. You may pass single values for attributes when calling the module, and this is translated into a list suitable for the API. +- When updating a group\_rolemapping, where possible provide the role ID to the module. This removes a lookup to the API to translate the name into the role ID. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        gid

        + +

        + string +

        +
        +

        ID of the group to be mapped.

        +

        This parameter is not required for updating or deleting the rolemapping but providing it reduces the number of API calls required.

        +
        +
        +

        group_name

        + +

        + string +

        +
        +

        Name of the group to be mapped.

        +

        This parameter is required (can be replaced by gid for less API call).

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        parents

        + +

        + list + / elements=dictionary +

        +
        +

        List of parent groups for the group to handle sorted top to bottom.

        +

        Set this if your group is a subgroup and you do not provide the GID in gid.

        +
        +
        +

        id

        + +

        + string +

        +
        +

        Identify parent by ID.

        +

        Needs less API calls than using parents[].name.

        +

        A deep parent chain can be started at any point when first given parent is given as ID.

        +

        Note that in principle both ID and name can be specified at the same time but current implementation only always use just one of them, with ID being preferred.

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Identify parent by name.

        +

        Needs more internal API calls than using parents[].id to map names to ID's under the hood.

        +

        When giving a parent chain with only names it must be complete up to the top.

        +

        Note that in principle both ID and name can be specified at the same time but current implementation only always use just one of them, with ID being preferred.

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        They Keycloak realm under which this role_representation resides.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        roles

        + +

        + list + / elements=dictionary +

        +
        +

        Roles to be mapped to the group.

        +
        +
        +

        id

        + +

        + string +

        +
        +

        The unique identifier for this role_representation.

        +

        This parameter is not required for updating or deleting a role_representation but providing it reduces the number of API calls required.

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the role_representation.

        +

        This parameter is required only when creating or updating the role_representation.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the realm_rolemapping.

        +

        On present, the realm_rolemapping is created if it does not yet exist, or updated with the parameters you provide.

        +

        On absent, the realm_rolemapping is removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_rolemapping_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_rolemapping_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_realm_rolemapping_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Map a client role to a group, authentication with credentials + middleware_automation.keycloak.keycloak_realm_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + state: present + group_name: group1 + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + - name: Map a client role to a group, authentication with token + middleware_automation.keycloak.keycloak_realm_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + state: present + group_name: group1 + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + - name: Map a client role to a subgroup, authentication with token + middleware_automation.keycloak.keycloak_realm_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + state: present + group_name: subgroup1 + parents: + - name: parent-group + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + - name: Unmap realm role from a group + middleware_automation.keycloak.keycloak_realm_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + state: absent + group_name: group1 + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of client role mapping after module execution.

        +

        The sample is truncated.

        +

        Returned: on success

        +

        Sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}

        +
        +
        +

        existing

        + +

        + dictionary +

        +
        +

        Representation of existing client role mapping.

        +

        The sample is truncated.

        +

        Returned: always

        +

        Sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +

        Sample: "Role role1 assigned to group group1."

        +
        +
        +

        proposed

        + +

        + dictionary +

        +
        +

        Representation of proposed client role mapping.

        +

        Returned: always

        +

        Sample: {"clientId": "test"}

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Gaëtan Daubresse (@Gaetan2907) +- Marius Huysamen (@mhuysamen) +- Alexander Groß (@agross) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_role.rst.txt b/main/_sources/plugins/keycloak_role.rst.txt index 0a0a5b9..2359b95 100644 --- a/main/_sources/plugins/keycloak_role.rst.txt +++ b/main/_sources/plugins/keycloak_role.rst.txt @@ -16,8 +16,8 @@ .. Title -keycloak_role -- Allows administration of Keycloak roles via Keycloak API -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +keycloak_role -- Allows administration of Keycloak roles using Keycloak API ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. Collection note @@ -35,7 +35,7 @@ keycloak_role -- Allows administration of Keycloak roles via Keycloak API .. rst-class:: ansible-version-added -New in middleware\_automation.keycloak 3.4.0 +New in middleware\_automation.keycloak 3.0.0 .. contents:: :local: @@ -49,9 +49,9 @@ Synopsis .. Description -- This module allows you to add, remove or modify Keycloak roles via the Keycloak REST API. It requires access to the REST API via OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. -- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/8.0/rest\-api/index.html `__. -- Attributes are multi\-valued in the Keycloak API. All attributes are lists of individual values and will be returned that way by this module. You may pass single values for attributes when calling the module, and this will be translated into a list suitable for the API. +- This module allows you to add, remove or modify Keycloak roles using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/latest/rest\-api/index.html `__. +- Attributes are multi\-valued in the Keycloak API. All attributes are lists of individual values and are returned that way by this module. You may pass single values for attributes when calling the module, and this is translated into a list suitable for the API. .. Aliases @@ -90,7 +90,7 @@ Parameters

        A dict of key/value pairs to set as custom attributes for the role.

        -

        Values may be single values (e.g. a string) or a list of strings.

        +

        Values may be single values (for example a string) or a list of strings.

        @@ -189,7 +189,7 @@ Parameters

        -

        If the role is a client role, the client id under which it resides.

        +

        If the role is a client role, the client ID under which it resides.

        If this parameter is absent, the role is considered a realm role.

        @@ -201,7 +201,6 @@ Parameters

        boolean

        -

        added in middleware_automation.keycloak 7.1.0

        If true, the role is a composition of other realm and/or client role.

        @@ -222,7 +221,6 @@ Parameters list / elements=dictionary

        -

        added in middleware_automation.keycloak 7.1.0

        List of roles to include to the composite realm role.

        @@ -288,7 +286,6 @@ Parameters

        integer

        -

        added in middleware_automation.keycloak 4.5.0

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        @@ -316,7 +313,6 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 5.4.0

        Configures the HTTP User-Agent header.

        @@ -353,6 +349,19 @@ Parameters
        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +
        +

        Authentication refresh token for Keycloak API.

        +
        + +

        state

        @@ -363,8 +372,8 @@ Parameters

        State of the role.

        -

        On present, the role will be created if it does not yet exist, or updated with the parameters you provide.

        -

        On absent, the role will be removed if it exists.

        +

        On present, the role is created if it does not yet exist, or updated with the parameters you provide.

        +

        On absent, the role is removed if it exists.

        Choices:

        • "present" ← (default)

          • @@ -373,7 +382,7 @@ Parameters
        - +

        token

        @@ -381,13 +390,12 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 3.0.0

        Authentication token for Keycloak API.

        - +

        validate_certs

        @@ -429,6 +437,50 @@ Attributes - Support - Description + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_role_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + * - .. raw:: html
        @@ -533,7 +585,7 @@ Examples realm: MyCustomRealm state: present auth_client_id: admin-cli - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com auth_realm: master auth_username: USERNAME auth_password: PASSWORD @@ -545,7 +597,7 @@ Examples realm: MyCustomRealm state: present auth_client_id: admin-cli - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com token: TOKEN delegate_to: localhost @@ -556,7 +608,7 @@ Examples client_id: MyClient state: present auth_client_id: admin-cli - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com auth_realm: master auth_username: USERNAME auth_password: PASSWORD @@ -567,7 +619,7 @@ Examples name: my-role-for-deletion state: absent auth_client_id: admin-cli - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com auth_realm: master auth_username: USERNAME auth_password: PASSWORD @@ -576,20 +628,20 @@ Examples - name: Create a keycloak role with some custom attributes middleware_automation.keycloak.keycloak_role: auth_client_id: admin-cli - auth_keycloak_url: https://auth.example.com/auth + auth_keycloak_url: https://auth.example.com auth_realm: master auth_username: USERNAME auth_password: PASSWORD name: my-new-role attributes: - attrib1: value1 - attrib2: value2 - attrib3: - - with - - numerous - - individual - - list - - items + attrib1: value1 + attrib2: value2 + attrib3: + - with + - numerous + - individual + - list + - items delegate_to: localhost diff --git a/main/_sources/plugins/keycloak_user.rst.txt b/main/_sources/plugins/keycloak_user.rst.txt new file mode 100644 index 0000000..a05e09d --- /dev/null +++ b/main/_sources/plugins/keycloak_user.rst.txt @@ -0,0 +1,1133 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_user_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_user -- Create and configure a user in Keycloak +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_user`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module creates, removes, or updates Keycloak users. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        access

        + +

        + dictionary +

        +
        +

        List user access.

        +
        +
        +

        attributes

        + +

        + list + / elements=dictionary +

        +
        +

        List of user attributes.

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the attribute.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        Control whether the attribute must exists or not.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        values

        + +

        + list + / elements=string +

        +
        +

        Values for the attribute as list.

        +
        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +

        auth_username

        + +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +
        +

        client_consents

        + +

        aliases: clientConsents

        +

        + list + / elements=dictionary +

        +
        +

        Client Authenticator Type.

        +

        Default: []

        +
        +
        +
        +
        +
        +

        client_id

        + +

        aliases: clientId

        +

        + string + / required +

        +
        +

        Client ID of the client role. Not the technical ID of the client.

        +
        +
        +
        +

        roles

        + +

        + list + / elements=string + / required +

        +
        +

        List of client roles to assign to the user.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        credentials

        + +

        + list + / elements=dictionary +

        +
        +

        User credentials.

        +

        Default: []

        +
        +
        +

        temporary

        + +

        + boolean +

        +
        +

        If true, the users are required to reset their credentials at next login.

        +

        Choices:

        +
          +

        • false ← (default)

          • +

        • true

          • +
        + +
        +
        +

        type

        + +

        + string + / required +

        +
        +

        Credential type.

        +
        +
        +

        value

        + +

        + string + / required +

        +
        +

        Value of the credential.

        +
        +
        +
        +

        disableable_credential_types

        + +

        aliases: disableableCredentialTypes

        +

        + list + / elements=string +

        +
        +

        List user Credential Type.

        +

        Default: []

        +
        +
        +

        email

        + +

        + string +

        +
        +

        User email.

        +
        +
        +
        +

        email_verified

        + +

        aliases: emailVerified

        +

        + boolean +

        +
        +

        Set or reset the emailVerified flag of the user.

        +

        When email_verified_behavior=no_defaults, the default value of this option becomes null and that causes the module not to change any existing value for that attribute.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +

        email_verified_behavior

        + +

        + string +

        +

        added in middleware_automation.keycloak 3.0.0

        +
        +

        The email_verified option used to have a default value. This caused problems when the user expects different behavior from keycloak by default.

        +

        The default value of this option is compatibility, which will ensure that the old default value for email_verified is used.

        +

        When set to no_defaults, the module will not change existing values of email_verified if no value is specified.

        +

        Choices:

        +
          +

        • "compatibility" ← (default)

          • +

        • "no_defaults"

          • +
        + +
        +
        +

        enabled

        + +

        + boolean +

        +
        +

        Enabled user.

        +

        Choices:

        +
          +

        • false

          • +

        • true

          • +
        + +
        +
        +
        +

        federated_identities

        + +

        aliases: federatedIdentities

        +

        + list + / elements=string +

        +
        +

        List of IDPs of user.

        +

        Default: []

        +
        + + +

        federation_link

        + +

        aliases: federationLink

        +

        + string +

        +
        +

        Federation Link.

        +
        +
        +
        +

        first_name

        + +

        aliases: firstName

        +

        + string +

        +
        +

        The user's first name.

        +
        +
        +

        force

        + +

        + boolean +

        +
        +

        If true, allows to remove user and recreate it.

        +

        Choices:

        +
          +

        • false ← (default)

          • +

        • true

          • +
        + +
        +
        +

        groups

        + +

        + list + / elements=dictionary +

        +
        +

        List of groups for the user.

        +

        Groups can be referenced by their name, like staff, or their path, like /staff/engineering. The path syntax allows you to reference subgroups, which is not possible otherwise.

        +

        Using the path is possible since middleware_automation.keycloak 3.0.0.

        +

        Default: []

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the group.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        Control whether the user must be member of this group or not.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        id

        + +

        + string +

        +
        +

        ID of the user on the Keycloak server if known.

        +
        +
        +
        +

        last_name

        + +

        aliases: lastName

        +

        + string +

        +
        +

        The user's last name.

        +
        +
        +

        origin

        + +

        + string +

        +
        +

        User origin.

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        The name of the realm in which is the client.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +
        +

        required_actions

        + +

        aliases: requiredActions

        +

        + list + / elements=string +

        +
        +

        Set or reset a user's required actions.

        +
        +
        +

        self

        + +

        + string +

        +
        +

        User self administration.

        +
        +
        +
        +

        service_account_client_id

        + +

        aliases: serviceAccountClientId

        +

        + string +

        +
        +

        Description of the client Application.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        Control whether the user should exists or not.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        username

        + +

        + string + / required +

        +
        +

        Username for the user.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_user_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_user_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_user_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + +Notes +----- + +.. note:: + - The module does not modify the user ID of an existing user. + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Create a user user1 + middleware_automation.keycloak.keycloak_user: + auth_keycloak_url: http://localhost:8080 + auth_username: admin + auth_password: password + realm: master + username: user1 + firstName: user1 + lastName: user1 + email: user1 + enabled: true + emailVerified: false + credentials: + - type: password + value: password + temporary: false + attributes: + - name: attr1 + values: + - value1 + state: present + - name: attr2 + values: + - value2 + state: absent + groups: + - name: group1 + state: present + state: present + + - name: Re-create a User + middleware_automation.keycloak.keycloak_user: + auth_keycloak_url: http://localhost:8080 + auth_username: admin + auth_password: password + realm: master + username: user1 + firstName: user1 + lastName: user1 + email: user1 + enabled: true + emailVerified: false + credentials: + - type: password + value: password + temporary: false + attributes: + - name: attr1 + values: + - value1 + state: present + - name: attr2 + values: + - value2 + state: absent + groups: + - name: group1 + state: present + state: present + + - name: Re-create a User + middleware_automation.keycloak.keycloak_user: + auth_keycloak_url: http://localhost:8080 + auth_username: admin + auth_password: password + realm: master + username: user1 + firstName: user1 + lastName: user1 + email: user1 + enabled: true + emailVerified: false + credentials: + - type: password + value: password + temporary: false + attributes: + - name: attr1 + values: + - value1 + state: present + - name: attr2 + values: + - value2 + state: absent + groups: + - name: group1 + state: present + state: present + force: true + + - name: Remove User + middleware_automation.keycloak.keycloak_user: + auth_keycloak_url: http://localhost:8080 + auth_username: admin + auth_password: password + realm: master + username: user1 + state: absent + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of the user after module execution.

        +

        Returned: on success

        +
        +
        +

        existing

        + +

        + dictionary +

        +
        +

        Representation of the existing user.

        +

        Returned: on success

        +
        +
        +

        proposed

        + +

        + dictionary +

        +
        +

        Representation of the proposed user.

        +

        Returned: on success

        +
        +
        +

        user_created

        + +

        + boolean +

        +
        +

        Indicates whether a user was created.

        +

        Returned: in success

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Philippe Gauthier (@elfelip) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_user_execute_actions_email.rst.txt b/main/_sources/plugins/keycloak_user_execute_actions_email.rst.txt new file mode 100644 index 0000000..8186b32 --- /dev/null +++ b/main/_sources/plugins/keycloak_user_execute_actions_email.rst.txt @@ -0,0 +1,611 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_user_execute_actions_email_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_user_execute_actions_email -- Send a Keycloak execute\-actions email to a user ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_user_execute_actions_email`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- Triggers the Keycloak endpoint :literal:`execute\-actions\-email` for a user. This sends an email with one or more required actions the user must complete (for example resetting the password). +- If no :ansopt:`middleware\_automation.keycloak.keycloak\_user\_execute\_actions\_email#module:actions` list is provided, the default action :literal:`UPDATE\_PASSWORD` is used. +- You must supply either the user's :ansopt:`middleware\_automation.keycloak.keycloak\_user\_execute\_actions\_email#module:id` or :ansopt:`middleware\_automation.keycloak.keycloak\_user\_execute\_actions\_email#module:username`. Supplying only :literal:`username` causes an extra lookup call. +- This module always reports :ansretval:`changed=true` because sending an email is a side effect and cannot be made idempotent. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        actions

        + +

        + list + / elements=string +

        +
        +

        List of required actions to include in the email.

        +

        Default: ["UPDATE_PASSWORD"]

        +
        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +

        auth_username

        + +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +
        +

        client_id

        + +

        aliases: clientId

        +

        + string +

        +
        +

        Optional client ID used for the redirect link.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        id

        + +

        + string +

        +
        +

        The unique ID (UUID) of the user.

        +

        Mutually exclusive with username.

        +
        +
        +

        lifespan

        + +

        + integer +

        +
        +

        Optional lifespan (in seconds) for the action token (supported on newer Keycloak versions). Forwarded as query parameter if provided.

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        The Keycloak realm where the user resides.

        +

        Default: "master"

        +
        +
        +
        +

        redirect_uri

        + +

        aliases: redirectUri

        +

        + string +

        +
        +

        Optional redirect URI. Must be valid for the given client if client_id is set.

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        username

        + +

        + string +

        +
        +

        Username of the user.

        +

        Mutually exclusive with id.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_user_execute_actions_email_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_user_execute_actions_email_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_user_execute_actions_email_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-none:`none` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Password reset email (default action) with 1h lifespan + middleware_automation.keycloak.keycloak_user_execute_actions_email: + username: johndoe + realm: MyRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: ADMIN + auth_password: SECRET + lifespan: 3600 + delegate_to: localhost + + - name: Multiple required actions using token auth + middleware_automation.keycloak.keycloak_user_execute_actions_email: + username: johndoe + actions: + - UPDATE_PASSWORD + - VERIFY_EMAIL + realm: MyRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + delegate_to: localhost + + - name: Email by user id with redirect + middleware_automation.keycloak.keycloak_user_execute_actions_email: + id: 9d59aa76-2755-48c6-b1af-beb70a82c3cd + client_id: my-frontend + redirect_uri: https://app.example.com/post-actions + actions: + - UPDATE_PASSWORD + realm: MyRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: ADMIN + auth_password: SECRET + delegate_to: localhost + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        actions

        + +

        + list + / elements=string +

        +
        +

        List of actions included in the email.

        +

        Returned: success

        +
        +
        +

        user_id

        + +

        + string +

        +
        +

        The user ID the email was (or would be, in check mode) sent to.

        +

        Returned: success

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Marius Bertram (@mariusbertram) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_user_federation.rst.txt b/main/_sources/plugins/keycloak_user_federation.rst.txt index b1df54d..cef7227 100644 --- a/main/_sources/plugins/keycloak_user_federation.rst.txt +++ b/main/_sources/plugins/keycloak_user_federation.rst.txt @@ -16,8 +16,8 @@ .. Title -keycloak_user_federation -- Allows administration of Keycloak user federations via Keycloak API -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +keycloak_user_federation -- Allows administration of Keycloak user federations using Keycloak API ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. Collection note @@ -35,7 +35,7 @@ keycloak_user_federation -- Allows administration of Keycloak user federations v .. rst-class:: ansible-version-added -New in middleware\_automation.keycloak 3.7.0 +New in middleware\_automation.keycloak 3.0.0 .. contents:: :local: @@ -49,7 +49,7 @@ Synopsis .. Description -- This module allows you to add, remove or modify Keycloak user federations via the Keycloak REST API. It requires access to the REST API via OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- This module allows you to add, remove or modify Keycloak user federations using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. - The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/20.0.2/rest\-api/index.html `__. @@ -175,8 +175,8 @@ Parameters

        The value of the config parameter config.bindCredential is redacted in the Keycloak responses. Comparing the redacted value with the desired value always evaluates to not equal. This means the before and desired states are never equal if the parameter is set.

        -

        Set to always to include config.bindCredential in the comparison of before and desired state. Because of the redacted value returned by Keycloak the module will always detect a change and make an update if a config.bindCredential value is set.

        -

        Set to only_indirect to exclude config.bindCredential when comparing the before state with the desired state. The value of config.bindCredential will only be updated if there are other changes to the user federation that require an update.

        +

        Set to always to include config.bindCredential in the comparison of before and desired state. Because of the redacted value returned by Keycloak the module always detects a change and make an update if a config.bindCredential value is set.

        +

        Set to only_indirect to exclude config.bindCredential when comparing the before state with the desired state. The value of config.bindCredential is only updated if there are other changes to the user federation that require an update.

        Choices:

        • "always" ← (default)

          • @@ -196,7 +196,7 @@ Parameters

        Dict specifying the configuration options for the provider; the contents differ depending on the value of provider_id. Examples are given below for ldap, kerberos and sssd. It is easiest to obtain valid config values by dumping an already-existing user federation configuration through check-mode in the existing field.

        -

        The value sssd has been supported since middleware_automation.keycloak 2.0.0.

        +

        The value sssd has been supported since middleware_automation.keycloak 4.2.0.

        @@ -209,7 +209,7 @@ Parameters

        -

        Enable/disable HTTP authentication of users with SPNEGO/Kerberos tokens. The data about authenticated users will be provisioned from this LDAP server.

        +

        Enable/disable HTTP authentication of users with SPNEGO/Kerberos tokens. The data about authenticated users is provisioned from this LDAP server.

        Choices:

        • false ← (default)

          • @@ -293,7 +293,7 @@ Parameters

        -

        DN of LDAP user which will be used by Keycloak to access LDAP server.

        +

        DN of LDAP user which is used by Keycloak to access LDAP server.

        @@ -485,7 +485,7 @@ Parameters

        -

        Additional LDAP Filter for filtering searched users. Leave this empty if you don't need additional filter.

        +

        Additional LDAP Filter for filtering searched users. Leave this empty if you do not need additional filter.

        @@ -517,7 +517,7 @@ Parameters

        -

        READ_ONLY is a read-only LDAP store. WRITABLE means data will be synced back to LDAP on demand. UNSYNCED means user data will be imported, but not synced back to LDAP.

        +

        READ_ONLY is a read-only LDAP store. WRITABLE means data is synced back to LDAP on demand. UNSYNCED means user data is imported, but not synced back to LDAP.

        Choices:

        • "READ_ONLY"

          • @@ -556,7 +556,7 @@ Parameters

        -

        Day of the week the entry will become invalid on.

        +

        Day of the week the entry is set to become invalid on.

        @@ -569,7 +569,7 @@ Parameters

        -

        Hour of day the entry will become invalid on.

        +

        Hour of day the entry is set to become invalid on.

        @@ -582,7 +582,7 @@ Parameters

        -

        Minute of day the entry will become invalid on.

        +

        Minute of day the entry is set to become invalid on.

        @@ -609,7 +609,7 @@ Parameters

        -

        If true, LDAP users will be imported into Keycloak DB and synced by the configured sync policies.

        +

        If true, LDAP users are imported into Keycloak DB and synced by the configured sync policies.

        Choices:

        • false

          • @@ -654,7 +654,7 @@ Parameters

        -

        Name of the LDAP attribute, which refers to Kerberos principal. This is used to lookup appropriate LDAP user after successful Kerberos/SPNEGO authentication in Keycloak. When this is empty, the LDAP user will be looked based on LDAP username corresponding to the first part of his Kerberos principal. For instance, for principal john@KEYCLOAK.ORG, it will assume that LDAP username is john.

        +

        Name of the LDAP attribute, which refers to Kerberos principal. This is used to lookup appropriate LDAP user after successful Kerberos/SPNEGO authentication in Keycloak. When this is empty, the LDAP user is looked up based on LDAP username corresponding to the first part of his Kerberos principal. For instance, for principal john@KEYCLOAK.ORG, it assumes that LDAP username is john.

        @@ -713,7 +713,7 @@ Parameters

        -

        Name of LDAP attribute, which is used as RDN (top attribute) of typical user DN. Usually it's the same as Username LDAP attribute, however it is not required. For example for Active directory, it is common to use cn as RDN attribute when username attribute might be sAMAccountName.

        +

        Name of LDAP attribute, which is used as RDN (top attribute) of typical user DN. Usually it is the same as Username LDAP attribute, however it is not required. For example for Active directory, it is common to use cn as RDN attribute when username attribute might be sAMAccountName.

        @@ -790,7 +790,7 @@ Parameters

        -

        Encrypts the connection to LDAP using STARTTLS, which will disable connection pooling.

        +

        Encrypts the connection to LDAP using STARTTLS, which disables connection pooling.

        Choices:

        • false ← (default)

          • @@ -917,7 +917,7 @@ Parameters

        -

        All values of LDAP objectClass attribute for users in LDAP divided by comma. For example inetOrgPerson, organizationalPerson. Newly created Keycloak users will be written to LDAP with all those object classes and existing LDAP user records are found just if they contain all those object classes.

        +

        All values of LDAP objectClass attribute for users in LDAP divided by comma. For example inetOrgPerson, organizationalPerson. Newly created Keycloak users are written to LDAP with all those object classes and existing LDAP user records are found just if they contain all those object classes.

        @@ -943,7 +943,8 @@ Parameters

        -

        Specifies whether LDAP connection will use the truststore SPI with the truststore configured in standalone.xml/domain.xml. always means that it will always use it. never means that it will not use it. ldapsOnly means that it will use if your connection URL use ldaps. Note even if standalone.xml/domain.xml is not configured, the default Java cacerts or certificate specified by javax.net.ssl.trustStore property will be used.

        +

        Specifies whether LDAP connection uses the truststore SPI with the truststore configured in standalone.xml/domain.xml. always means that it always uses it. never means that it does not use it. ldapsOnly means that it uses if your connection URL use ldaps.

        +

        Note even if standalone.xml/domain.xml is not configured, the default Java cacerts or certificate specified by javax.net.ssl.trustStore property is used.

        Choices:

        • "always"

          • @@ -1008,7 +1009,6 @@ Parameters

          integer

          -

          added in middleware_automation.keycloak 4.5.0

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        @@ -1023,7 +1023,6 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 5.4.0

        Configures the HTTP User-Agent header.

        @@ -1040,7 +1039,7 @@ Parameters

        -

        The unique ID for this user federation. If left empty, the user federation will be searched by its name.

        +

        The unique ID for this user federation. If left empty, the user federation is searched by its name.

        @@ -1093,7 +1092,7 @@ Parameters

        -

        Name of the mapper. If no ID is given, the mapper will be searched by name.

        +

        Name of the mapper. If no ID is given, the mapper is searched by name.

        @@ -1106,7 +1105,7 @@ Parameters

        -

        Unique ID for the parent of this mapper. ID of the user federation will automatically be used if left blank.

        +

        Unique ID for the parent of this mapper. ID of the user federation is automatically used if left blank.

        @@ -1162,7 +1161,7 @@ Parameters

        -

        Unique ID for the parent of this user federation. Realm ID will be automatically used if left blank.

        +

        Unique ID for the parent of this user federation. Realm ID is automatically used if left blank.

        @@ -1211,6 +1210,19 @@ Parameters +
        +
        +

        refresh_token

        + +

        + string +

        +
        +
        +

        Authentication refresh token for Keycloak API.

        +
        + +

        remove_unspecified_mappers

        @@ -1230,7 +1242,7 @@ Parameters
        - +

        state

        @@ -1241,8 +1253,8 @@ Parameters

        State of the user federation.

        -

        On present, the user federation will be created if it does not yet exist, or updated with the parameters you provide.

        -

        On absent, the user federation will be removed if it exists.

        +

        On present, the user federation is created if it does not yet exist, or updated with the parameters you provide.

        +

        On absent, the user federation is removed if it exists.

        Choices:

        • "present" ← (default)

          • @@ -1251,7 +1263,7 @@ Parameters
        - +

        token

        @@ -1259,13 +1271,12 @@ Parameters

        string

        -

        added in middleware_automation.keycloak 3.0.0

        Authentication token for Keycloak API.

        - +

        validate_certs

        @@ -1307,6 +1318,50 @@ Attributes - Support - Description + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_user_federation_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + * - .. raw:: html
        @@ -1407,7 +1462,7 @@ Examples - name: Create LDAP user federation middleware_automation.keycloak.keycloak_user_federation: - auth_keycloak_url: https://keycloak.example.com/auth + auth_keycloak_url: https://keycloak.example.com auth_realm: master auth_username: admin auth_password: password @@ -1417,32 +1472,32 @@ Examples provider_id: ldap provider_type: org.keycloak.storage.UserStorageProvider config: - priority: 0 - enabled: true - cachePolicy: DEFAULT - batchSizeForSync: 1000 - editMode: READ_ONLY - importEnabled: true - syncRegistrations: false - vendor: other - usernameLDAPAttribute: uid - rdnLDAPAttribute: uid - uuidLDAPAttribute: entryUUID - userObjectClasses: inetOrgPerson, organizationalPerson - connectionUrl: ldaps://ldap.example.com:636 - usersDn: ou=Users,dc=example,dc=com - authType: simple - bindDn: cn=directory reader - bindCredential: password - searchScope: 1 - validatePasswordPolicy: false - trustEmail: false - useTruststoreSpi: ldapsOnly - connectionPooling: true - pagination: true - allowKerberosAuthentication: false - debug: false - useKerberosForPasswordAuthentication: false + priority: 0 + enabled: true + cachePolicy: DEFAULT + batchSizeForSync: 1000 + editMode: READ_ONLY + importEnabled: true + syncRegistrations: false + vendor: other + usernameLDAPAttribute: uid + rdnLDAPAttribute: uid + uuidLDAPAttribute: entryUUID + userObjectClasses: inetOrgPerson, organizationalPerson + connectionUrl: ldaps://ldap.example.com:636 + usersDn: ou=Users,dc=example,dc=com + authType: simple + bindDn: cn=directory reader + bindCredential: password + searchScope: 1 + validatePasswordPolicy: false + trustEmail: false + useTruststoreSpi: ldapsOnly + connectionPooling: true + pagination: true + allowKerberosAuthentication: false + debug: false + useKerberosForPasswordAuthentication: false mappers: - name: "full name" providerId: "full-name-ldap-mapper" @@ -1454,7 +1509,7 @@ Examples - name: Create Kerberos user federation middleware_automation.keycloak.keycloak_user_federation: - auth_keycloak_url: https://keycloak.example.com/auth + auth_keycloak_url: https://keycloak.example.com auth_realm: master auth_username: admin auth_password: password @@ -1475,7 +1530,7 @@ Examples - name: Create sssd user federation middleware_automation.keycloak.keycloak_user_federation: - auth_keycloak_url: https://keycloak.example.com/auth + auth_keycloak_url: https://keycloak.example.com auth_realm: master auth_username: admin auth_password: password @@ -1485,13 +1540,13 @@ Examples provider_id: sssd provider_type: org.keycloak.storage.UserStorageProvider config: - priority: 0 - enabled: true - cachePolicy: DEFAULT + priority: 0 + enabled: true + cachePolicy: DEFAULT - name: Delete user federation middleware_automation.keycloak.keycloak_user_federation: - auth_keycloak_url: https://keycloak.example.com/auth + auth_keycloak_url: https://keycloak.example.com auth_realm: master auth_username: admin auth_password: password diff --git a/main/_sources/plugins/keycloak_user_rolemapping.rst.txt b/main/_sources/plugins/keycloak_user_rolemapping.rst.txt new file mode 100644 index 0000000..ee29407 --- /dev/null +++ b/main/_sources/plugins/keycloak_user_rolemapping.rst.txt @@ -0,0 +1,747 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_user_rolemapping_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_user_rolemapping -- Allows administration of Keycloak user\_rolemapping with the Keycloak API +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_user_rolemapping`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to add, remove or modify Keycloak user\_rolemapping with the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, admin\-cli and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/latest/rest\-api/index.html `__. +- Attributes are multi\-valued in the Keycloak API. All attributes are lists of individual values and are returned that way by this module. You may pass single values for attributes when calling the module, and this is translated into a list suitable for the API. +- When updating a user\_rolemapping, where possible provide the role ID to the module. This removes a lookup to the API to translate the name into the role ID. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        cid

        + +

        + string +

        +
        +

        ID of the client whose role is to be mapped.

        +

        This parameter is not required for updating or deleting the rolemapping but providing it reduces the number of API calls required.

        +

        If neither cid nor client_id is specified, a realm role is mapped instead.

        +
        +
        +

        client_id

        + +

        + string +

        +
        +

        Name of the client (different than cid) whose role is to be mapped.

        +

        This parameter is required if cid is not provided (can be replaced by cid to reduce the number of API calls that must be made).

        +

        If neither cid nor client_id is specified, a realm role is mapped instead.

        +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +

        realm

        + +

        + string +

        +
        +

        They Keycloak realm under which this role_representation resides.

        +

        Default: "master"

        +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        roles

        + +

        + list + / elements=dictionary +

        +
        +

        Roles to be mapped to the user.

        +
        +
        +

        id

        + +

        + string +

        +
        +

        The unique identifier for this role_representation.

        +

        This parameter is not required for updating or deleting a role_representation but providing it reduces the number of API calls required.

        +
        +
        +

        name

        + +

        + string +

        +
        +

        Name of the role representation.

        +

        This parameter is required only when creating or updating the role_representation.

        +
        +
        +

        service_account_user_client_id

        + +

        + string +

        +
        +

        Client ID of the service-account-user to be mapped.

        +

        This parameter is not required for updating or deleting the rolemapping but providing it reduces the number of API calls required.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the user_rolemapping.

        +

        On present, the user_rolemapping is created if it does not yet exist, or updated with the parameters you provide.

        +

        On absent, the user_rolemapping is removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        target_username

        + +

        + string +

        +
        +

        Username of the user roles are mapped to.

        +

        This parameter is not required (can be replaced by uid for less API call).

        +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        uid

        + +

        + string +

        +
        +

        ID of the user to be mapped.

        +

        This parameter is not required for updating or deleting the rolemapping but providing it reduces the number of API calls required.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_user_rolemapping_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_user_rolemapping_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_user_rolemapping_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Map a realm role to a user, authentication with credentials + middleware_automation.keycloak.keycloak_user_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + state: present + uid: user_uid + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + - name: Map a client role to a user, authentication with credentials + middleware_automation.keycloak.keycloak_user_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + state: present + client_id: client1 + uid: user_uid + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + - name: Map a client role to a service account user for a client, authentication with credentials + middleware_automation.keycloak.keycloak_user_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + state: present + client_id: client1 + service_account_user_client_id: clientIdOfServiceAccount + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + - name: Map a client role to a user, authentication with token + middleware_automation.keycloak.keycloak_user_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + token: TOKEN + state: present + client_id: client1 + target_username: user1 + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + - name: Unmap client role from a user + middleware_automation.keycloak.keycloak_user_rolemapping: + realm: MyCustomRealm + auth_client_id: admin-cli + auth_keycloak_url: https://auth.example.com + auth_realm: master + auth_username: USERNAME + auth_password: PASSWORD + state: absent + client_id: client1 + uid: 70e3ae72-96b6-11e6-9056-9737fd4d0764 + roles: + - name: role_name1 + id: role_id1 + - name: role_name2 + id: role_id2 + delegate_to: localhost + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        end_state

        + +

        + dictionary +

        +
        +

        Representation of client role mapping after module execution.

        +

        The sample is truncated.

        +

        Returned: on success

        +

        Sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}

        +
        +
        +

        existing

        + +

        + dictionary +

        +
        +

        Representation of existing client role mapping.

        +

        The sample is truncated.

        +

        Returned: always

        +

        Sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        Message as to what action was taken.

        +

        Returned: always

        +

        Sample: "Role role1 assigned to user user1."

        +
        +
        +

        proposed

        + +

        + dictionary +

        +
        +

        Representation of proposed client role mapping.

        +

        Returned: always

        +

        Sample: {"clientId": "test"}

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Dušan Marković (@bratwurzt) +- Ivan Kokalović (@koke1997) + + +.. Extra links + + +.. Parsing errors diff --git a/main/_sources/plugins/keycloak_userprofile.rst.txt b/main/_sources/plugins/keycloak_userprofile.rst.txt new file mode 100644 index 0000000..5a2eea2 --- /dev/null +++ b/main/_sources/plugins/keycloak_userprofile.rst.txt @@ -0,0 +1,1306 @@ +.. Document meta + +:orphan: + +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + +.. meta:: + :antsibull-docs: 2.24.0 + +.. Anchors + +.. _ansible_collections.middleware_automation.keycloak.keycloak_userprofile_module: + +.. Anchors: short name for ansible.builtin + +.. Title + +keycloak_userprofile -- Allows managing Keycloak User Profiles +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This module is part of the `middleware_automation.keycloak collection `_. + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. + + To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_userprofile`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in middleware\_automation.keycloak 3.0.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- This module allows you to create, update, or delete Keycloak User Profiles using the Keycloak API. You can also customize the "Unmanaged Attributes" with it. +- The names of module options are snake\_cased versions of the camelCase ones found in the Keycloak API and its documentation at \ `https://www.keycloak.org/docs\-api/24.0.5/rest\-api/index.html `__. For compatibility reasons, the module also accepts the camelCase versions of the options. + + +.. Aliases + + +.. Requirements + + + + + + +.. Options + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

        Parameter

        Comments

        +
        +

        auth_client_id

        + +

        + string +

        +
        +

        OpenID Connect client_id to authenticate to the API with.

        +

        Default: "admin-cli"

        +
        +
        +

        auth_client_secret

        + +

        + string +

        +
        +

        Client Secret to use in conjunction with auth_client_id (if required).

        +
        +
        +
        +

        auth_keycloak_url

        + +

        aliases: url

        +

        + string + / required +

        +
        +

        URL to the Keycloak instance.

        +
        +
        +
        +

        auth_password

        + +

        aliases: password

        +

        + string +

        +
        +

        Password to authenticate for API access with.

        +
        +
        +

        auth_realm

        + +

        + string +

        +
        +

        Keycloak realm name to authenticate to for API access.

        +
        +
        +
        +

        auth_username

        + +

        aliases: username

        +

        + string +

        +
        +

        Username to authenticate for API access with.

        +
        +
        +

        config

        + +

        + dictionary +

        +
        +

        The configuration of the User Profile Provider.

        +
        +
        +
        +

        kc_user_profile_config

        + +

        aliases: kcUserProfileConfig

        +

        + list + / elements=dictionary +

        +
        +

        Define a declarative User Profile. See EXAMPLES for more context.

        +
        +
        +
        +

        attributes

        + +

        + list + / elements=dictionary +

        +
        +

        A list of attributes to be included in the User Profile.

        +
        +
        +
        +

        annotations

        + +

        + dictionary +

        +
        +

        Annotations for the attribute.

        +
        +
        +
        +
        +
        +

        display_name

        + +

        aliases: displayName

        +

        + string + / required +

        +
        +

        The display name of the attribute.

        +
        +
        +
        +

        group

        + +

        + string +

        +
        +

        Specifies the User Profile group where this attribute is added.

        +
        +
        +
        +

        multivalued

        + +

        + boolean +

        +
        +

        Whether the attribute can have multiple values.

        +

        Choices:

        +
          +

        • false ← (default)

          • +

        • true

          • +
        + +
        +
        +
        +

        name

        + +

        + string + / required +

        +
        +

        The name of the attribute.

        +
        +
        +
        +

        permissions

        + +

        + dictionary +

        +
        +

        The permissions for viewing and editing the attribute.

        +
        +
        +
        +

        edit

        + +

        + list + / elements=string +

        +
        +

        The roles that can edit the attribute.

        +

        Supported values are admin and user.

        +

        Default: ["admin", "user"]

        +
        +
        +
        +

        view

        + +

        + list + / elements=string +

        +
        +

        The roles that can view the attribute.

        +

        Supported values are admin and user.

        +

        Default: ["admin", "user"]

        +
        +
        +
        +

        required

        + +

        + dictionary +

        +
        +

        The roles that require this attribute.

        +
        +
        +
        +

        roles

        + +

        + list + / elements=string +

        +
        +

        The roles for which this attribute is required.

        +

        Supported values are admin and user.

        +

        Default: ["user"]

        +
        +
        +
        +

        selector

        + +

        + dictionary +

        +
        +

        Selector when the attribute should be added.

        +
        +
        +
        +

        scopes

        + +

        + list + / elements=string +

        +
        +

        Scopes to which the attribute should be added.

        +
        +
        +
        +

        validations

        + +

        + dictionary +

        +
        +

        The validations to be applied to the attribute.

        +
        +
        +
        +

        double

        + +

        + dictionary +

        +
        +

        The double validation for the attribute.

        +
        +
        +
        +

        email

        + +

        + dictionary +

        +
        +

        The email validation for the attribute.

        +
        +
        +
        +

        integer

        + +

        + dictionary +

        +
        +

        The integer validation for the attribute.

        +
        +
        +
        +
        +
        +

        iso_date

        + +

        aliases: isoDate

        +

        + dictionary +

        +
        +

        The iso-date validation for the attribute.

        +
        +
        +
        +

        length

        + +

        + dictionary +

        +
        +

        The length validation for the attribute.

        +
        +
        +
        +

        max

        + +

        + integer + / required +

        +
        +

        The maximum length of the attribute.

        +
        +
        +
        +

        min

        + +

        + integer +

        +
        +

        The minimum length of the attribute.

        +
        +
        +
        +
        +
        +

        local_date

        + +

        aliases: localDate

        +

        + dictionary +

        +
        +

        The local-date validation for the attribute.

        +
        +
        +
        +

        multivalued

        + +

        + dictionary +

        +
        +

        The multivalued validation for the attribute.

        +
        +
        +
        +

        max

        + +

        + integer + / required +

        +
        +

        The maximum amount of values of the attribute.

        +
        +
        +
        +

        min

        + +

        + integer +

        +
        +

        The minimum amount of values of the attribute.

        +
        +
        +
        +

        options

        + +

        + dictionary +

        +
        +

        Validation to ensure the attribute matches one of the provided options.

        +
        +
        +
        +

        pattern

        + +

        + dictionary +

        +
        +

        The pattern validation for the attribute using regular expressions.

        +
        +
        +
        +
        +
        +

        person_name_prohibited_characters

        + +

        aliases: personNameProhibitedCharacters

        +

        + dictionary +

        +
        +

        The prohibited characters validation for person name attributes.

        +
        +
        +
        +
        +
        +

        up_username_not_idn_homograph

        + +

        aliases: upUsernameNotIdnHomograph

        +

        + dictionary +

        +
        +

        The validation to prevent IDN homograph attacks in usernames.

        +
        +
        +
        +

        uri

        + +

        + dictionary +

        +
        +

        The URI validation for the attribute.

        +
        +
        +
        +
        +
        +

        username_prohibited_characters

        + +

        aliases: usernameProhibitedCharacters

        +

        + dictionary +

        +
        +

        The prohibited characters validation for the username attribute.

        +
        +
        +
        +

        groups

        + +

        + list + / elements=dictionary +

        +
        +

        A list of attribute groups to be included in the User Profile.

        +
        +
        +
        +

        annotations

        + +

        + dictionary +

        +
        +

        The annotations included in the group.

        +
        +
        +
        +
        +
        +

        display_description

        + +

        aliases: displayDescription

        +

        + string +

        +
        +

        The display description for the group.

        +
        +
        +
        +
        +
        +

        display_header

        + +

        aliases: displayHeader

        +

        + string + / required +

        +
        +

        The display header for the group.

        +
        +
        +
        +

        name

        + +

        + string + / required +

        +
        +

        The name of the group.

        +
        +
        +
        +
        +
        +

        unmanaged_attribute_policy

        + +

        aliases: unmanagedAttributePolicy

        +

        + string +

        +
        +

        Policy for unmanaged attributes.

        +

        Choices:

        +
          +

        • "ENABLED"

          • +

        • "ADMIN_EDIT"

          • +

        • "ADMIN_VIEW"

          • +
        + +
        +
        +

        connection_timeout

        + +

        + integer +

        +
        +

        Controls the HTTP connections timeout period (in seconds) to Keycloak API.

        +

        Default: 10

        +
        +
        +

        http_agent

        + +

        + string +

        +
        +

        Configures the HTTP User-Agent header.

        +

        Default: "Ansible"

        +
        +
        +
        +
        +

        parent_id

        + +

        aliases: parentId, realm

        +

        + string + / required +

        +
        +

        The parent ID of the realm key. In practice the ID (name) of the realm.

        +
        +
        +
        +

        provider_id

        + +

        aliases: providerId

        +

        + string +

        +
        +

        The name of the provider ID for the key (supported value is declarative-user-profile).

        +

        Choices:

        +
          +

        • "declarative-user-profile" ← (default)

          • +
        + +
        +
        +
        +

        provider_type

        + +

        aliases: providerType

        +

        + string +

        +
        +

        Component type for User Profile (only supported value is org.keycloak.userprofile.UserProfileProvider).

        +

        Choices:

        +
          +

        • "org.keycloak.userprofile.UserProfileProvider" ← (default)

          • +
        + +
        +
        +

        refresh_token

        + +

        + string +

        +
        +

        Authentication refresh token for Keycloak API.

        +
        +
        +

        state

        + +

        + string +

        +
        +

        State of the User Profile provider.

        +

        On present, the User Profile provider is created if it does not yet exist, or updated with the parameters you provide.

        +

        On absent, the User Profile provider is removed if it exists.

        +

        Choices:

        +
          +

        • "present" ← (default)

          • +

        • "absent"

          • +
        + +
        +
        +

        token

        + +

        + string +

        +
        +

        Authentication token for Keycloak API.

        +
        +
        +

        validate_certs

        + +

        + boolean +

        +
        +

        Verify TLS certificates (do not disable this in production).

        +

        Choices:

        +
          +

        • false

          • +

        • true ← (default)

          • +
        + +
        + + + +.. Attributes + + +Attributes +---------- + +.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Attribute + - Support + - Description + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_userprofile_module__attribute-action_group: + + .. rst-class:: ansible-option-title + + **action_group** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` + + :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_userprofile_module__attribute-check_mode: + + .. rst-class:: ansible-option-title + + **check_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Can run in :literal:`check\_mode` and return changed status prediction without modifying target. + + + .. raw:: html + +
        + + + * - .. raw:: html + +
        +
        + + .. _ansible_collections.middleware_automation.keycloak.keycloak_userprofile_module__attribute-diff_mode: + + .. rst-class:: ansible-option-title + + **diff_mode** + + .. raw:: html + + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` + + + .. raw:: html + +
        + + - .. raw:: html + +
        + + Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. + + + .. raw:: html + +
        + + + +.. Notes + +Notes +----- + +.. note:: + - Currently, only a single :ansval:`declarative\-user\-profile` entry is supported for :ansopt:`middleware\_automation.keycloak.keycloak\_userprofile#module:provider\_id` (design of the Keyckoak API). However, there can be multiple :ansopt:`middleware\_automation.keycloak.keycloak\_userprofile#module:config.kc\_user\_profile\_config[].attributes[]` entries. + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + - name: Create a Declarative User Profile with default settings + middleware_automation.keycloak.keycloak_userprofile: + state: present + parent_id: master + config: + kc_user_profile_config: + - attributes: + - name: username + displayName: ${username} + validations: + length: + min: 3 + max: 255 + username_prohibited_characters: {} + up_username_not_idn_homograph: {} + annotations: {} + permissions: + view: + - admin + - user + edit: [] + multivalued: false + - name: email + displayName: ${email} + validations: + email: {} + length: + max: 255 + annotations: {} + required: + roles: + - user + permissions: + view: + - admin + - user + edit: [] + multivalued: false + - name: firstName + displayName: ${firstName} + validations: + length: + max: 255 + person_name_prohibited_characters: {} + annotations: {} + required: + roles: + - user + permissions: + view: + - admin + - user + edit: [] + multivalued: false + - name: lastName + displayName: ${lastName} + validations: + length: + max: 255 + person_name_prohibited_characters: {} + annotations: {} + required: + roles: + - user + permissions: + view: + - admin + - user + edit: [] + multivalued: false + - name: testAttribute + displayName: ${testAttribute} + validations: + integer: + min: 0 + max: 255 + annotations: {} + required: + roles: + - user + permissions: + view: + - admin + - user + edit: [] + multivalued: false + groups: + - name: user-metadata + displayHeader: User metadata + displayDescription: Attributes, which refer to user metadata + annotations: {} + + - name: Delete a Keycloak User Profile Provider + keycloak_userprofile: + state: absent + parent_id: master + + # Unmanaged attributes are user attributes not explicitly defined in the User Profile + # configuration. By default, unmanaged attributes are "Disabled" and are not + # available from any context such as registration, account, and the + # administration console. By setting "Enabled", unmanaged attributes are fully + # recognized by the server and accessible through all contexts, useful if you are + # starting migrating an existing realm to the declarative User Profile + # and you don't have yet all user attributes defined in the User Profile configuration. + - name: Enable Unmanaged Attributes + middleware_automation.keycloak.keycloak_userprofile: + state: present + parent_id: master + config: + kc_user_profile_config: + - unmanagedAttributePolicy: ENABLED + + # By setting "Only administrators can write", unmanaged attributes can be managed + # only through the administration console and API, useful if you have already + # defined any custom attribute that can be managed by users but you are unsure + # about adding other attributes that should only be managed by administrators. + - name: Enable ADMIN_EDIT on Unmanaged Attributes + middleware_automation.keycloak.keycloak_userprofile: + state: present + parent_id: master + config: + kc_user_profile_config: + - unmanagedAttributePolicy: ADMIN_EDIT + + # By setting `Only administrators can view`, unmanaged attributes are read-only + # and only available through the administration console and API. + - name: Enable ADMIN_VIEW on Unmanaged Attributes + middleware_automation.keycloak.keycloak_userprofile: + state: present + parent_id: master + config: + kc_user_profile_config: + - unmanagedAttributePolicy: ADMIN_VIEW + + + +.. Facts + + +.. Return values + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + +

        Key

        Description

        +
        +

        data

        + +

        + dictionary +

        +
        +

        The data returned by the Keycloak API.

        +

        Returned: when state is present

        +
        +
        +

        msg

        + +

        + string +

        +
        +

        The output message generated by the module.

        +

        Returned: always

        +

        Sample: "UserProfileProvider created successfully"

        +
        + + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Eike Waldt (@yeoldegrove) + + +.. Extra links + + +.. Parsing errors diff --git a/main/index.html b/main/index.html index fab3a31..90ed169 100644 --- a/main/index.html +++ b/main/index.html @@ -102,19 +102,45 @@
      • Ansible version compatibility
      • Installation
      • Usage
        • -
      • Configuration
      • Support
      • Release and Upgrade Notes
      • License
    • Plugin Index
    • Role Index