Authentication

Authentication is performed using OpenID Connect protocol. For more information about the details of OpenID Connect please refer to the official specification.

Keycloak (an OpenID Provider) is included in the product to allow authenticating to all the client applications with that need. Keycloak is an open source Identity and Access Management solution that works as OpenID Provider. An OpenID Provider is an OAuth 2.0 Authorization Server that is capable of Authenticating the End-User and providing Claims to a Relying Party about the Authentication event and the End-User. For more information about Keycloak please refer to the official documentation.

Obtaining an access token

For testing, development or administration purposes we may need to obtain an access token to be able to access the REST APIs. We can obtain one using the Direct Access Grants flow. This means that client has access to username/password of user and exchange it directly with Keycloak server for an access token. In terms of OAuth2 specification, this is called “Resource Owner Password Credentials Grant”.

1 POST https://<keycloak-host>/realms/<realm>/protocol/openid-connect/token HTTP/1.1
2 Content-Type: application/x-www-form-urlencoded
3 {
4     grant_type: "password",
5     client_id: "admin-cli",
6     username: <username>,
7     password: <password>,
8 }

This can be achieved for example using curl with the following command:

 1 curl -X POST https://<keycloak-host>/realms/<realm>/protocol/openid-connect/token -d "grant_type=password&client_id=admin-cli&username=<username>&password=<password>"
 2
 3 {
 4     "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJaTzQ5NFN1QjNBdThMcjMwVTRsQVoxdGNHVXZ2eXhYalA4VG5kNzV",
 5     "expires_in": 4200,
 6     "refresh_expires_in": 864000,
 7     "refresh_token": "eyJhbGciOiJy0BD7p9K6A-3Q11Yt3RLg",
 8     "token_type": "Bearer",
 9     "not-before-policy": 1647863488,
10     "session_state": "737cb7df-4d2f-41ca-a25a-e4066d8d9ef3",
11     "scope": "email profile"
12 }

And we can see the response with the requested access_token eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSld....

To use the token we just need to include it in the Authorization header like in the next example:

1curl -X GET https://rest-api-IP-of-your-system/sapi/users -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJaTzQ5NFN1QjNBdThMcjMwVTRsQVoxdGNHVXZ2eXhYalA4VG5kNzV"

Keycloak configuration

  • When adding a SAML v2 Identity Provider, please make sure that the parameter “Force Authentication” is set to “OFF” in order to properly logout. More information can be found in the Keycloack documentation site.

User session count limit

Keycloak’s last versions added a new variable that allows the system to limit how many sessions a user can create. In order to add this configuration, the Authentication Flows must be modified (Keycloak recommends, at least, Browser, Direct Grant and Reset Credentials).

The configuration for these limits is as follows:

{
"id": "92d5ac54-f1e6-4cef-907f-22f011526500",
"alias": "Sessionslimit",
"config": {
  "userClientLimit": "0",
  "behavior": "Deny new session",
  "userRealmLimit": "3"
}

It is required to add an alias, so it can be called in the different Flows.

Limits and behavior can be configurable. Limits can be applied per client or per realm.

First one (userClientLimit) limits the maximum number of sessions a user can have with each client while the second one (userRealmLimit) limits the number of sessions per user in the whole realm

The behaviour defines how the limits work. The are two options:

  • Deny new session. If there are a number of sessions equals to the limit, it will deny the access to the new session.

  • Terminate oldest session. If the are a number of sessions equals to the limit, it will delete the oldest one an create another one session.

It is remarkable that a deleted session is not a logout. The session will be alive until the window or application are closed.

Single sign-on (SSO) with Google

Keycloak can be configured to delegate authentication agains Google identity services to implement a Single sing-on service (SSO). This chapter describes the configuration needed both in the Google console and the Keycloak server.

Google console configuration

  • Create a project in console.cloud.google.com.

  • Go to “OAuth consent screen” and select which users are allowed to login:

    • Internal: Users accounts from our organization

    • External: Every Google account

  • Fill the following fields: App name, User support email, Authorized domains & Email addresses

  • Go to “Credentials” and Create Credentials with OAuth client ID

  • Use “Web application” as Aplication type and fill its name.

  • Copy the “Authorized redirect URI” from our Keycloak console→ Identity Provider→ Google → Redirect URI

Keycloak

  • Select “Google” from the “Identity Providers” section in the realm that you want to use for this authentication scheme.

  • Get the ID and Secret from the credentials created before.

  • Go to “Authentication” and Create Flow with “Detect existing broker user” and “Automatically set existing user”

  • Configure Google in “Identity Provider” to use this Flow as “First Login Flow”.