Google Git
Sign in
eclipse / gerrit / www.eclipse.org / kapua / bc3548d66c03be1313e197f6edb5fdd4b4de6b40 / . / docs / 1.5.0 / developer-guide / en / sso.html
blob: fa2d6d3c2177eae38bc2806eab944fe1e12454e8 [file] [log] [blame]
<!DOCTYPE HTML>
<html lang="" >
<head>
<meta charset="UTF-8">
<title>Single sign-on · Eclipse Kapua™ Developer Guide</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="description" content="">
<meta name="generator" content="HonKit 3.6.20">
<link rel="stylesheet" href="gitbook/style.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-hints/plugin-hints.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-search/search.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css">
<meta name="HandheldFriendly" content="true"/>
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png">
<link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon">
<link rel="next" href="database.html" />
</head>
<body>
<div class="book honkit-cloak">
<div class="book-summary">
<div id="book-search-input" role="search">
<input type="text" placeholder="Type to search" />
</div>
<nav role="navigation">
<ul class="summary">
<li class="chapter " data-level="1.1" data-path="./">
<a href="./">
Introduction
</a>
</li>
<li class="chapter " data-level="1.2" data-path="building.html">
<a href="building.html">
Building
</a>
<ul class="articles">
<li class="chapter " data-level="1.2.1" data-path="building.html">
<a href="building.html#kapua">
Kapua
</a>
</li>
<li class="chapter " data-level="1.2.2" data-path="building.html">
<a href="building.html#documentation">
Documentation
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="1.3" data-path="running.html">
<a href="running.html">
Running
</a>
<ul class="articles">
<li class="chapter " data-level="1.3.1" data-path="running.html">
<a href="running.html#docker-containers">
Docker
</a>
</li>
<li class="chapter " data-level="1.3.2" data-path="running.html">
<a href="running.html#openshift">
OpenShift
</a>
</li>
<li class="chapter " data-level="1.3.3" data-path="running.html">
<a href="running.html#vagrant">
Vagrant
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="1.4" data-path="ide.html">
<a href="ide.html">
Setting up an IDE
</a>
<ul class="articles">
<li class="chapter " data-level="1.4.1" data-path="ide.html">
<a href="ide.html#eclipse">
Eclipse IDE
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="1.5" >
<span>
Configuration
</span>
<ul class="articles">
<li class="chapter active" data-level="1.5.1" data-path="sso.html">
<a href="sso.html">
Single sign-on
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="1.6" data-path="database.html">
<a href="database.html">
Working with database
</a>
</li>
<li class="chapter " data-level="1.7" data-path="client.html">
<a href="client.html">
Client generation
</a>
</li>
<li class="chapter " data-level="1.8" data-path="qa.html">
<a href="qa.html">
QA process
</a>
</li>
<li class="divider"></li>
<li>
<a href="https://github.com/honkit/honkit" target="blank" class="gitbook-link">
Published with HonKit
</a>
</li>
</ul>
</nav>
</div>
<div class="book-body">
<div class="body-inner">
<div class="book-header" role="navigation">
<!-- Title -->
<h1>
<i class="fa fa-circle-o-notch fa-spin"></i>
<a href="." >Single sign-on</a>
</h1>
</div>
<div class="page-wrapper" tabindex="-1" role="main">
<div class="page-inner">
<div id="book-search-results">
<div class="search-noresults">
<section class="normal markdown-section">
<h1 id="single-sign-on-sso">Single sign-on (SSO)</h1>
<p>This section describes the single sign-on integration of Eclipse Kapua. Our single sign-on solution is based on the
<a href="https://openid.net/connect/" target="_blank">OpenID Connect</a> identity layer, on top of the <a href="https://oauth.net/2/" target="_blank">OAuth 2.0</a> authorization framework.
Please note that the OpenID Connect provider is unique for the same Kapua instance, thus it is common to all the accounts in the instance.</p>
<p>In this document we first describe how to enable SSO on Kapua. In a second step we present two examples based on the Keycloak Authentication Server,
using Docker and OpenShift.</p>
<h2 id="enabling-single-sign-on">Enabling single sign-on</h2>
<p>In order to enable single sign-on you will need to select an OpenID provider.
You can do this using the configuration property <code>sso.openid.provider</code>.
Currently, there are two default providers in Kapua.
However, additional providers can be added to Kapua by using the Java service loader framework.
The current default providers are:</p>
<ul>
<li><code>generic</code> – A generic OpenID Connect provider</li>
<li><code>keycloak</code> – An OpenID Connect provider based on Keycloak&apos;s configuration patterns</li>
</ul>
<p>Each provider will require additional configuration options. But there is a set of common configuration
options:</p>
<ul>
<li><strong><code>sso.openid.client.id</code></strong> : the &quot;client id&quot; used when communicating with the OpenID Connect server.
This represents also the JWT audience to search for in the OpenID Connect ID Token
(for more information see <a href="https://openid.net/specs/openid-connect-core-1_0.html#IDToken" target="_blank">here</a> )</li>
<li><strong><code>sso.openid.client.secret</code> (optional)</strong> : the &quot;client secret&quot; used when communicating with the OpenID Connect server.</li>
<li><strong><code>sso.openid.conf.path</code> (optional)</strong> : to provide a custom OpenID well-known suffix (the default one is <code>.well-known/openid-configuration</code> and
it&apos;s attached as suffix to the issuer).</li>
<li><strong><code>sso.openid.jwt_processor_timeout</code> (optional)</strong> : the JwtProcessor expiration time (the default value is 1 hour).</li>
</ul>
<p>It is also necessary to configure the Web Console external endpoint address.</p>
<ul>
<li><strong><code>console.sso.openid.home.uri</code></strong> : the URL to the web console, e.g. <code>http://localhost:8080</code></li>
</ul>
<p>The SSO Login will be available in the form of a dedicated button on the Kapua login page
(the button can be enabled through the configuration option <code>sso.openid.provider</code>).</p>
<h3 id="generic-provider">Generic provider</h3>
<p>The generic provider configuration values are retrieved through the <code>well-known</code> OpenID configuration document provided by the OpenID Provider
(see the official <a href="https://openid.net/specs/openid-connect-discovery-1_0.html" target="_blank">OpenID Connect Discovery specification</a> for further information).
The <code>issuer</code> is the only required parameter. However, custom parameters can be added through the following properties, and are used in case the automatic
configuration through the <code>well-known</code> document fails.
The required values are specific to your OpenID Connect solution, please use its documentation to look up the required values:</p>
<ul>
<li><strong><code>sso.openid.generic.jwt.issuer.allowed</code></strong> : the base URL to the OpenID server provider.</li>
<li><strong><code>sso.openid.generic.jwt.audience.allowed</code></strong> : the JWT audience.</li>
<li><strong><code>sso.openid.generic.server.endpoint.auth</code> (optional)</strong> : the endpoint URL to the authentication API.</li>
<li><strong><code>sso.openid.generic.server.endpoint.logout</code>(optional)</strong> : the logout endpoint of the OpenID provider.</li>
<li><strong><code>sso.openid.generic.server.endpoint.token</code> (optional)</strong> : the endpoint URL to the token API.</li>
</ul>
<p>Note that these properties, in combination with the ones defined in the previous paragraph,
can be set via environment variables thanks to the <code>run-console</code> bash script included in the Console docker container.
Please refer to the <a href="assembly/README.md">assembly module README file</a> for detailed information about those properties.</p>
<h4 id="note-about-client-id-and-audience-values">Note about &apos;client id&apos; and &apos;audience&apos; values</h4>
<p>Properties <code>sso.openid.client.id</code> and <code>sso.openid.generic.jwt.audience.allowed</code> (the second property is used only for the <code>generic</code> provider)
basically represent the same value.
More precisely, <code>sso.openid.client.id</code> is used as parameter in the requests to the OpenID Provider, while <code>sso.openid.generic.jwt.audience.allowed</code> is used by
the <code>JwtProcessor</code> in order to validate the token received from the OpenID Provider. These two should correspond to the same <code>clientId</code>.</p>
<p>According to the official OpenID Connect specification (see <a href="https://openid.net/specs/openid-connect-core-1_0.html#IDToken" target="_blank">here</a> and
<a href="https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation" target="_blank">here</a>), the <code>audience</code> contains a list of allowed <code>client_id</code>.
The token can contain a list of audiences (described by the <code>aud</code> claim).
When the token is received, we need to validate that the audience contains the <code>client_id</code> corresponding to the Kapua Console.
Only one <code>client_id</code> corresponds to the Kapua Console (if multiple client_ids are present in the audience, they correspond to other clients).</p>
<p>However, some OpenID Provider implementations are using different values between clientId and audience, thus the only way to make them work is to use two
different values for these properties (also, please note that the <code>generic-provider</code> should be the most &apos;permissive&apos; provider). </p>
<h3 id="keycloak-provider">Keycloak provider</h3>
<p>The Keycloak provider can be configured using the following configuration parameters:</p>
<ul>
<li><strong><code>sso.openid.keycloak.uri</code></strong> : the base URL to the Keycloak server.</li>
<li><strong><code>sso.openid.keycloak.realm</code></strong> : the name of the realm to use.</li>
</ul>
<p>Note that the <em>auth</em> and <em>token</em> endpoints are automatically computed by the Keycloak provider.
For more information about Keycloak, see the <a href="http://www.keycloak.org/documentation.html" target="_blank">Keycloak Documentation</a>.</p>
<p>Similarly to the &apos;generic&apos; provider, these properties, in combination with the common properties defined previously,
can be set via environment variables thanks to the <code>run-console</code> bash script included in the Console docker container.
Please refer to the <a href="assembly/README.md">assembly module README file</a> for detailed information about these environment variables.</p>
<h3 id="enabling-users-to-sso">Enabling users to SSO</h3>
<p>In order to enable a user to login through an OpenID provider, the user must first be created on the OpenID
Connect server (e.g. using Keycloak, on the Keycloak Admin Console).
Secondly, the user can be added to Kapua.
Such user differs from a &apos;normal&apos; one for its type (which is <code>EXTERNAL</code>, while a normal user is <code>INTERNAL</code>) and for
not having any credentials (since his credentials are stored in the OpenID Provider).</p>
<p>Currently there are three methods to register an external user in Kapua:
using the <em>SimpleRegistrationProcessor</em> , using <em>REST API</em> or using the <em>console</em>.</p>
<h4 id="insert-the-user-through-the-simpleregistrationprocessor-module">Insert the user through the SimpleRegistrationProcessor module</h4>
<p>This module allows one to automatically create the user in Kapua at the first log-in attempt using the SSO.
More precisely, two users are created: an external user without credentials, representing the SSO user, and an internal
user with credentials, representing a gateway user.
Both users are placed under a new account with the same name of the SSO user.
If a user with the same name already exists in Kapua, the registration process will fail,
and the user is simply logged in.</p>
<p><strong>WARNING</strong>: The SimpleRegistrationProcessor is intended to be used only as a <em>Proof-of-Concept</em> and should not be
used in a real environment.
For instance, the credentials provided for the gateway user are hardcoded in the SimpleRegistrationProcessor code.
Note however that the SimpleRegistrationProcessor is disabled by default.
In order to enable it, the configuration option <strong><code>authentication.registration.service.enabled</code></strong> should be provided
with value <code>true</code>.</p>
<h4 id="insert-the-user-through-rest-api">Insert the user through REST API</h4>
<p>After getting the session token using an authentication REST API, a user can be inserted using<br><a href="https://www.eclipse.org/kapua/docs/api/index.html?version=1.0.0#/Users/userCreate" target="_blank">userCreate</a>.
It is mandatory to provide the following attributes: </p>
<ul>
<li><strong><code>scopeId</code></strong>: the scope id to which the user will belong in Kapua;</li>
<li><strong><code>name</code></strong>: represents the name in the OpenID Provider;</li>
<li><strong><code>userType</code></strong>: must always be set as <strong><em>EXTERNAL</em></strong>;</li>
<li><strong><code>externalId</code></strong>: represents the unique ID on the OpenID Provider.</li>
</ul>
<h4 id="insert-the-user-through-the-console">Insert the user through the Console</h4>
<p>External users can be inserted through the <em>Users</em> module on the Console.
Log in with administrator credentials in order to add a user.</p>
<ol>
<li>Add the new user through the &quot;Add&quot; button.</li>
<li>The Add dialog allows to choose between an &quot;Internal user&quot; and an &quot;External user&quot;;
choose the latter in order to add an external one.</li>
<li>Insert the Username and the External Id; all the other fields are optional.</li>
</ol>
<p>An external user can also be modified through the button &quot;Edit&quot;
(please note that the &quot;Username&quot; and &quot;External Id&quot; fields are not modifiable).
Note that the user has no assigned roles. In order to add a &quot;Role&quot;, use the &quot;Assign&quot; button of the &quot;Roles&quot; tab.
Note also that the external user has no &quot;Credentials&quot; at all, since the credentials are established and stored in
the external Provider.</p>
<p>Enabling the sso also allows one to see the User Type and, in case it is an external user, the user External Id in the
&quot;Description&quot; tab.</p>
<h3 id="logging-out">Logging out</h3>
<p>If the SSO is enabled, logging out from Kapua also logs out from the external OpenID provider, invalidating the OpenID
Connect session.
This is implemented following the OpenID Connect specification for the
<a href="https://openid.net/specs/openid-connect-session-1_0.html#RPLogout" target="_blank">Relying Party Logout</a>.
Note that logging out from the OpenID provider is also possible through the provider OpenID logout endpoint,
but the user will remain logged into Kapua until also the logout from Kapua is performed.</p>
<p>The OpenID Connect logout can be disabled by setting the <code>console.sso.openid.user.logout.enabled</code> and <code>console.sso.openid.session_listener.logout.enabled</code>
properties to <code>false</code> (these properties are always set to <code>true</code> by default). The first property allows disabling the user-initiated logout, while the
second one allows disabling the <code>HttpSessionListener</code> managed logout (see class <code>OpenIDLogoutListener</code>), which is triggered at session invalidation. Be careful
if you choose to disable the OpenID logout, since this will allow the user to login again into the Kapua Console without the need to provide any credentials.</p>
<h2 id="keycloak-example-docker-based">Keycloak Example (Docker based)</h2>
<p>We detail here the steps to run an OpenID Keycloak provider.
The example described here makes use of a Keycloak Server Docker image
(see <a href="https://hub.docker.com/r/jboss/keycloak/" target="_blank">here</a> for more details). </p>
<h3 id="installing-the-keycloak-server-docker-image">Installing the Keycloak Server (Docker image)</h3>
<p>In order to deploy automatically the Keycloak image, is sufficient to use the <code>sso-docker-deploy.sh</code>script inside the
<code>sso</code> subdirectory of the docker deployment scripts. In such a way the environment is ready to be used without the need
for further configuration. </p>
<p>However, if you want to use a stand alone Keycloak image, please follow the instruction below in order to configure it.</p>
<h4 id="manual-installation-of-the-keycloak-server">Manual installation of the Keycloak server.</h4>
<p>In order to download and install the image, run <code>docker pull jboss/keycloak</code> on a bash terminal.
Then, run <code>docker run -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -p 9090:8080 jboss/keycloak</code> to start the
docker container, setting up the &quot;<em>admin</em>&quot; user (with &quot;<em>admin</em>&quot; as password).
The Keycloak Server Admin Console will be available at the following URL: <em>http://<keycloak-ip-address>:9090/</keycloak-ip-address></em>.</p>
<h4 id="ssl-configuration">SSL configuration</h4>
<p>The Keycloak provider can be configured to use SSL, which is enabled by setting the 9443 port for the <code>KEYCLOAK_URL</code>
in the <code>sso-docker-common.sh</code> file. A self-signed certificate and a key are produced through <code>sso-docker-deploy.sh</code>
script and passed via the volume based on the <code>./certs:/etc/x509/https</code> directory.
The script also installs the certificate in the Kapua Console docker image (which is tagged with the &apos;sso&apos; tag).</p>
<p><strong>WARNING</strong>: This SSL configuration is intended to be used only for testing purposes and should not be used in a
production environment. If you want to use Keycloak in a production environment and provide your own TLS certificate,
please refer to the official
<a href="https://www.keycloak.org/docs/latest/server_installation/#_setting_up_ssl" target="_blank">Keycloak documentation</a>.</p>
<h3 id="manually-configuring-the-keycloak-server">Manually configuring the Keycloak Server</h3>
<p>The Keycloak instance provided with the docker deployment is already configured with a dedicated
&quot;Kapua&quot; realm and a client when using the script <code>sso-docker-deploy.sh</code> in the subdirectory <code>sso</code>.</p>
<p>However, if you already have a running Keycloak instance, you can follow the instructions below in order to configure
it manually.
Open the Keycloak Admin Console on your preferred browser and follow the steps below in order to configure it.</p>
<ol>
<li>Create a new realm on Keycloak, call it &quot;<em>kapua</em>&quot;</li>
<li>Create a new client for this realm, call it &quot;<em>console</em>&quot; (this name represents the &quot;Client ID&quot;).</li>
<li>Configure the client &quot;Settings&quot; tab as follows: <ul>
<li>Client Protocol : &quot;<em>openid-connect</em>&quot;</li>
<li>Access : &quot;<em>public</em>&quot;</li>
<li>Standard Flow Enabled : <em>ON</em></li>
<li>Direct Access Grants Enabled : <em>ON</em></li>
<li>Valid Redirect URIs : <em><a href="http://localhost:8080/*" target="_blank">http://localhost:8080/*</a></em> (use your IP address in place of localhost)</li>
<li>Base URL : <em><a href="http://localhost:8080/" target="_blank">http://localhost:8080/</a></em></li>
</ul>
</li>
<li>Under the &quot;Mappers&quot; tab, create a new mapper called &quot;console&quot; with the following parameters:<ul>
<li>Name : &quot;<em>console</em>&quot;</li>
<li>Mapper Type : &quot;<em>Audience</em>&quot;</li>
<li>Included Custom Audience : &quot;<em>console</em>&quot;</li>
<li>Add to access token : <em>ON</em></li>
</ul>
</li>
<li>On the &quot;Realm Settings&quot;, under the &quot;Tokens&quot; tab, set &quot;Access Token Lifespan&quot; to 10 minutes (the default time is too
short)</li>
</ol>
<h3 id="configuring-kapua-to-use-sso-with-the-keycloak-server">Configuring Kapua to use SSO with the Keycloak Server</h3>
<p>The Kapua console docker image is already configured and deployed in docker without further configuration using the
<code>sso-docker-deploy.sh</code> script in the subdirectory <code>sso</code>.</p>
<p>If you need to configure it manually, the following properties must be passed (as VM options) in order to set up the SSO
on Kapua using Keycloak (you can login using the default <code>admin</code> user with <code>admin</code> password):</p>
<ul>
<li><code>sso.openid.provider=keycloak</code> : to set Keycloak as OpenID provider</li>
<li><code>sso.openid.keycloak.realm=kapua</code> : the Keycloak Realm (we are using the &quot;kapua&quot; realm)</li>
<li><code>sso.openid.keycloak.uri=http://&lt;Keycloak-IP-address&gt;:9090</code> : the Keycloak Server URI
(use <code>https://&lt;Keycloak-IP-address&gt;:9443</code> in case TLS is enabled - see below for further details)</li>
<li><code>sso.openid.client.id=console</code> : the OpenID Client ID (the one set on Keycloak)</li>
<li><code>console.sso.openid.home.uri=http://localhost:8080</code> : the Kapua web console URI </li>
</ul>
<p>If you need to start the console docker container alone, it is sufficient to provide the following docker environment
variables (these will automatically set up the configuration properties described above):</p>
<ul>
<li><code>KEYCLOAK_URL=http://&lt;Keycloak-IP-address&gt;:9090</code> : the Keycloak Server URI
(use <code>https://&lt;Keycloak-IP-address&gt;:9443</code> in case TLS is enabled - see below for further details)</li>
<li><code>KAPUA_CONSOLE_URL=http://localhost:8080</code> : the Kapua web console URI</li>
</ul>
<p>When using <code>docker-compose</code>, these two variables are bound through the <code>docker-compose.yaml</code> file.
Note that even if the Keycloak server is running locally on a docker container, it is recommended to use your machine
IP address instead of &apos;localhost&apos;, since this one can be misinterpreted by docker as the &apos;localhost&apos; of the container
in which the Kapua component or Keycloak are running (this is automatically done through the <code>sso-docker-deploy.sh</code>
script). </p>
<p>Please refer to the <a href="assembly/README.md">assembly module README file</a> for detailed information about the Console docker container
and related environment variables.</p>
<h3 id="setting-up-a-user-on-the-keycloak-server">Setting Up a user on the Keycloak server</h3>
<p>A test user is already created inside the Keycloak server, with username <code>sso-user</code> and password <code>sso-password</code>.
The ID assigned by Keycloak must be used as External ID on the Kapua side (see the next section).</p>
<p>If you want to add a new user, please follow the instructions below (remember to use the <code>admin</code> user with <code>admin</code>
password to log in):</p>
<ol>
<li>From the &quot;Users&quot; tab on the left menu, click on &quot;Add user&quot;</li>
<li>Configure the user as follows:<ul>
<li>Username : e.g. &quot;<em>alice</em>&quot;</li>
<li>Email : e.g. &quot;<em>alice@heremailprovider.com</em>&quot;</li>
<li>User Enabled : <em>ON</em></li>
</ul>
</li>
<li>Configure the user credentials under the &quot;Credentials&quot; tab</li>
</ol>
<p>Note that the user must have an email set in the OpenID Provider server, otherwise the creation on Kapua through the
SimpleRegistrationProcessor will fail. It is also possible to use the &quot;<em>admin</em>&quot; or the &quot;<em>sso-user</em>&quot; the users to log in
(remind to add an email address). </p>
<h3 id="setting-up-a-user-on-kapua">Setting Up a user on Kapua</h3>
<p>To add a new user in Kapua, it is sufficient to add it through the console as described in the
<a href="#insert-the-user-through-the-console">Insert the user through the Console</a> section.
If you want to use the SimpleRegistrationProcessor or the REST API, please follow the examples below.</p>
<p>Using the SimpleRegistrationProcessor, the user &quot;<em>alice</em>&quot; in Keycloak will generate &quot;<em>alice</em>&quot;
and &quot;<em>alice-broker</em>&quot; in Kapua, in a dedicated &quot;<em>alice</em>&quot; account.</p>
<p>Using the userCreate REST API with the following body (using the <em>scopeId</em> of the desired account
and the ID of the user &quot;<em>admin</em>&quot; in Keycloak as <em>externalId</em>):</p>
<pre><code>{
&quot;scopeId&quot;: &quot;...&quot;,
&quot;name&quot;: &quot;admin&quot;,
&quot;userType&quot;: &quot;EXTERNAL&quot;,
&quot;externalId&quot; : &quot;5726876c-....&quot;
}
</code></pre><p>will create the &quot;<em>admin</em>&quot; user without the need of the SimpleRegistrationProcessor.</p>
<h3 id="keycloak-logout-endpoint">Keycloak logout endpoint</h3>
<p>Logging out from the Keycloak provider is possible through the Keycloak OpenID Connect logout endpoint: </p>
<p><code>{sso.openid.keycloak.uri}/auth/realms/{realm_name}/protocol/openid-connect/logout</code></p>
<p>In our example the endpoint is the following: </p>
<p><code>http://&lt;Keycloak-IP-address&gt;:9090/auth/realms/kapua/protocol/openid-connect/logout</code></p>
<h2 id="keycloak-example-openshift-based">Keycloak Example (OpenShift based)</h2>
<p>This project provides a template to bootstrap single sign-on based on <a href="http://keycloak.org" target="_blank">Keycloak</a>.
The scripts for this are located in the directory <code>kapua/deployment/openshift/sso</code>
(please refer to <code>kapua/deployment/minishift/sso</code> if you are using Minishift).</p>
<p>Assuming you have already installed Kapua into OpenShift, it is possible to run the script <code>deploy</code>, which
will create a new build and deployment configuration in OpenShift. This is based on the official Keycloak Docker
image <code>jboss/keycloak</code>, adding a few steps for initial provisioning.</p>
<p><div class="alert alert-danger hints-alert"><div class="hints-icon"><i class="fa fa-exclamation-circle"></i></div><div class="hints-container"><p>The default setup uses an ephemeral storage. So re-starting the Keycloak pod will delete the configuration unless
you re-configure the setup with a persistent volume.</p>
</div></div> </p>
<p>After the build and deployment configuration has been created, the script will also re-configure the Kapua OpenShift
project to use the newly created Keycloak instance. This is done by calling the script <code>activate</code>.
The <code>activate</code> script can be called at a later time to re-configure Kapua (e.g. when re-installing Kapua).</p>
<p>Both scripts (<code>deploy</code> and <code>activate</code>) require both Kapua and Keycloak URLs.
Keycloak requires the Kapua web console URL in order to allow requests from this source,
while Kapua requires the Keycloak URL in order to forward requests to Keycloak.
The URLs are being constructed from OpenShift routes, which are configured for both Kapua and Keycloak.
However this requires that Kapua is set up before Keycloak and that the <code>activate</code> script can only be called after
the <code>deploy</code> script has been successfully run.</p>
<p>Please refer to the <a href="#keycloak-example-docker-based">Keycloak Example (Docker based)</a> section for the user creation,
or follow the next section in order to perform email-based user registration.</p>
<h3 id="email-server-based-user-registration">Email-server based user registration</h3>
<p>For this configuration to work, you will need some existing SMTP server which is capable of sending e-mails.
This is required so that Keycloak can send user verification and password recovery e-mails. If you don&apos;t have
and local SMTP server it is also possible to use some cloud based service like Mailgun, SendGrid or any other
provider.</p>
<p>The deployment is triggered by running the <code>deploy</code> script with a set of environment variables. Assuming you
are using <code>bash</code> as shell, this can be done like this:</p>
<pre><code>SMTP_HOST=smtp.server.org SMTP_USER=user SMTP_PASSWORD=secret SMTP_FROM=sender@my.domain ./deploy
</code></pre><p>The following environment variables are being used:</p>
<ul>
<li><strong><code>SMTP_HOST</code> (required)</strong> : The host name or IP address of the SMTP server.</li>
<li><strong><code>SMTP_PORT</code> (optional)</strong> : The port number of the SMTP service.</li>
<li><strong><code>SMTP_FROM</code> (required)</strong> : The sender e-mail used in the e-mail.</li>
<li><strong><code>SMTP_USER</code> (required)</strong> : The user name used to authenticate with the SMTP server.</li>
<li><strong><code>SMTP_PASSWORD</code> (required)</strong> : The password used to authenticate with the SMTP server.</li>
<li><strong><code>SMTP_ENABLE_SSL</code> (optional)</strong> : If SSL should be used instead of STARTTLS.</li>
<li><strong><code>KEYCLOAK_ADMIN_PASSWORD</code> (optional)</strong> : The password which will be assigned to the Keycloak admin user.
The default is to generate a password.</li>
</ul>
</section>
</div>
<div class="search-results">
<div class="has-results">
<h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
<ul class="search-results-list"></ul>
</div>
<div class="no-results">
<h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
</div>
</div>
</div>
</div>
</div>
</div>
<a href="database.html" class="navigation navigation-next navigation-unique" aria-label="Next page: Working with database">
<i class="fa fa-angle-right"></i>
</a>
</div>
<script>
var gitbook = gitbook || [];
gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"Single sign-on","level":"1.5.1","depth":2,"next":{"title":"Working with database","level":"1.6","depth":1,"path":"database.md","ref":"database.md","articles":[]},"previous":{"title":"Configuration","level":"1.5","depth":1,"ref":"","articles":[{"title":"Single sign-on","level":"1.5.1","depth":2,"path":"sso.md","ref":"sso.md","articles":[]}]},"dir":"ltr"},"config":{"plugins":["hints"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"hints":{"info":"fa fa-info-circle","tip":"fa fa-mortar-board","danger":"fa fa-exclamation-circle","working":"fa fa-wrench"},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"github":"eclipse/kapua","theme":"default","githubHost":"https://github.com/","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56},"embedFonts":false},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Eclipse Kapua™ Developer Guide","links":{"home":"http://eclipse.org/kapua"},"gitbook":"3.x.x","description":"Eclipse Kapua™ Developer Guide"},"file":{"path":"sso.md","mtime":"2021-07-20T08:57:45.186Z","type":"markdown"},"gitbook":{"version":"3.6.20","time":"2021-07-20T08:58:19.688Z"},"basePath":".","book":{"language":""}});
});
</script>
</div>
<noscript>
<style>
.honkit-cloak {
display: block !important;
}
</style>
</noscript>
<script>
// Restore sidebar state as critical path for prevent layout shift
function __init__getSidebarState(defaultValue){
var baseKey = "";
var key = baseKey + ":sidebar";
try {
var value = localStorage[key];
if (value === undefined) {
return defaultValue;
}
var parsed = JSON.parse(value);
return parsed == null ? defaultValue : parsed;
} catch (e) {
return defaultValue;
}
}
function __init__restoreLastSidebarState() {
var isMobile = window.matchMedia("(max-width: 600px)").matches;
if (isMobile) {
// Init last state if not mobile
return;
}
var sidebarState = __init__getSidebarState(true);
var book = document.querySelector(".book");
// Show sidebar if it enabled
if (sidebarState && book) {
book.classList.add("without-animation", "with-summary");
}
}
try {
__init__restoreLastSidebarState();
} finally {
var book = document.querySelector(".book");
book.classList.remove("honkit-cloak");
}
</script>
<script src="gitbook/gitbook.js"></script>
<script src="gitbook/theme.js"></script>
<script src="gitbook/gitbook-plugin-search/search-engine.js"></script>
<script src="gitbook/gitbook-plugin-search/search.js"></script>
<script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script>
<script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script>
<script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>
</body>
</html>