mirror of
https://github.com/ansible-middleware/keycloak.git
synced 2025-04-06 10:50:31 -07:00
291 lines
No EOL
20 KiB
HTML
291 lines
No EOL
20 KiB
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> |