Keycloak authentication

This file explains the Keycloak authentication. As a prerequisite, you must have configured a Keycloak, see the tutorial in Setup environment

Overview

The application is secured via a JWT generated by the backend. But before its generation, a first authentication is necessary: either Windows, or via a JWT provided by Keycloak. In previous versions of BIA framework (< 3.8), windows authentication was used. we will see here via Keycloak.

Add Credential

The BIA application uses a service account to retrieve data from KeyCloak (See Setup Environment, Keycloak, Service Account section)

If the application is running on Windows, add the login password in the vault via this command (By adapting the UserName and the UserPassword):

%windir%\system32\cmdkey.exe /generic:BIA:KeycloakSearchUserAccount /user:"UserName" /pass:"UserPassword"

How Activate

You must have at least version 3.8 of the BIA framework.

Back End

On your web server, disable windows authentication for your back end application.

At the source code level, in the launchSettings.json file, Change these settings as follows:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    ...
  },
}

In Api.Controllers.Base.AuthControllerBase, replace BiaControllerBaseNoToken by BiaControllerBaseIdP

public abstract class AuthControllerBase : BiaControllerBaseIdP

Add the Keycloak configuration in your different files bianetconfig.XXX.json

Values are to be adapted according to your Keycloak. In this example of json, the realm is called BIA-Realm, the client is called biaapp

"Authentication": {
      "Keycloak": {
        "IsActive": true,
        "BaseUrl": "https://url_of_my_keycloak", // To be adapted according to your Keycloak
        "Configuration": {
          "realm": "BIA-Realm",
          "Authority": "/realms/BIA-Realm",
          "RequireHttpsMetadata": true,
          "ValidAudience": "account"
        },
        "Api": {
          "TokenConf": {
            "RelativeUrl": "/realms/BIA-Realm/protocol/openid-connect/token",
            "ClientId": "biaapp",
            "GrantType": "password",
            "CredentialKeyInWindowsVault": "BIA:KeycloakSearchUserAccount",
            "EnvServiceAccountUserName": "KC_SA_USERNAME",
            "EnvServiceAccountPassword": "KC_SA_PASSWORD"
          },
          "SearchUserRelativeUrl": "/admin/realms/BIA-Realm/users"
        }
      },
      ...
}

The login and password of the keycloak account that owns the role view-users must be registered in the vault via this command while connected with the application pool account:

%windir%\system32\cmdkey.exe /generic:BIA:KeycloakSearchUserAccount /user:"MyLogin" /pass:"MyPassword"

How Restore Windows Authentication

Back End

On your web server, enable windows authentication for your back end application.

At the source code level, in the launchSettings.json file, Change these settings as follows:

{
  "iisSettings": {
    "windowsAuthentication": true,
    "anonymousAuthentication": true,
    ...
  },
}

In Api.Controllers.Base.AuthControllerBase, replace BiaControllerBaseIdP by BiaControllerBaseNoToken

public abstract class AuthControllerBase : BiaControllerBaseNoToken

In your different files bianetconfig.XXX.json, set the IsActive param to false.

"Authentication": {
      "Keycloak": {
        "IsActive": false,
        ...
      },
      ...
}