mirror of
https://github.com/ansible-middleware/keycloak.git
synced 2025-04-07 03:10:31 -07:00
| .. | ||
| _downloads/a0468922d38230cfdad1d445a6b10b9e | ||
| _sources | ||
| _static | ||
| roles | ||
| .buildinfo | ||
| developing.html | ||
| genindex.html | ||
| index.html | ||
| objects.inv | ||
| README.html | ||
| search.html | ||
| searchindex.js | ||
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<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" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/ansible-basic-sphinx-ext.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></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="Role Index" href="roles/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" />
<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></li>
<li class="toctree-l3"><a class="reference internal" href="#choosing-between-upstream-project-keycloak-and-red-hat-single-sign-on-rhsso">Choosing between upstream project (Keycloak) and Red Hat Single Sign-On (RHSSO)</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#install-upstream-keycloak-from-keycloak-releases">Install upstream (Keycloak) from keycloak releases</a></li>
<li class="toctree-l4"><a class="reference internal" href="#install-rhsso-from-the-red-hat-customer-support-portal">Install RHSSO from the Red Hat Customer Support Portal</a></li>
<li class="toctree-l4"><a class="reference internal" href="#install-from-controller-node-local-source">Install from controller node (local source)</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="#support">Support</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="roles/index.html">Role Index</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">Contributor’s Guidelines</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"></a> »</li>
<li>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="Permalink to this headline"></a></h1>
<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>
<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>.</p>
<!--start requires_ansible-->
<section id="ansible-version-compatibility">
<h2>Ansible version compatibility<a class="headerlink" href="#ansible-version-compatibility" title="Permalink to this headline"></a></h2>
<p>This collection has been tested against following Ansible versions: <strong>>=2.9.10</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="Permalink to this headline"></a></h2>
<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="Permalink to this headline"></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>
<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="w"></span>
<span class="nt">collections</span><span class="p">:</span><span class="w"></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><span class="w"></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>
</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>
</section>
<section id="included-roles">
<h3>Included roles<a class="headerlink" href="#included-roles" title="Permalink to this headline"></a></h3>
<ul class="simple">
<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 the service.</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>
</ul>
</section>
</section>
<section id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline"></a></h2>
<section id="install-playbook">
<h3>Install Playbook<a class="headerlink" href="#install-playbook" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><span class="xref myst"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak.yml</span></code></span> installs the upstream(Keycloak) based on the defined variables.</p></li>
<li><p><span class="xref myst"><code class="docutils literal notranslate"><span class="pre">playbooks/rhsso.yml</span></code></span> installs Red Hat Single Sign-On(RHSSO) based on defined variables.</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 <span class="xref myst">keycloak role README</span>.</p>
</section>
<section id="choosing-between-upstream-project-keycloak-and-red-hat-single-sign-on-rhsso">
<h3>Choosing between upstream project (Keycloak) and Red Hat Single Sign-On (RHSSO)<a class="headerlink" href="#choosing-between-upstream-project-keycloak-and-red-hat-single-sign-on-rhsso" title="Permalink to this headline"></a></h3>
<p>The general flag <code class="docutils literal notranslate"><span class="pre">keycloak_rhsso_enable</span></code> controls what to install between upstream (Keycloak, when <code class="docutils literal notranslate"><span class="pre">False</span></code>) or Red Hat Single Sign-On (when <code class="docutils literal notranslate"><span class="pre">True</span></code>).
The default value for the flag if <code class="docutils literal notranslate"><span class="pre">True</span></code> when Red Hat Network credentials are defined, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.</p>
<section id="install-upstream-keycloak-from-keycloak-releases">
<h4>Install upstream (Keycloak) from keycloak releases<a class="headerlink" href="#install-upstream-keycloak-from-keycloak-releases" title="Permalink to this headline"></a></h4>
<p>This is the default approach when RHN credentials are not defined. Keycloak is downloaded from keycloak builds (hosted on github.com) locally, and distributed to target nodes.</p>
</section>
<section id="install-rhsso-from-the-red-hat-customer-support-portal">
<h4>Install RHSSO from the Red Hat Customer Support Portal<a class="headerlink" href="#install-rhsso-from-the-red-hat-customer-support-portal" title="Permalink to this headline"></a></h4>
<p>Define the credentials as follows, and the default behaviour is to download a fresh archive of RHSSO on the controller node, then distribute to target nodes.</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">rhn_username</span><span class="p">:</span><span class="w"> </span><span class="s">'<customer_portal_username>'</span><span class="w"></span>
<span class="nt">rhn_password</span><span class="p">:</span><span class="w"> </span><span class="s">'<customer_portal_password>'</span><span class="w"></span>
<span class="c1"># (keycloak_rhsso_enable defaults to True)</span><span class="w"></span>
</pre></div>
</div>
</section>
<section id="install-from-controller-node-local-source">
<h4>Install from controller node (local source)<a class="headerlink" href="#install-from-controller-node-local-source" title="Permalink to this headline"></a></h4>
<p>Making the keycloak zip archive (or the RHSSO zip archive), available to the playbook repository root 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 matches the downloaded archive path, so 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><span class="w"></span>
</pre></div>
</div>
<p>And depending on <code class="docutils literal notranslate"><span class="pre">keycloak_rhsso_enable</span></code>:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">True</span></code>: install RHSSO using file rh-sso-x.y.z-server-dist.zip</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">False</span></code>: install keycloak using file keycloak-x.y.zip</p></li>
</ul>
</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="Permalink to this headline"></a></h4>
<p>For RHSSO:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">keycloak_rhsso_enable</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">keycloak_rhsso_download_url</span><span class="p">:</span><span class="w"> </span><span class="s">"https://<internal-nexus.private.net>/<path>/<to>/rh-sso-x.y.z-server-dist.zip"</span><span class="w"></span>
</pre></div>
</div>
<p>For keycloak:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">keycloak_rhsso_enable</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">False</span><span class="w"></span>
<span class="nt">keycloak_download_url</span><span class="p">:</span><span class="w"> </span><span class="s">"https://<internal-nexus.private.net>/<path>/<to>/keycloak-x.y.zip"</span><span class="w"></span>
</pre></div>
</div>
</section>
</section>
<section id="example-installation-command">
<h3>Example installation command<a class="headerlink" href="#example-installation-command" title="Permalink to this headline"></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><span class="w"></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="w"></span>
<span class="l l-Scalar l-Scalar-Plain">localhost ansible_connection=local</span><span class="w"></span>
</pre></div>
</div>
</li>
</ul>
</section>
</section>
<section id="configuration">
<h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline"></a></h2>
<section id="config-playbook">
<h3>Config Playbook<a class="headerlink" href="#config-playbook" title="Permalink to this headline"></a></h3>
<p><span class="xref myst"><code class="docutils literal notranslate"><span class="pre">playbooks/keycloak_realm.yml</span></code></span> creates or updates provided realm, user federation(s), client(s), client role(s) and client user(s).</p>
</section>
<section id="example-configuration-command">
<h3>Example configuration command<a class="headerlink" href="#example-configuration-command" title="Permalink to this headline"></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 -i <ansible_hosts> playbooks/keycloak_realm.yml -e <span class="nv">keycloak_admin_password</span><span class="o">=</span><changeme> -e <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="w"></span>
<span class="l l-Scalar l-Scalar-Plain">localhost ansible_connection=local</span><span class="w"></span>
</pre></div>
</div>
</li>
</ul>
<p>For full configuration details, refer to the <span class="xref myst">keycloak_realm role README</span>.</p>
</section>
</section>
<section id="support">
<h2>Support<a class="headerlink" href="#support" title="Permalink to this headline"></a></h2>
<p>Keycloak collection v1.0.0 is a Beta release and for <a class="reference external" href="https://access.redhat.com/support/offerings/techpreview">Technical Preview</a>. If you have any issues or questions related to collection, please don’t hesitate to contact us on Ansible-middleware-core@redhat.com or open an issue on https://github.com/ansible-middleware/keycloak/issues</p>
</section>
<section id="license">
<h2>License<a class="headerlink" href="#license" title="Permalink to this headline"></a></h2>
<p>Apache License v2.0 or later</p>
<p>See <span class="xref myst">LICENSE</span> to view the full text.</p>
</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="roles/index.html" class="btn btn-neutral float-right" title="Role 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 2022, 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>