SafeNet Keycloak Agent is used for integration of a Keycloak Identity provider function (IDP) with SAS PCE. With this integration, SAS PCE provides multi-factor authentication in context of authentication requests received by the Keycloak IDP from SAML or OIDC integrated applications. This agent is also a key component of STA Hybrid Access Management Add-On based deployment.

SafeNet Keycloak Agent also supports Single Sign-On (SSO) for applications integrated through Keycloak IDP. If an SSO exists for the same user and browser, SAS PCE is not invoked for token-based multi-factor authentication (MFA) and access is permitted when an access attempt reaches the Keycloak IDP. The access event is logged in the Keycloak IDP in this situation. If SSO is absent, SAS PCE is used for token-based MFA. If the authentication is successful, SSO is launched in the context of the users and the browser on the their system.

System Requirements

Operating System

The SafeNet Agent for Keycloak is supported by Java compatible operating systems (Linux or Windows).

Software Requirements

• Oracle JDK 17, OpenJDK 17

• SAS PCE

• Keycloak Server

Prerequisites

Configuration of these components is necessary for the installation of SafeNet Keycloak Agent.

SAS PCE

SafeNet Authentication Service PCE v3.20 and above is supported.

Keycloak Server

• Ensure that the Keycloak server version 22.0.5 is deployed on the system along with administrator user setup. For installation and configuration, refer to the server section in the Keycloak Server Guide.

• Refer to the Server Initialization section of the Keycloak Server Administrator Guide to set up the administrator user and master realm.

• Ensure the Keycloak server's directory structure contains "bin/", "conf/", "lib/", "data/", "providers/" and "themes/".

  

• You need to run Keycloak 22.0.5 with your configuration and it should be available in your keycloak.conf file.

• Ensure the SAS Token Validator service is accessible from the system where Keycloak is configured.
  http(s):<sas-server-ip>:<port>/TokenValidator/TokenValidator.asmx

Keycloak Server Migration

In Keycloak version 22, Quarkus distribution is the default distribution. For those using the Keycloak Wildfly distribution, it is required to migrate to the Quarkus distribution.

If you are using Keycloak Agent 1.2.0 with Keycloak version 15.0.2 (Wildfly), follow the steps below to migrate to Keycloak Agent 1.4.0 with Keycloak version 22.0.5 (Quarkus):

1. Create a backup of the old installation, including configuration, themes, and others.

2. Create a backup of the database using the instructions in the documentation for your relational database.

3. Download and extract Keycloak 22.0.5 server to install a clean instance of Keycloak.

4. Copy conf/ from the previous installation to the new installation.

   If upgrading from Keycloak Agent 1.3, remove Features-disabled=admin2 from the conf file.

   Note

   Keycloak automatically migrates the database schema or you can do it manually. By default, the database is automatically migrated when you start the new installation for the first time.

5. Upgrade the Keycloak server.

   Note

   The database is not compatible with the old server after the upgrade.

6. Install Keycloak Agent at the new Keycloak server location.

7. (Optional) If you need to roll back, restore the old installation first, and then restore the database from the backup.

For more details on the migration procedure, see the Upgrading Guide version 22.0.5.

Terminologies

• Keycloak Directory: Keycloak server installation directory.

• Authentication Flow: An authentication flow is a container for all authentications, screens, and actions that are mandatory during login, registration, and other Keycloak workflows.

Package Contents

The SafeNet Keycloak Agent is a compressed zip|tar.gz file. The SafeNetKeycloakAgent Package contains:

• Setup scripts

• Binaries

• Themes resources

• SafeNet OTP Realm json file

• Realm configuration and Authentication flows defined for SAS OTP Validation.

To unpack this file, run the unzip, gunzip or tar utilities.

Keycloak SAS Providers (Keycloak SPIs)

On the functional level, the package updates the following modules on the pre-installed Keycloak server.

• SafeNet OTP Authentication Flow – Customized authentication flow for OTP validation with SAS Token Validator service.

• SafeNet Theme – Customized theme to define SafeNet HTML templates and stylesheets.

Set up SAS API for SAS PCE

SAS API requests data from SAS PCE to dynamically update the SafeNet Keycloak Agent.

When SafeNet Keycloak Agent is configured with SAS using MySQL database, follow below steps.

Before installation ensure that the following steps are performed:

1. After installing SafeNet server, install MySQL 8.0.32 Connector.

2. Configure SafeNet server with MySQL database.

3. Copy the following text in a text file and save the file in the .ps1 file format:

   ```text

   Note that you should be running PowerShell as an Administrator

   $publish = New-Object System.EnterpriseServices.Internal.Publish $publish.GacInstall("C:\Program Files (x86)\MySQL\MySQL Connector Net 8.0.32\Assemblies\v4.5.2\MySql.Data.EntityFramework.dll")

   If installing into the GAC on a server hosting web applications in IIS, you need to restart IIS for the #applications to pick up the change.

   Iisreset ```

4. Run the .ps1 file, as an Administrator in the PowerShell.

5. Reset IIS.

Points to Remember

• Default location: System Directory:\Program Files (x86)\MySQL\MySQL Connector Net 8.0.27\<locate MySql.Data.EntityFramework.dll file>

• If someone changes the directory location while installing the MySQL Connector, the above path also needs to be updated in the script.

• Open the PowerShell script and change the path to where your DLL resides.

Configuration overview

• Installing SafeNet Agent for Keycloak and Realm Configuration are mandatory.

• User Federation Setup (Either LDAP or SAS User Federation is mandatory).

• Customization, Logging in SafeNet Agent for Keycloak and Testing the End User Login flow are optional.