Postgres Pro Enterprise Manager : Documentation: 2: 7.6. User Authentication via OpenID Connect : Postgres Professional

7.6. User Authentication via OpenID Connect
Prev	Up	Chapter 7. Security	Home	Next

7.6. User Authentication via OpenID Connect #

7.6.1. Creating a PPEM Client in Keycloak
7.6.2. Configuring the Manager for Integration with Keycloak
7.6.3. Associating Keycloak and PPEM Groups
7.6.4. Important Considerations
7.6.5. User Authentication Process

This section explains how to integrate PPEM with OpenID Connect (OIDC) providers and describes the user authentication process.

Important

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.

7.6.1. Creating a PPEM Client in Keycloak #

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.

7.6.2. Configuring the Manager for Integration with Keycloak #

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
```

7.6.3. Associating Keycloak and PPEM Groups #

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.

7.6.4. Important Considerations #

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.

7.6.5. User Authentication Process #

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:
1. 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.
2. 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.
3. The Keycloak user enters credentials.
4. If user credentials are valid, Keycloak sends a request containing a one-time code to the PPEM server.
5. 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:
1. At each action in the web application, the PPEM server verifies whether the Keycloak user has a cookie with access and refresh tokens.
2. 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.
3. The action is performed.
Logout:
1. The Keycloak user logs out of the PPEM web application.
2. The Keycloak user is redirected to the Keycloak web application where the user session is terminated, and access and refresh tokens are deleted.
3. 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.

Prev	Up	Next
7.5. Authentication and Authorization Operation Scheme	Home	7.7. Role-Based Access Control (RBAC) Model

epub pdf