This section explains how to integrate PPEM with OpenID Connect (OIDC) providers and describes the user authentication process.
Keycloak is used as an example of an OIDC provider in this section. You can select any other provider based on your organization's requirements.
The integration process includes the following steps:
For more information about the integration process, refer to Section 7.6.4.
Create a PPEM client in the Keycloak web application.
In doing so, follow the steps below:
Specify URIs required for integration with PPEM:
redirect URI in the
https://PPEM_host/auth/oidc/callback
format
post logout redirect URI in the
https://PPEM_host/
format
Generate a secret for the PPEM client.
For more information, refer to the official Keycloak documentation on creating client applications.
In the ppem-manager.yml manager
configuration file, specify the following Keycloak
integration parameters:
oidc:
issuer: keycloak_API_URL
client_id: ppem_client_ID
client_secret: ppem_client_secret
login_timeout: authentication_timeout
scopes:
- data_scopes
Where:
issuer: The URL of the Keycloak
API.
client_id: The client ID that you specified when
creating a PPEM client in Keycloak.
client_secret: The secret that you generated
when creating a PPEM
client in Keycloak.
login_timeout: The user authentication timeout.
If the timeout occurs, reauthentication is required.
Default value: 10m.
Optional parameter.
scopes: The list of data scopes that PPEM
will receive from Keycloak.
Possible values:
openid: The access token request.
This data scope is required. Without it, Keycloak returns an error when authenticating users.
profile: The Keycloak
user data request, for example, the username and last name.
email: The Keycloak
user email request.
This data scope is required. Without it, Keycloak users cannot be created in PPEM.
For more information, refer to Section 7.6.4.
phone: The Keycloak
user phone number request.
This data scope is optional.
roles: The Keycloak
groups request.
This data scope is required. Without it, Keycloak users cannot perform actions in the web application.
For more information, refer to Section 7.6.4.
offline_access: The refresh token request.
This data scope is optional, but recommended. Without it, reauthentication of Keycloak users is required after each access token expiration.
Default value:
- openid - profile - email
Example of the Keycloak integration configuration:
oidc:
issuer: http://198.51.100.0:8080/realms/j.doe
client_id: j.doe-ppem-client
client_secret: yyyyyYyyyYyYY1yy1yyyYyy1YYYYYy1y
login_timeout: 10m
scopes:
- openid
- profile
- email
- phone
- roles
- offline_access
You must add all Keycloak users to groups and then associate Keycloak and PPEM groups. In this case, Keycloak users are automatically added to PPEM groups and assigned roles through these groups. Otherwise, Keycloak users cannot perform any actions in the web application.
To associate Keycloak and PPEM groups, when creating or editing PPEM groups:
From Group, select OIDC.
In OIDC group, enter the Keycloak group name.
User association.
PPEM stores a list of all users in the
public.users table of the
repository database, and
Keycloak users are automatically created
in this table.
Since you specify the user email at
user creation, you must
also specify the email data scope when
configuring the manager for integration with Keycloak.
At each access token update, information about
Keycloak users is updated in the
public.users table using
iss and sub
access token fields, where iss is the
Keycloak URL and sub
is the Keycloak user ID.
Group association.
PPEM stores a list of user groups in the
public.groups table of the repository
database.
Keycloak and PPEM
groups are associated using
groups and iss access
token fields and source and
external_id fields of the
public.groups table. For the access token
to contain the groups field, you must
specify the roles data scope when
configuring the manager for integration with Keycloak.
If groups are associated, Keycloak users are automatically added to PPEM groups and assigned roles through these groups.
For more information, refer to Section 7.6.3.
You can block a Keycloak user from logging in to the web application.
To do this, select Blocked from PPEM Access when editing the user.
The user authentication process is based on the standard Authorization Code Flow for OIDC providers used in most applications. It includes the following steps:
Initial authentication:
The Keycloak user enters the network
address of the server where the
manager is installed
(hereinafter referred to as the PPEM server)
in the browser address bar, for example, https://ppem.example.com.
The PPEM server determines that the Keycloak user is missing a cookie with access and refresh tokens and redirects this user to the Keycloak web application.
The Keycloak user enters credentials.
If user credentials are valid, Keycloak sends a request containing a one-time code to the PPEM server.
The PPEM server exchanges the received one-time code for access and refresh tokens and creates a cookie with these tokens for the Keycloak user.
The Keycloak user can now access PPEM.
Automatic token update:
At each action in the web application, the PPEM server verifies whether the Keycloak user has a cookie with access and refresh tokens.
If required, the PPEM server exchanges the existing refresh token for new access and refresh tokens and creates a cookie with these tokens for the Keycloak user.
The action is performed.
Logout:
The Keycloak user logs out of the PPEM web application.
The Keycloak user is redirected to the Keycloak web application where the user session is terminated, and access and refresh tokens are deleted.
The Keycloak user is redirected to the PPEM web application. Due to missing access and refresh tokens, the user is redirected back to the Keycloak web application and is prompted to enter credentials.