mirror of
https://github.com/ansible-middleware/keycloak.git
synced 2026-07-25 00:44:48 +00:00
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Ansible Collection - middleware_automation.keycloak — Keycloak Ansible Collection documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=41de9001" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<link rel="stylesheet" type="text/css" href="_static/antsibull-minimal.css" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Plugin Index" href="plugins/index.html" />
<link rel="prev" title="Welcome to Keycloak Collection documentation" href="index.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
Keycloak Ansible Collection
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">User documentation</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Ansible Collection - middleware_automation.keycloak</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#ansible-version-compatibility">Ansible version compatibility</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#installing-the-collection-from-ansible-galaxy">Installing the Collection from Ansible Galaxy</a></li>
<li class="toctree-l3"><a class="reference internal" href="#included-roles">Included roles</a></li>
<li class="toctree-l3"><a class="reference internal" href="#included-modules">Included modules</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#usage">Usage</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#install-keycloak">Install Keycloak</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#install-from-controller-node-offline">Install from controller node (offline)</a></li>
<li class="toctree-l4"><a class="reference internal" href="#install-from-alternate-sources-like-corporate-nexus-artifactory-proxy-etc">Install from alternate sources (like corporate Nexus, artifactory, proxy, etc)</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example-installation-command">Example installation command</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#configure-with-roles">Configure with roles</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#example-configuration-command">Example configuration command</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#configure-with-modules">Configure with modules</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#support">Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="#release-and-upgrade-notes">Release and Upgrade Notes</a></li>
<li class="toctree-l2"><a class="reference internal" href="#license">License</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="plugins/index.html">Plugin Index</a></li>
<li class="toctree-l1"><a class="reference internal" href="roles/index.html">Role Index</a></li>
<li class="toctree-l1"><a class="reference internal" href="CHANGELOG.html">Changelog</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="developing.html">Developing</a></li>
<li class="toctree-l1"><a class="reference internal" href="developing.html#contributor-s-guidelines">Contributor’s Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="releasing.html">Releasing</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Middleware collections</span></p>
<ul>
<li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/keycloak/main/">Keycloak / Red Hat Single Sign-On</a></li>
<li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/infinispan/main/">Infinispan / Red Hat Data Grid</a></li>
<li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/wildfly/main/">Wildfly / Red Hat JBoss EAP</a></li>
<li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/jws/main/">Tomcat / Red Hat JWS</a></li>
<li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/amq/main/">ActiveMQ / Red Hat AMQ Broker</a></li>
<li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/amq_streams/main/">Kafka / Red Hat AMQ Streams</a></li>
<li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/common/main/">Ansible Middleware utilities</a></li>
<li class="toctree-l1"><a class="reference external" href="https://ansible-middleware.github.io/ansible_collections_jcliff/main/">JCliff</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Keycloak Ansible Collection</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Ansible Collection - middleware_automation.keycloak</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/README.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="ansible-collection-middleware-automation-keycloak">
<h1>Ansible Collection - middleware_automation.keycloak<a class="headerlink" href="#ansible-collection-middleware-automation-keycloak" title="Link to this heading"></a></h1>
<!--start build_status -->
<p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/actions/workflows/ci.yml"><img alt="Build Status" src="https://github.com/ansible-middleware/keycloak/actions/workflows/ci.yml/badge.svg?branch=main" /></a></p>
<blockquote>
<div><p><strong><em>NOTE:</em> If you are Red Hat customer, install <code class="docutils literal notranslate"><span class="pre">redhat.rhbk</span></code> (for Red Hat Build of Keycloak) or <code class="docutils literal notranslate"><span class="pre">redhat.sso</span></code> (for Red Hat Single Sign-On) from <a class="reference external" href="https://console.redhat.com/ansible/ansible-dashboard">Automation Hub</a> as the certified version of this collection.</strong></p>
</div></blockquote>
<!--end build_status -->
<!--start description -->
<p>Collection to install and configure <a class="reference external" href="https://www.keycloak.org/">Keycloak</a> or <a class="reference external" href="https://access.redhat.com/products/red-hat-single-sign-on">Red Hat Single Sign-On</a> / <a class="reference external" href="https://access.redhat.com/products/red-hat-build-of-keycloak">Red Hat Build of Keycloak</a>.</p>
<!--end description -->
<!--start requires_ansible-->
<section id="ansible-version-compatibility">
<h2>Ansible version compatibility<a class="headerlink" href="#ansible-version-compatibility" title="Link to this heading"></a></h2>
<p>This collection has been tested against following Ansible versions: <strong>>=2.16.0</strong>.</p>
<p>Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions.</p>
<!--end requires_ansible-->
</section>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h2>
<!--start galaxy_download -->
<section id="installing-the-collection-from-ansible-galaxy">
<h3>Installing the Collection from Ansible Galaxy<a class="headerlink" href="#installing-the-collection-from-ansible-galaxy" title="Link to this heading"></a></h3>
<p>Before using the collection, you need to install it with the Ansible Galaxy CLI:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>ansible-galaxy collection install middleware_automation.keycloak
</pre></div>
</div>
<!--end galaxy_download -->
<p>You can also include it in a <code class="docutils literal notranslate"><span class="pre">requirements.yml</span></code> file and install it via <code class="docutils literal notranslate"><span class="pre">ansible-galaxy</span> <span class="pre">collection</span> <span class="pre">install</span> <span class="pre">-r</span> <span class="pre">requirements.yml</span></code>, using the format:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nn">---</span>
<span class="nt">collections</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">middleware_automation.keycloak</span>
</pre></div>
</div>
<p>The keycloak collection also depends on the following python packages to be present on the controller host:</p>
<ul class="simple">
<li><p>netaddr</p></li>
<li><p>lxml</p></li>
</ul>
<p>A requirement file is provided to install:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>pip install -r requirements.txt
</pre></div>
</div>
<!--start roles_paths -->
</section>
<section id="included-roles">
<h3>Included roles<a class="headerlink" href="#included-roles" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_quarkus/README.md"><code class="docutils literal notranslate"><span class="pre">keycloak_quarkus</span></code></a>: role for installing keycloak (>= 19.0.0, quarkus based).</p></li>
<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_realm/README.md"><code class="docutils literal notranslate"><span class="pre">keycloak_realm</span></code></a>: role for configuring a realm, user federation(s), clients and users, in an installed service.</p></li>
<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak/README.md"><code class="docutils literal notranslate"><span class="pre">keycloak</span></code></a>: role for installing legacy keycloak (<= 19.0, wildfly based).</p></li>
</ul>
<!--end roles_paths -->
</section>
<section id="included-modules">
<h3>Included modules<a class="headerlink" href="#included-modules" title="Link to this heading"></a></h3>
<p>All Keycloak administration modules from <code class="docutils literal notranslate"><span class="pre">community.general</span></code> are provided in this collection for Keycloak 17+ (Quarkus). Use <code class="docutils literal notranslate"><span class="pre">auth_keycloak_url</span></code> without the legacy <code class="docutils literal notranslate"><span class="pre">/auth</span></code> context path (for example <code class="docutils literal notranslate"><span class="pre">http://localhost:8080</span></code>). Set <code class="docutils literal notranslate"><span class="pre">keycloak_context</span></code> to <code class="docutils literal notranslate"><span class="pre">/auth</span></code> only when automating WildFly-based Keycloak with the <code class="docutils literal notranslate"><span class="pre">keycloak</span></code> role.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_authentication</span></code>: manage authentication flows and executions using Keycloak Admin REST API.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_authentication_flow</span></code>: manage custom authentication flows and flow executions.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_authentication_required_actions</span></code>: manage required actions available in realm authentication.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_authentication_v2</span></code>: manage authentication flows with newer Keycloak API handling.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_authz_authorization_scope</span></code>: manage authorization scopes for a client resource server.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_authz_custom_policy</span></code>: manage custom authorization policies for a client resource server.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_authz_permission</span></code>: manage authorization permissions for a client resource server.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_authz_permission_info</span></code>: retrieve authorization permission information for a client resource server.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_client</span></code>: manage Keycloak clients (create/update/delete).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_client_rolemapping</span></code>: manage client role mappings for users and groups.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_client_rolescope</span></code>: manage client role scope mappings.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_client_scope</span></code>: manage client scopes and protocol mappers (replaces <code class="docutils literal notranslate"><span class="pre">community.general.keycloak_clientscope</span></code>).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_client_scope_type</span></code>: manage default and optional client scope assignments.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_clientsecret_info</span></code>: retrieve client secret information.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_clientsecret_regenerate</span></code>: regenerate a client secret.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_clienttemplate</span></code>: manage legacy client templates.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_component</span></code>: manage realm components.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_component_info</span></code>: retrieve realm component information.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_group</span></code>: manage realm groups and subgroups.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_identity_provider</span></code>: manage identity provider instances and configuration.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_realm</span></code>: manage realms (create/update/delete).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_realm_info</span></code>: retrieve realm information.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_realm_key</span></code>: manage realm key providers.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_realm_keys_metadata_info</span></code>: retrieve realm keys metadata.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_realm_localization</span></code>: manage realm localization texts.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_realm_rolemapping</span></code>: manage realm role mappings for users and groups.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_role</span></code>: manage realm and client roles.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_user</span></code>: manage users (create/update/delete).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_user_execute_actions_email</span></code>: trigger execute-actions emails for users.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_user_federation</span></code>: manage user federation providers (for example LDAP/AD).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_user_rolemapping</span></code>: manage user role mappings.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_userprofile</span></code>: manage user profile configuration.</p></li>
</ul>
</section>
</section>
<section id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Link to this heading"></a></h2>
<p>The collection provides roles to install Keycloak and modules to manage realms, clients, users, and related settings via the <a class="reference external" href="https://www.keycloak.org/docs-api/latest/rest-api/index.html">Keycloak Admin REST API</a>.</p>
<p>For Quarkus-based Keycloak (17+), set <code class="docutils literal notranslate"><span class="pre">auth_keycloak_url</span></code> to the server root URL without the legacy <code class="docutils literal notranslate"><span class="pre">/auth</span></code> path, for example <code class="docutils literal notranslate"><span class="pre">http://localhost:8080</span></code>. When using the legacy <code class="docutils literal notranslate"><span class="pre">keycloak</span></code> role with WildFly-based Keycloak, set <code class="docutils literal notranslate"><span class="pre">keycloak_context</span></code> to <code class="docutils literal notranslate"><span class="pre">/auth</span></code> in the <code class="docutils literal notranslate"><span class="pre">keycloak_realm</span></code> role.</p>
<section id="install-keycloak">
<h3>Install Keycloak<a class="headerlink" href="#install-keycloak" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_quarkus.yml"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak_quarkus.yml</span></code></a> installs Keycloak >= 17 using the <code class="docutils literal notranslate"><span class="pre">keycloak_quarkus</span></code> role.</p></li>
<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak.yml"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak.yml</span></code></a> installs legacy Keycloak (<= 19) using the <code class="docutils literal notranslate"><span class="pre">keycloak</span></code> role.</p></li>
</ul>
<p>For full service configuration details, refer to the <a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_quarkus/README.md">keycloak_quarkus role README</a> or the <a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak/README.md">keycloak role README</a>.</p>
<section id="install-from-controller-node-offline">
<h4>Install from controller node (offline)<a class="headerlink" href="#install-from-controller-node-offline" title="Link to this heading"></a></h4>
<p>Making the keycloak zip archive available to the playbook working directory, and setting <code class="docutils literal notranslate"><span class="pre">keycloak_offline_install</span></code> to <code class="docutils literal notranslate"><span class="pre">true</span></code>, allows to skip
the download tasks. The local path for the archive does match the downloaded archive path, so that it is also used as a cache when multiple hosts are provisioned in a cluster.</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">keycloak_offline_install</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</pre></div>
</div>
<!--start rhn_credentials -->
<!--end rhn_credentials -->
</section>
<section id="install-from-alternate-sources-like-corporate-nexus-artifactory-proxy-etc">
<h4>Install from alternate sources (like corporate Nexus, artifactory, proxy, etc)<a class="headerlink" href="#install-from-alternate-sources-like-corporate-nexus-artifactory-proxy-etc" title="Link to this heading"></a></h4>
<p>It is possible to perform downloads from alternate sources, using the <code class="docutils literal notranslate"><span class="pre">keycloak_download_url</span></code> 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).</p>
</section>
<section id="example-installation-command">
<h4>Example installation command<a class="headerlink" href="#example-installation-command" title="Link to this heading"></a></h4>
<p>Execute the following command from the source root directory:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>ansible-playbook<span class="w"> </span>-i<span class="w"> </span><ansible_hosts><span class="w"> </span>playbooks/keycloak_quarkus.yml<span class="w"> </span>-e<span class="w"> </span><span class="nv">keycloak_quarkus_bootstrap_admin_password</span><span class="o">=</span><changeme>
</pre></div>
</div>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_quarkus_bootstrap_admin_password</span></code> password for the administration console user account.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ansible_hosts</span></code> is the inventory, below is an example inventory for deploying to localhost</p>
<div class="highlight-YAML+Jinja notranslate"><div class="highlight"><pre><span></span><span class="p p-Indicator">[</span><span class="nv">keycloak</span><span class="p p-Indicator">]</span>
<span class="l l-Scalar l-Scalar-Plain">localhost ansible_connection=local</span>
</pre></div>
</div>
</li>
</ul>
<p>Note: when deploying clustered configurations, all hosts belonging to the cluster must be present in <code class="docutils literal notranslate"><span class="pre">ansible_play_batch</span></code>; ie. they must be targeted by the same ansible-playbook execution.</p>
</section>
</section>
<section id="configure-with-roles">
<h3>Configure with roles<a class="headerlink" href="#configure-with-roles" title="Link to this heading"></a></h3>
<!--start rhbk_realm_playbook -->
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_realm.yml"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak_realm.yml</span></code></a> creates or updates provided realm, user federation(s), client(s), client role(s) and client user(s).</p></li>
</ul>
<!--end rhbk_realm_playbook -->
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_realm_client.yml"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak_realm_client.yml</span></code></a> creates a realm with clients, roles and users using the <code class="docutils literal notranslate"><span class="pre">keycloak_realm</span></code> role.</p></li>
<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_federation.yml"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak_federation.yml</span></code></a> configures user federation providers.</p></li>
</ul>
<section id="example-configuration-command">
<h4>Example configuration command<a class="headerlink" href="#example-configuration-command" title="Link to this heading"></a></h4>
<p>Execute the following command from the source root directory:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>ansible-playbook<span class="w"> </span>-i<span class="w"> </span><ansible_hosts><span class="w"> </span>playbooks/keycloak_realm.yml<span class="w"> </span>-e<span class="w"> </span><span class="nv">keycloak_realm_admin_password</span><span class="o">=</span><changeme><span class="w"> </span>-e<span class="w"> </span><span class="nv">keycloak_realm_realm</span><span class="o">=</span><span class="nb">test</span>
</pre></div>
</div>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_realm_admin_password</span></code> password for the administration console user account.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_realm_realm</span></code> name of the realm to be created/used.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ansible_hosts</span></code> is the inventory, below is an example inventory for deploying to localhost</p>
<div class="highlight-YAML+Jinja notranslate"><div class="highlight"><pre><span></span><span class="p p-Indicator">[</span><span class="nv">keycloak</span><span class="p p-Indicator">]</span>
<span class="l l-Scalar l-Scalar-Plain">localhost ansible_connection=local</span>
</pre></div>
</div>
</li>
</ul>
<!--start rhbk_realm_readme -->
<p>For full configuration details, refer to the <a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_realm/README.md">keycloak_realm role README</a>.</p>
<!--end rhbk_realm_readme -->
</section>
</section>
<section id="configure-with-modules">
<h3>Configure with modules<a class="headerlink" href="#configure-with-modules" title="Link to this heading"></a></h3>
<p>Module playbooks target an already running Keycloak instance. All modules use the <code class="docutils literal notranslate"><span class="pre">middleware_automation.keycloak</span></code> collection namespace.</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_client_scope.yml"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak_client_scope.yml</span></code></a> creates a client scope with protocol mappers using the <code class="docutils literal notranslate"><span class="pre">keycloak_client_scope</span></code> module.</p></li>
<li><p><a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_authentication_flow.yml"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak_authentication_flow.yml</span></code></a> creates a custom authentication flow with execution steps using the <code class="docutils literal notranslate"><span class="pre">keycloak_authentication_flow</span></code> module.</p></li>
</ul>
<p>Example task using shared authentication defaults:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">localhost</span>
<span class="w"> </span><span class="nt">module_defaults</span><span class="p">:</span>
<span class="w"> </span><span class="nt">group/middleware_automation.keycloak.keycloak</span><span class="p">:</span>
<span class="w"> </span><span class="nt">auth_keycloak_url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">http://localhost:8080</span>
<span class="w"> </span><span class="nt">auth_realm</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">master</span>
<span class="w"> </span><span class="nt">auth_username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">admin</span>
<span class="w"> </span><span class="nt">auth_password</span><span class="p">:</span><span class="w"> </span><span class="s">"{{</span><span class="nv"> </span><span class="s">keycloak_admin_password</span><span class="nv"> </span><span class="s">}}"</span>
<span class="w"> </span><span class="nt">tasks</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Create a user in a realm</span>
<span class="w"> </span><span class="nt">middleware_automation.keycloak.keycloak_user</span><span class="p">:</span>
<span class="w"> </span><span class="nt">realm</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">TestRealm</span>
<span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">testuser</span>
<span class="w"> </span><span class="nt">first_name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Test</span>
<span class="w"> </span><span class="nt">last_name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">User</span>
<span class="w"> </span><span class="nt">email</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">testuser@example.com</span>
<span class="w"> </span><span class="nt">enabled</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">present</span>
</pre></div>
</div>
<p>When migrating from <code class="docutils literal notranslate"><span class="pre">community.general</span></code>, replace the collection prefix in playbooks (for example <code class="docutils literal notranslate"><span class="pre">community.general.keycloak_user</span></code> becomes <code class="docutils literal notranslate"><span class="pre">middleware_automation.keycloak.keycloak_user</span></code>) and use <code class="docutils literal notranslate"><span class="pre">keycloak_client_scope</span></code> instead of <code class="docutils literal notranslate"><span class="pre">keycloak_clientscope</span></code>.</p>
</section>
</section>
<section id="support">
<h2>Support<a class="headerlink" href="#support" title="Link to this heading"></a></h2>
<!--start support -->
<p>For bug reports and feature requests, use <a class="reference external" href="https://github.com/ansible-middleware/keycloak/issues">GitHub Issues</a>.</p>
<!--end support -->
</section>
<section id="release-and-upgrade-notes">
<h2>Release and Upgrade Notes<a class="headerlink" href="#release-and-upgrade-notes" title="Link to this heading"></a></h2>
<p>For details on changes between versions, please see the <a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/CHANGELOG.rst">CHANGELOG</a> for this collection.</p>
</section>
<section id="license">
<h2>License<a class="headerlink" href="#license" title="Link to this heading"></a></h2>
<p>Apache License v2.0 or later</p>
<!--start license -->
<p>See <a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/LICENSE">LICENSE</a> to view the full text.</p>
<!--end license -->
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="index.html" class="btn btn-neutral float-left" title="Welcome to Keycloak Collection documentation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="plugins/index.html" class="btn btn-neutral float-right" title="Plugin Index" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2026, Red Hat, Inc..</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>