| |
| <!DOCTYPE HTML> |
| <html lang="" > |
| <head> |
| <meta charset="UTF-8"> |
| <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> |
| <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="GitBook 3.2.2"> |
| |
| |
| |
| |
| <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"> |
| <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://www.gitbook.com" target="blank" class="gitbook-link"> |
| Published with GitBook |
| </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 option <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'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 "client id" 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 "client secret" used when communicating with the OpenID Connect server.</li> |
| <li><strong><code>sso.openid.conf.wellknown.path</code> (optional)</strong> : to provide a custom OpenID well-known suffix (the default one is <code>.well-known/openid-configuration</code> and |
| it'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.generic.openid.jwt.issuer.allowed</code></strong> : the base URL to the OpenID server provider.</li> |
| <li><strong><code>sso.generic.openid.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> |
| <h4 id="note-about-client-id-and-audience-values">Note about 'client id' and 'audience' 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 'permissive' 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.</p> |
| <p>For more information see the <a href="http://www.keycloak.org/documentation.html" target="_blank">Keycloak Documentation</a>.</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 'normal' 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 "Add" button.</li> |
| <li>The Add dialog allows to choose between an "Internal user" and an "External user"; |
| 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 "Edit" |
| (please note that the "Username" and "External Id" fields are not modifiable). |
| Note that the user has no assigned roles. In order to add a "Role", use the "Assign" button of the "Roles" tab. |
| Note also that the external user has no "Credentials" 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 |
| "Description" 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 "<em>admin</em>" user (with "<em>admin</em>" 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 'sso' 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 |
| "Kapua" 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 "<em>kapua</em>"</li> |
| <li>Create a new client for this realm, call it "<em>console</em>" (this name represents the "Client ID").</li> |
| <li>Configure the client "Settings" tab as follows: <ul> |
| <li>Client Protocol : "<em>openid-connect</em>"</li> |
| <li>Access : "<em>public</em>"</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> (user 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 "Mappers" tab, create a new mapper called "console" with the following parameters:<ul> |
| <li>Name : "<em>console</em>"</li> |
| <li>Mapper Type : "<em>Audience</em>"</li> |
| <li>Included Custom Audience : "<em>console</em>"</li> |
| <li>Add to access token : <em>ON</em></li> |
| </ul> |
| </li> |
| <li>On the "Realm Settings", under the "Tokens" tab, set "Access Token Lifespan" 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 "kapua" realm)</li> |
| <li><code>sso.openid.keycloak.uri=http://<Keycloak-IP-address>:9090</code> : the Keycloak Server URI |
| (use <code>https://<Keycloak-IP-address>: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://<Keycloak-IP-address>:9090</code> : the Keycloak Server URI |
| (use <code>https://<Keycloak-IP-address>: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 'localhost', since this one can be misinterpreted by docker as the 'localhost' 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> |
| <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 "Users" tab on the left menu, click on "Add user"</li> |
| <li>Configure the user as follows:<ul> |
| <li>Username : e.g. "<em>alice</em>"</li> |
| <li>Email : e.g. "<em>alice@heremailprovider.com</em>"</li> |
| <li>User Enabled : <em>ON</em></li> |
| </ul> |
| </li> |
| <li>Configure the user credentials under the "Credentials" 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 "<em>admin</em>" or the "<em>sso-user</em>" 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 "<em>alice</em>" in Keycloak will generate "<em>alice</em>" |
| and "<em>alice-broker</em>" in Kapua, in a dedicated "<em>alice</em>" 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 "<em>admin</em>" in Keycloak as <em>externalId</em>):</p> |
| <pre><code>{ |
| "scopeId": "...", |
| "name": "admin", |
| "userType": "EXTERNAL", |
| "externalId" : "5726876c-...." |
| } |
| </code></pre><p>will create the "<em>admin</em>" 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://<Keycloak-IP-address>: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'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":{"danger":"fa fa-exclamation-circle","info":"fa fa-info-circle","tip":"fa fa-mortar-board","working":"fa fa-wrench"},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"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}},"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":"2020-12-22T18:11:17.805Z","type":"markdown"},"gitbook":{"version":"3.2.2","time":"2020-12-22T18:12:02.070Z"},"basePath":".","book":{"language":""}}); |
| }); |
| </script> |
| </div> |
| |
| |
| <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-sharing/buttons.js"></script> |
| |
| |
| |
| <script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script> |
| |
| |
| |
| </body> |
| </html> |
| |