This section describes Eclipse Kapua single sign-on integration. The single sign-on solution is based onOpenID connectionidentity level, aboveOAuth 2.0licensing framework. Note that the OpenID Connect provider is unique to the same Kapua instance, so it is common to all accounts on that instance.
In this document we first describe how to enable SSO in Kapua. In a second step, we present two examples based on the Keycloak authentication server, using Docker and OpenShift.
Enable single logon
To enable single sign-on, you will need to select an OpenID provider. You can do this using the config propertysso.openid.provider.Currently, there are two default providers in Kapua. However, additional providers can be added to Kapua using the Java Service Load Framework. The current default providers are:
in general– A generic OpenID Connect providerkeychain– An OpenID Connect provider based on Keycloak configuration standards
Each provider will require additional configuration options. But there are a set of common configuration options:
sso.openid.client.id: the "Client ID" used in communicating with the OpenID Connect server. This also represents the public JWT to look up the OpenID Connect ID token (for more information, seehere)sso.openid.client.secret(optional): the "client secret" used in communicating with the OpenID Connect server.sso.openid.conf.path(optional): to provide a well-known custom OpenID suffix (default is.known/configuration-openidand appended as a suffix to the editor).sso.openid.jwt_processor_timeout(optional): The JwtProcessor timeout (default value is 1 hour).
It is also necessary to configure the external terminal address of the Web Console.
console.sso.openid.home.uri: the URL of the web console, for example.http://localhost:8080
SSO login will be available in the form of a dedicated button on the Kapua login page (the button can be enabled via the config optionsso.openid.provider).
General Provider
Generic provider configuration values are retrieved through the providerwell-knownOpenID configuration document provided by OpenID provider (see official documentOpenID Connect discovery specificationfor more information).editoris the only required parameter. However, custom parameters can be added via the following properties and are used in case the automatic configuration via thewell-knownthe document fails. The required values are specific to the OpenID Connect solution. Use your documentation to look up the required values:
sso.openid.generic.jwt.ssuer.allowed: The base URL for the OpenID server provider.sso.openid.generic.jwt.audience.allowed: the public JWT.sso.openid.generic.server.endpoint.auth(optional): The endpoint URL for the authentication API.sso.openid.generic.server.endpoint.logout(optional): The OpenID provider disconnect endpoint.sso.openid.generic.server.endpoint.token(optional): The endpoint URL for the token API.
Note that these properties, along with those defined in the previous paragraph, can be set via environment variables thanks torun consoleThe bash script is included in the Docker Console container. Refer toREADME mount unit filefor detailed information about these properties.
A note about the "customer id" and "public" values.
propertiessso.openid.client.idesso.openid.generic.jwt.audience.allowed(the second property is only used for thein generalprovider) represent basically the same value. More specifically,sso.openid.client.idused as a parameter in requests to the OpenID provider, whilesso.openid.generic.jwt.audience.allowedused byProcessor Jwtto validate the token received from the OpenID provider. These two must match the sameClient ID.
According to the official OpenID Connect specification (seehereehere), Opubliccontains a list of permissionsClient ID. The token can contain a list of audiences (described byaudapplication). When the token is received, we need to confirm that the audience contains it.Client IDwhich corresponds to the Kapua console. Only oneClient IDmatches the Kapua Console (if there are multiple client_ids in the public, they match other clients).
However, some implementations of the OpenID Provider use different values between clientId and public , so the only way to make them work is to use two different values for these properties (also note thatgeneric providershould be the most "forgiving" vendor).
keycloak provider
The Keycloak provider can be configured using the following configuration parameters:
sso.openid.keycloak.uri: the base URL on the Keycloak server.sso.openid.keycloak.realm: the domain name to use.
Note that theauthenticationerecommendationEndpoints are calculated automatically by the Keycloak provider. For more information about Keycloak, seeKeycloak Documentation.
Similar to the "generic" provider, these properties, along with the common properties defined earlier, can be set via environment variables thanks torun consoleThe bash script is included in the Docker Console container. Refer toREADME mount unit filefor detailed information about these environment variables.
Enable Users for SSO
Before a user can connect through an OpenID provider, the user must first be created on the OpenID Connect server (for example, using Keycloak, in the Keycloak Admin Console). Second, the user can be added to Kapua. Such a user differs from a "normal" user by its type (which isEXTERNAL, while a normal user isINTERNAL) and having no credentials (since your credentials are stored in the OpenID provider).
Currently, there are three methods to register an external user in Kapua: using theSimple Record Processor, usingAPI RESTor using itconsole.
Import the user through the SimpleRegistrationProcessor module
This module allows you to automatically create the user in Kapua on the first login attempt using SSO. Specifically, two users are created: an external user with no credentials, representing the SSO user, and an internal user with credentials, representing a portal user. Both users are placed into a new account with the same SSO username. If a user with the same name already exists in Kapua, the registration process will fail and the user is just logged in.
NOTICE: SimpleRegistrationProcessor should only be used as aConcept proofand should not be used in a real environment. For example, the credentials provided for the portal user are encoded in the SimpleRegistrationProcessor code. Note, however, that SimpleRegistrationProcessor is disabled by default. To enable it, the configuration optionauthentication.registration.service.enabledmust be provided with valueTRUE.
Import User via REST API
After obtaining the session token using an authentication REST API, a user can log in using
user creation.It is mandatory to provide the following functionalities:
scopeId: the ID of the domain to which the user will belong in Kapua.name: represents the name in the OpenID provider.user type: must always be set toEXTERNAL;external identifier: represents the unique identifier in the OpenID provider.
Enter user via Console
External users can log in through itUsersunit on the console. Log in with administrator credentials to add a user.
- Add the new user via the "Add" button.
- The Add dialog allows you to choose between an "Internal User" and an "External User". select the last one to add an external one.
- Enter your username and external ID. All other fields are optional.
An external user can also be modified via the "Edit" button (note that the "Username" and "External ID" fields cannot be modified). Note that the user does not have certain roles. To add a "Role", use the "Assign" button on the "Roles" tab. Also note that the external user does not have any "Credential" as the credentials are generated and stored in the external provider.
Enabling sso also allows you to see the User Type and, in the case of an external user, the external user ID on the Description tab.
To go out
If SSO is enabled, logging out of Kapua also logs out of the external OpenID provider, canceling the OpenID Connect session. This is implemented according to the OpenID Connect specification for theDisconnect from party support.Note that OpenID provider logout is also possible via the OpenID provider logout endpoint, but the user will remain logged in to Kapua until Kapua logout is also done.
OpenID Connect logout can be disabled by configuring theconsole.sso.openid.user.logout.enabledeconsole.sso.openid.session_listener.logout.enabledproperties forfalse(these properties are always set toTRUEby default). The first property allows disabling user-initiated logout, while the second allows disablingHttpSessionListenermanaged disconnect (see classOpenIDLogoutListener), which is triggered when the session is cancelled. Be careful if you choose to disable OpenID logout as this will allow the user to log back into the Kapua console without having to provide credentials.
Keycloak example (based on Docker)
Here we describe the steps to run an OpenID Keycloak provider. The example described here uses a Keycloak server Docker image (seehereFor more informations).
Installing Keycloak Server (Docker image)
To automatically deploy the Keycloak image, simply use thesso-docker-deploy.shscript insidethendocker deployment scripts subdirectory. In this way, the environment is ready for use without the need for additional configurations.
However, if you want to use a standalone Keycloak image, follow the instructions below to configure it.
Manual Keycloak server installation.
To download and install the image, rundocker pull jboss/keycloakin a bash terminal. so rundocker run -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -p 9090:8080 jboss/keycloakto start the docker container by setting the "Administrator"user(with"Administrator" as a password). The Keycloak Server Admin Console will be available at the following URL:http://
SSL configuration
The Keycloak provider can be configured to use SSL, which is enabled by configuring port 9443 toKEYCLOAK_URLnosso-docker-common.shfile. A self-signed certificate and key are generatedsso-docker-deploy.shscript and analyzed the volume based on./certs:/etc/x509/httpsdirectory. The script also installs the certificate into the Kapua console docker image (which is tagged with the 'sso' tag).
NOTICE: This SSL configuration is intended to be used for testing purposes only 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, see the officialKeycloak Documentation.
Keycloak server manual configuration
The Keycloak instance provided with the docker deployment is already configured with a dedicated "Kapua" domain and client when using the scriptsso-docker-deploy.shno subdirectorythen.
However, if you already have an instance of Keycloak running, you can follow the instructions below to configure it manually. Open the Keycloak Admin Console in your preferred browser and follow the steps below to configure it.
- Create a new realm in Keycloak, name it "cloud"
- Create a new client for this domain, name it "console" (this name means "Customer ID").
- Configure the Client Settings tab as follows:
- Client protocol: "open connection"
- Access: "public"
- Default flow enabled:ABOUT
- Direct access grants enabled:ABOUT
- Valid redirect URIs:http://localhost:8080/*(use your IP address instead of localhost)
- URL base:http://localhost:8080/
- In the “Mappers” tab, create a new mapping called “console” with the following parameters:
- Name : "console"
- Cartographer Type: "Public"
- Custom Audience Included: "console"
- Add to access token:ABOUT
- In "Realm Settings", "Tokens" tab, set "Access Token Lifespan" to 10 minutes (default time is too short)
Configure Kapua to use SSO with the Keycloak server
The Kapua console docker image is already configured and deployed to docker without further configuration using itsso-docker-deploy.shscript in subdirectorythen.
If you need to configure it manually, the following properties must be passed (like VM options) to configure SSO for Kapua using Keycloak (you can login using the defaultAdministratoruser withAdministratorPassword):
sso.openid.provider=keycloak: to set Keycloak as an OpenID providersso.openid.keycloak.realm=cap: the Keycloak realm (we use the "kapua" realm)sso.openid.keycloak.uri=http://: the URI of the Keycloak server (use:9090 https://if TLS is enabled - see below for details):9443 sso.openid.client.id=console: the OpenID client ID (the one defined in Keycloak)console.sso.openid.home.uri=http://localhost:8080: URI do console web Cloud
If you just need to launch docker from the console, just provide the following docker environment variables (they will automatically set the configuration properties described above):
KEYCLOAK_URL=http://: the URI of the Keycloak server (use:9090 https://if TLS is enabled - see below for details):9443 KAPUA_CONSOLE_URL=http://localhost:8080: URI do console web Cloud
When usingdocker-compile, these two variables are connected throughdocker-compose.yamlNote that even if the Keycloak server is running locally in a docker container, it is recommended to use your computer's IP address instead of 'localhost', as this can be misinterpreted by docker as the 'localhost' of the container running the Kapua or Keycloak component (this is done automatically via thesso-docker-deploy.shwriting).
Refer toREADME mount unit filefor detailed information about console docker container and related environment variables.
User configuration on Keycloak server
A test user has already been created within the Keycloak server, with usernamesso userand passwordsso password.The ID assigned by Keycloak must be used as an external ID on the Kapua side (see next section).
If you want to add a new user, follow the instructions below (remember to use theAdministratoruser withAdministratorpassword to login):
- On the Users tab in the left menu, click Add User
- Configure the user as follows:
- Username: eg. "Alice"
- Email: eg. "alice@heremailprovider.com"
- Enabled user:ABOUT
- Configure user credentials on the Credentials tab.
Note that the user must have an email defined on the OpenID Provider server, otherwise creation in Kapua via SimpleRegistrationProcessor will fail. It is also possible to use "Administrator"or the"sso user"users please login (reminder to add an email address).
User Configuration in Kapua
To add a new user to Kapua, simply add them via the console as described inEnter user via Consolesection. If you want to use the SimpleRegistrationProcessor or the REST API, follow the examples below.
Using the SimpleRegistrationProcessor, the user "Alice"no Keycloak will create"Alice" e "Alice brokerage"in Capua, in a dedicated"Alice" account.
Using the userCreate REST API with the following body (using thescopeIdof the desired account and user ID"Administrator« not Keycloak likeexternal identifier):
{ "scopeId": "...", "name": "admin", "userType": "EXTERNAL", "externalId" : "5726876c-...."}will create the "Administrator"user without the need for SimpleRegistrationProcessor.
Keycloak disconnect endpoint
Keycloak provider logout is possible via the Keycloak OpenID Connect logout endpoint:
{sso.openid.keycloak.uri}/auth/realms/{nome_do_realm}/protocol/openid-connect/logout
In our example the endpoint is:
http://
Keycloak example (based on OpenShift)
This project provides a template for starting a simple connection based onKeychain.The scripts for this are in the directorykapua/deployment/openshift/sso(Seekapua/deployment/minishift/ssoif you use Minishift).
Assuming you already have Kapua installed on OpenShift, you can run the scriptto develop, which will create a new build and development configuration in OpenShift. This is based on the official Keycloak Dockerimagejboss/keycloak, adding some steps for initial provisioning.
The default configuration uses temporary storage. Therefore, restarting the Keycloak pod will clear the configuration unless you reconfigure the configuration with a persistent volume.
After creating the build and deploy configuration, the script will reconfigure the Kapua OpenShift project to use the newly created Keycloak instance. This is done by calling the scriptactivate. OactivateThe script can be called later to reconfigure Kapua (eg when reinstalling Kapua).
Both scenarios (to developeactivate) require Kapua and Keycloak URLs. Keycloak requires the Kapua web console URL to allow requests from that source, while Kapua requires the Keycloak URL to forward requests to Keycloak. URLs are generated from OpenShift routes, which are configured for Kapua and Keycloak. However, this requires Kapua to have been configured prior to Keycloak and thatactivateThe script can only be called after theto developThe script ran successfully.
Refer toKeycloak example (based on Docker)section to create a user or follow the next section to register a user via email.
Email server-based user registration
For this setup to work, you will need an existing SMTP server that can send emails. This is required so that Keycloak can send user verification and password recovery emails. If you don't have a local SMTP server, you can also use a cloud-based service like Mailgun, SendGrid or any other provider.
Deployment is enabled by running itto developscript with a set of environment variables. Assuming you useviolent beatingas a shell, this can be done like this:
SMTP_HOST = smtp.server.org SMTP_USER = χρήστης SMTP_PASSWORD = segredo SMTP_FROM = remetente@meu.domínio ./deployThe following environment variables are used:
SMTP_HOST(mandatory): the hostname or IP address of the SMTP server.SMTP_PORT(optional): The SMTP service port number.SMTP_FROM(mandatory): The sender email used in the email.SMTP_USER(mandatory): The username used for authentication on the SMTP server.SMTP_PASSWORD(mandatory): the password used for authentication on the SMTP server.SMTP_ENABLE_SSL(optional): whether to use SSL instead of STARTTLS.KEYCLOAK_ADMIN_PASSWORD(optional): The password to be assigned to the Keycloak admin user. The default is to create a password.