Merge pull request #3298 from gbarbon/feature-ssoOidcEnvVarRenaming

SSO - OIDC environment variables renaming

assembly/README.md

@@ -24,6 +24,9 @@ the IP address of your docker instance.
 
 **Note:** This is only a setup for testing SSO support.
 
+The following paragraphs describe how to set up an SSO OpenID Connect Provider in Kapua via environment variables.
+For further information, please see the [SSO Developer Guide](docs/developer-guide/en/sso.md).
+
 #### Keycloak Provider
 
 It is possible to test the sso with a Keycloak image by simply launching the `deploy` scripts located in the `deployment/docker/unix/sso` directory.
@@ -41,21 +44,30 @@ Starting the `kapua-console` image with the following command line instead:
 You will also need to create a new realm named `kapua` in the Keycloak web UI and create a new client called `console`, 
 assigning `http://localhost:8080/*` as a valid redirect URI.
 
-For further information take a look at the `sso.md` manual located in the `docs/developer-guide/en` directory.
+To use the Keycloak provider with the Kapua Console, the following environment variables must be provided:
+
+- `KAPUA_CONSOLE_URL` : the `kapua-console` URL;
+- `KEYCLOAK_URL` : the URL of the Keycloak instance;
+- `KEYCLOAK_REALM` : the keycloak realm (the default value is `kapua`);
+- `KEYCLOAK_CLIENT_ID` : the client id in the keycloak realm (the default value is `console`);
+- `KAPUA_OPENID_CLIENT_SECRET` : the client secret (optional).
 
 #### Generic Provider
 
 It is also possible to use a generic OpenID Connect provider, by providing to the console the following environment 
 variables:
 
-- `OPENID_JWT_ISSUER` : the base URL to the OpenID Connect server provider.
-- `OPENID_CLIENT_ID` : the client id (the default value is `console`).
-- `CLIENT_SECRET` : the client secret (optional).
-- `JWT_AUDIENCE` : the JWT audience (the default value is `console`).
-- `OPENID_AUTH_ENDPOINT` : the endpoint URL to the authentication API (optional, already retrieved via well-known document).
-- `OPENID_TOKEN_ENDPOINT` : the endpoint URL to the token API (optional, already retrieved via well-known document).
-- `OPENID_LOGOUT_ENDPOINT` : the URL to the logout endpoint (optional, already retrieved via well-known document).
-- `KAPUA_CONSOLE_URL` : the `kapua-console` URL.
+- `KAPUA_CONSOLE_URL` : the `kapua-console` URL;
+- `KAPUA_OPENID_JWT_ISSUER` : the base URL to the OpenID Connect server provider;
+- `KAPUA_OPENID_JWT_AUDIENCE` : the JWT audience (the default value is `console`);
+- `KAPUA_OPENID_CLIENT_ID` : the client id (the default value is `console`);
+- `KAPUA_OPENID_CLIENT_SECRET` : the client secret (optional);
+- `KAPUA_OPENID_AUTH_ENDPOINT` : the endpoint URL to the authentication API (optional, already retrieved via well-known document);
+- `KAPUA_OPENID_TOKEN_ENDPOINT` : the endpoint URL to the token API (optional, already retrieved via well-known document);
+- `KAPUA_OPENID_LOGOUT_ENDPOINT` : the URL to the logout endpoint (optional, already retrieved via well-known document).
+
+Note that `OPENID_CLIENT_ID` and `JWT_AUDIENCE` are usually mapped with the same value,
+(see the [SSO Developer Guide](docs/developer-guide/en/sso.md) for further information).
 
 ### Tomcat images
 

assembly/console/entrypoint/run-console

@@ -25,29 +25,29 @@ if [ -n "$KEYCLOAK_URL" ] && [ -n "$KAPUA_CONSOLE_URL" ]; then
    JAVA_OPTS="$JAVA_OPTS -Dsso.openid.provider=keycloak"
    JAVA_OPTS="$JAVA_OPTS -Dsso.openid.client.id=${KEYCLOAK_CLIENT_ID}"
 
-   test -n "$CLIENT_SECRET" && JAVA_OPTS="$JAVA_OPTS -Dsso.openid.client.secret=${CLIENT_SECRET}"
+   test -n "${KAPUA_OPENID_CLIENT_SECRET}" && JAVA_OPTS="$JAVA_OPTS -Dsso.openid.client.secret=${KAPUA_OPENID_CLIENT_SECRET}"
 
    JAVA_OPTS="$JAVA_OPTS -Dsso.openid.keycloak.uri=${KEYCLOAK_URL}"
    JAVA_OPTS="$JAVA_OPTS -Dsso.openid.keycloak.realm=${KEYCLOAK_REALM}"
 
    JAVA_OPTS="$JAVA_OPTS -Dconsole.sso.openid.home.uri=${KAPUA_CONSOLE_URL}"
 
 # Check for generic OpenID Connect provider integration
-elif [ -n "${KAPUA_CONSOLE_URL}" ] && [ -n "${OPENID_JWT_ISSUER}" ]; then
+elif [ -n "${KAPUA_CONSOLE_URL}" ] && [ -n "${KAPUA_OPENID_JWT_ISSUER}" ]; then
    echo "Activating OpenID Connect Generic integration..."
-  echo "  OpenID Issuer: ${OPENID_JWT_ISSUER}"
+  echo "  OpenID Issuer: ${KAPUA_OPENID_JWT_ISSUER}"
   echo "  Console: ${KAPUA_CONSOLE_URL}"
 
   JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.provider=generic"
-  JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.client.id=${OPENID_CLIENT_ID:-console}"
-  test -n "${CLIENT_SECRET}" && JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.client.secret=${CLIENT_SECRET}"
+  JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.client.id=${KAPUA_OPENID_CLIENT_ID:-console}"
+  test -n "${KAPUA_OPENID_CLIENT_SECRET}" && JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.client.secret=${KAPUA_OPENID_CLIENT_SECRET}"
   JAVA_OPTS="${JAVA_OPTS} -Dconsole.sso.openid.home.uri=${KAPUA_CONSOLE_URL}"
 
-  JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.generic.jwt.audience.allowed=${JWT_AUDIENCE:-console}"
-  JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.generic.jwt.issuer.allowed=${OPENID_JWT_ISSUER}"
-  test -n "${OPENID_AUTH_ENDPOINT}" && JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.generic.server.endpoint.auth=${OPENID_AUTH_ENDPOINT}"
-  test -n "${OPENID_LOGOUT_ENDPOINT}" && JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.generic.server.endpoint.logout=${OPENID_LOGOUT_ENDPOINT}"
-  test -n "${OPENID_TOKEN_ENDPOINT}" && JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.generic.server.endpoint.token=${OPENID_TOKEN_ENDPOINT}"
+  JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.generic.jwt.audience.allowed=${KAPUA_OPENID_JWT_AUDIENCE:-console}"
+  JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.generic.jwt.issuer.allowed=${KAPUA_OPENID_JWT_ISSUER}"
+  test -n "${KAPUA_OPENID_AUTH_ENDPOINT}" && JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.generic.server.endpoint.auth=${KAPUA_OPENID_AUTH_ENDPOINT}"
+  test -n "${KAPUA_OPENID_LOGOUT_ENDPOINT}" && JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.generic.server.endpoint.logout=${KAPUA_OPENID_LOGOUT_ENDPOINT}"
+  test -n "${KAPUA_OPENID_TOKEN_ENDPOINT}" && JAVA_OPTS="${JAVA_OPTS} -Dsso.openid.generic.server.endpoint.token=${KAPUA_OPENID_TOKEN_ENDPOINT}"
 fi
 
 # Multi Factor Authentication configurations

deployment/docker/compose/docker-compose.yml

@@ -64,13 +64,13 @@ services:
       - KAPUA_KEYSTORE_PASSWORD
       - LOGBACK_LOG_LEVEL
       - KAPUA_CONSOLE_URL
-      - OPENID_JWT_ISSUER
-      - OPENID_CLIENT_ID
-      - CLIENT_SECRET
-      - JWT_AUDIENCE
-      - OPENID_AUTH_ENDPOINT
-      - OPENID_TOKEN_ENDPOINT
-      - OPENID_LOGOUT_ENDPOINT
+      - KAPUA_OPENID_JWT_ISSUER
+      - KAPUA_OPENID_CLIENT_ID
+      - KAPUA_OPENID_CLIENT_SECRET
+      - KAPUA_OPENID_JWT_AUDIENCE
+      - KAPUA_OPENID_AUTH_ENDPOINT
+      - KAPUA_OPENID_TOKEN_ENDPOINT
+      - KAPUA_OPENID_LOGOUT_ENDPOINT
       - KEYCLOAK_URL
       - KEYCLOAK_CLIENT_ID
       - KEYCLOAK_REALM

deployment/docker/compose/sso/sso-docker-compose.yml

@@ -64,13 +64,13 @@ services:
       - KAPUA_KEYSTORE_PASSWORD
       - LOGBACK_LOG_LEVEL
       - KAPUA_CONSOLE_URL
-      - OPENID_JWT_ISSUER
-      - OPENID_CLIENT_ID
-      - CLIENT_SECRET
-      - JWT_AUDIENCE
-      - OPENID_AUTH_ENDPOINT
-      - OPENID_TOKEN_ENDPOINT
-      - OPENID_LOGOUT_ENDPOINT
+      - KAPUA_OPENID_JWT_ISSUER
+      - KAPUA_OPENID_CLIENT_ID
+      - KAPUA_OPENID_CLIENT_SECRET
+      - KAPUA_OPENID_JWT_AUDIENCE
+      - KAPUA_OPENID_AUTH_ENDPOINT
+      - KAPUA_OPENID_TOKEN_ENDPOINT
+      - KAPUA_OPENID_LOGOUT_ENDPOINT
       - KEYCLOAK_URL
       - KEYCLOAK_CLIENT_ID
       - KEYCLOAK_REALM

docs/developer-guide/en/sso.md

@@ -9,9 +9,10 @@ using Docker and OpenShift.
 
 ## Enabling single sign-on
 
-In order to enable single sign-on you will need to select an OpenID provider. You can do this using the
-configuration option `sso.openid.provider`. Currently there are two default providers in Kapua. However additional
-providers can be added to Kapua by using the Java service loader framework. 
+In order to enable single sign-on you will need to select an OpenID provider.
+You can do this using the configuration property `sso.openid.provider`.
+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:
 
 * `generic` – A generic OpenID Connect provider
@@ -24,9 +25,9 @@ options:
     This represents also the JWT audience to search for in the OpenID Connect ID Token
     (for more information see [here](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) )
 - **`sso.openid.client.secret` (optional)** : the "client secret" used when communicating with the OpenID Connect server.
-- **`sso.openid.conf.wellknown.path` (optional)** : to provide a custom OpenID well-known suffix (the default one is `.well-known/openid-configuration` and 
+- **`sso.openid.conf.path` (optional)** : to provide a custom OpenID well-known suffix (the default one is `.well-known/openid-configuration` and
     it's attached as suffix to the issuer).
-- **`sso.openid.jwt-processor-timeout` (optional)** : the JwtProcessor expiration time (the default value is 1 hour).
+- **`sso.openid.jwt_processor_timeout` (optional)** : the JwtProcessor expiration time (the default value is 1 hour).
 
 It is also necessary to configure the Web Console external endpoint address.
 
@@ -43,12 +44,16 @@ The `issuer` is the only required parameter. However, custom parameters can be a
 configuration through the `well-known` document fails.
 The required values are specific to your OpenID Connect solution, please use its documentation to look up the required values:
 
-- **`sso.generic.openid.jwt.issuer.allowed`** : the base URL to the OpenID server provider.
-- **`sso.generic.openid.jwt.audience.allowed`** : the JWT audience.
+- **`sso.openid.generic.jwt.issuer.allowed`** : the base URL to the OpenID server provider.
+- **`sso.openid.generic.jwt.audience.allowed`** : the JWT audience.
 - **`sso.openid.generic.server.endpoint.auth` (optional)** : the endpoint URL to the authentication API.
 - **`sso.openid.generic.server.endpoint.logout`(optional)** : the logout endpoint of the OpenID provider.
 - **`sso.openid.generic.server.endpoint.token` (optional)** : the endpoint URL to the token API.
 
+Note that these properties, in combination with the ones defined in the previous paragraph,
+ can be set via environment variables thanks to the `run-console` bash script included in the Console docker container.
+Please refer to the [assembly module README file](assembly/README.md) for detailed information about those properties.
+
 #### Note about 'client id' and 'audience' values
 
 Properties `sso.openid.client.id` and `sso.openid.generic.jwt.audience.allowed` (the second property is used only for the `generic` provider) 
@@ -73,8 +78,11 @@ The Keycloak provider can be configured using the following configuration parame
 - **`sso.openid.keycloak.realm`** : the name of the realm to use.
 
 Note that the _auth_ and _token_ endpoints are automatically computed by the Keycloak provider.
+For more information about Keycloak, see the [Keycloak Documentation](http://www.keycloak.org/documentation.html).
 
-For more information see the [Keycloak Documentation](http://www.keycloak.org/documentation.html).
+Similarly to the 'generic' provider, these properties, in combination with the common properties defined previously,
+ can be set via environment variables thanks to the `run-console` bash script included in the Console docker container.
+Please refer to the [assembly module README file](assembly/README.md) for detailed information about these environment variables.
 
 ### Enabling users to SSO
 
@@ -195,7 +203,7 @@ Open the Keycloak Admin Console on your preferred browser and follow the steps b
     - Access : "_public_"
     - Standard Flow Enabled : _ON_
     - Direct Access Grants Enabled : _ON_
-    - Valid Redirect URIs : _http://localhost:8080/*_  (user your IP address in place of localhost)
+    - Valid Redirect URIs : _http://localhost:8080/*_  (use your IP address in place of localhost)
     - Base URL : _http://localhost:8080/_
 3. Under the "Mappers" tab, create a new mapper called "console" with the following parameters:
     - Name : "_console_"
@@ -233,6 +241,9 @@ IP address instead of 'localhost', since this one can be misinterpreted by docke
 in which the Kapua component or Keycloak are running (this is automatically done through the `sso-docker-deploy.sh`
 script). 
 
+Please refer to the [assembly module README file](assembly/README.md) for detailed information about the Console docker container
+and related environment variables.
+
 ### Setting Up a user on the Keycloak server
 
 A test user is already created inside the Keycloak server, with username `sso-user` and password `sso-password`.