Purpose

This stack provides Keycloak, an Identity and Access Management (IAM) service. Keycloak provides Single-Sign On (SSO), LDAP connectivity, OpenID Connect, OAUth 2.0 and SAML 2.0 protocol support, and Social Login.

Properties

Topology

The stack is comprised of two containers:

• iam-keycloak hosts the Keycloak application
• iam-keycloak-postgresql hosts the RDBMS which provides persistence 

Configuration

See also the variables which control integration of the stack into the reverse proxy.
For changes to take effect the stack has to be reinstalled.

First Steps

Access Keycloak by clicking its tile on your ProjectServer entry page and select Administration Console. Then login as administrator;
after installation the stack is preconfigured with the administrator account admin, password admin. After login you find yourself in the Realm Settings screen.

Keycloak has the concept of realms. This are separate, isolated sets of users, credentials, roles and groups, allowing Keycloak to manage different security contexts. The realm master does already exist. Hovering the mouse over the string Master in the top left corner of the screen reveals an Add Realm button in order to create a new realm. You just need to provide the new realm's name and press Create. You are then forwarded to a second screen where you may provide additional details. You normally don't need, just refer to the help texts behind the question mark buttons for details.

In Keycloak lingo Clients are the applications which users want to use and which contact Keycloak in order to verify the user's identity and to learn about his/her rights. Therefore you have to create one such client per application. You start by clicking Clients in the navigation bar on the left side. On the far right you then find the Create button. In the next screen you again just enter the client id. Preferably you name it after your application or stack, e.g. vcs-gitea.

Pressing Save drops you into the next screen. Here you switch the Access-Type from "public" to "confidential" to enable the client secret which a client has to present to Keycloak before it gets served.

The only mandatory entry field is Valid Redirect URIs. This is  the URI Keycloak contacts to return control to the application after authentication is done. Each application forms this URI upon its own ideas; to help here is a collection of redirect URIs for some PS4 stacks. Do not forget to press Save then.

Basically Keycloak offers three ways where to get user information:

• It may do User Federation through a central identity database like Active Directory, usually accessed through the LDAP protocol,
• it may hook on other Identity Providers like GitHub, Twitter, StackExchange etc. through OpenId Connect or SAML
• or it may take them from its own local user database.

Local users belong to groups, so the first step is to access the Groups screen. Press button New on the right to create one. You just have to provide a group name, then press Save.

Then proceed to the Users section where you press Add User. Enter the user's account name, e-mail address and his first and last name, then Save.

Then switch to the Credentials tab. Provide a password in the first two entry fields. Leaving Temporary to OFF will force the user to change his password at his initial login. You confirm this by pressing Reset Password (as this is the very same dialog you use in order to reset the user's password) and confirm the following security query.

Finally you assign the user to a group: While still in the Users section switch to the Groups tab. You find an Available Groups table to the right where you select the group name (in the below example the group is named "local"). Then press Join. Done!

TODO: establish User Federation

TODO: establish Identity Provider

Logging

At least for production setups it make sense to send log messages ("events") to the database so that they are available for later analysis. The corresponding  configuration screen is Events->Config. Do not forget to configure an expiration time so that the database does not grow infinitely.

Administration Commands

Related Documents

• Most recent changes

• HowTo: Using Keycloak as identity provider for Gitea