Getting started with Keycloak

Admin Console

The Admin Console is the Keycloak user interface that enables administrators to manage user accounts and access to Payment Manager.

As an administrator of Payment Manager user accounts, you need the following:

An admin account to the Admin Console.
This is created by the Infrastructure team deploying Payment Manager. The admin account must be set up so that it has permissions to manage only the relevant realm.
The URL to the Admin Console.
This is also provided by the Infrastructure team.
VPN access to the Admin Console.

For further information on the Admin Console, see section Admin Console in the Keycloak Server Administration Guide.

Prerequisites

To be able to add user accounts to manage access to Payment Manager, the Payment Manager application itself must be set up in Keycloak first:

A realm or realms must be configured.
The Payment Manager user interface must be registered as a client of Keycloak.

This section provides details about these two prerequisites.

Realms

In the case of an on-premise deployment, Payment Manager comes with an out-of-the-box Pm4ml realm (Pm4ml stands for Payment Manager for Mojaloop). A realm can be thought of as an isolated domain, in this case, that domain is the Payment Manager application. Anything within the Pm4ml realm relates to the Payment Manager instance.

In the case of a SaaS cloud deployment, there will always be one realm per DFSP.

The Pm4ml realm has some pre-configured settings. You can find these settings under the Realm Settings menu item, displayed in the left-hand navigation pane. On clicking Realm Settings, various tabs are displayed in the right-hand pane.

Figure 1. Realms

Some of the key settings on the General and Login tabs are highlighted in the table below.

Click the links in the table to find out further details about the individual settings.

Table 1. Realm Settings
Tab	Setting
General	Name: This is the name of the Pm4ml realm.
	Enabled: ON This is required because a realm can only be accessed if it is enabled.
	Display name: Payment Manager for Mojaloop The name specified here is the name that is displayed on the Keycloak sign-in page when the user logs in to Payment Manager.
	User-Managed Access: OFF If this is set to ON, users can manage access to protected resources. For further details, see section User-Managed Access in the Keycloak Authorization Services Guide.
	Endpoints: OpenID Endpoint Configuration and SAML 2.0 Identity Provider Metadata
Login	User registration: OFF This is required so that Payment Manager users are not able to create an account for themselves, and user accounts are always created by an admin person.
	Edit username: OFF If this is set to OFF, the user’s username is not allowed to be updated.
	Forgot password: ON When enabled, users are able to reset their credentials if they forget their password or lose their OTP generator.
	Remember Me: OFF When disabled, if a logged-in user closes their browser, their session is destroyed and they will have to log in again.
	Verify email: OFF When disabled, the user will not get a verification email on registering the user.
	Login with email: ON When enabled, the user can log in using their email address.
	Require SSL: external requests Keycloak requires a secure connection when accessing Payment Manager from a non-private IP address.
Token	The settings on this tab enable you to configure how you want the refresh of access tokens to happen, how long a session can be live or idle, and so on.

For further information on realm settings, see Keycloak documentation.

Clients

Clients in Keycloak are entities that can request the authentication of a user. The Payment Manager application is one such entity, which has to be registered to the Payment Manager realm.

The Payment Manager user interface (pm4ml-customer-ui) is registered as a client to the Payment Manager realm by default.

Clients other than pm4ml-customer-ui are Keycloak’s own clients necessary for the correct operation of Keycloak. Do not modify client settings unless you have a particular requirement and the consequences of your actions (reduced security) are fully understood.

Figure 2. Clients

On clicking pm4ml-customer-ui, the settings associated with it are displayed. Some key settings are highlighted below.

Table 2. Clients
Tab	Setting
Settings	Root URL: Specifies the URL where the Payment Manager user interface is accessible to users of Payment Manager.
Credentials	Client Athenticator: Client id and Secret This setting is required so that the Payment Manager Experience API can identify itself securely to Keycloak. The secret is automatically generated, and the Regenerate Secret button allows you to recreate this secret if you want to or need to. NOTE: You get a new client secret every time you restart Keycloak (Keycloak refreshes all its keys if the database that holds the keys loses its state).

Figure 3. Client settings

For further information on client settings, see section Clients in the Keycloak Server Administration Guide.