mirror of
https://github.com/ansible-middleware/keycloak.git
synced 2025-04-06 02:40:30 -07:00
|
|
||
|---|---|---|
| .. | ||
| _downloads/a0468922d38230cfdad1d445a6b10b9e | ||
| _sources | ||
| _static | ||
| plugins | ||
| roles | ||
| .buildinfo | ||
| CHANGELOG.html | ||
| developing.html | ||
| genindex.html | ||
| index.html | ||
| objects.inv | ||
| README.html | ||
| releasing.html | ||
| search.html | ||
| searchindex.js | ||
| testing.html | ||
<!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=e59714d7" />
<link rel="stylesheet" type="text/css" href="_static/antsibull-minimal.css" />
<link rel="stylesheet" type="text/css" href="_static/ansible-basic-sphinx-ext.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=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></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>
</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-playbook">Install Playbook</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>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#example-installation-command">Example installation command</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#configuration">Configuration</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#config-playbook">Config Playbook</a></li>
<li class="toctree-l3"><a class="reference internal" href="#example-configuration-command">Example configuration command</a></li>
</ul>
</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/workflows/CI/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.15.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><code class="docutils literal notranslate"><span class="pre">keycloak_quarkus</span></code>: role for installing keycloak (>= 19.0.0, quarkus based).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_realm</span></code>: role for configuring a realm, user federation(s), clients and users, in an installed service.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak</span></code>: role for installing legacy keycloak (<= 19.0, wildfly based).</p></li>
</ul>
<!--end roles_paths -->
</section>
</section>
<section id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Link to this heading"></a></h2>
<section id="install-playbook">
<h3>Install Playbook<a class="headerlink" href="#install-playbook" title="Link to this heading"></a></h3>
<!--start rhbk_playbook -->
<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 based on the defined variables (using most defaults).</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 keycloak legacy based on the defined variables (using most defaults).</p></li>
</ul>
<p>Both playbooks include the <code class="docutils literal notranslate"><span class="pre">keycloak</span></code> role, with different settings, as described in the following sections.</p>
<p>For full service configuration details, refer to the <a class="reference external" href="https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak/README.md">keycloak role README</a>.</p>
<!--end rhbk_playbook -->
<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>
<section id="example-installation-command">
<h3>Example installation command<a class="headerlink" href="#example-installation-command" title="Link to this heading"></a></h3>
<p>Execute the following command from the source root directory</p>
<div class="highlight-YAML+Jinja notranslate"><div class="highlight"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">ansible-playbook -i <ansible_hosts> -e @rhn-creds.yml playbooks/keycloak.yml -e keycloak_admin_password=<changeme></span>
</pre></div>
</div>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">keycloak_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="configuration">
<h2>Configuration<a class="headerlink" href="#configuration" title="Link to this heading"></a></h2>
<section id="config-playbook">
<h3>Config Playbook<a class="headerlink" href="#config-playbook" title="Link to this heading"></a></h3>
<!--start rhbk_realm_playbook -->
<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>
<!--end rhbk_realm_playbook -->
</section>
<section id="example-configuration-command">
<h3>Example configuration command<a class="headerlink" href="#example-configuration-command" title="Link to this heading"></a></h3>
<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_admin_password</span><span class="o">=</span><changeme><span class="w"> </span>-e<span class="w"> </span><span class="nv">keycloak_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_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</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 -->
<!--start support -->
<!--end support -->
</section>
</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 internal" href="#LICENSE"><span class="xref myst">LICENSE</span></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 2025, 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>