SafeNet Agent for Keycloak

SafeNet Agent for Keycloak is used for integration of a Keycloak identity provider function (IDP) with SAS PCE. With this integration, SAS PCE provides multi-factor authentication in the 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 Agent for Keycloak also supports Single Sign-On (SSO) for applications integrated through a 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 browser on their system.

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 Agent for Keycloak.

SAS PCE

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

Keycloak server

• Ensure that the Keycloak server version 24.0.5 is deployed on the system along with the 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 must run Keycloak 24.0.5 with your configuration. 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 24, Quarkus distribution is the default distribution. Those using Keycloak Wildfly distribution must migrate to Quarkus distribution.

To migrate from Keycloak Agent 1.2.0 with Keycloak version 15.0.2 (Wildfly) to Keycloak Agent 1.5.0 with Keycloak version 24.0.5 (Quarkus):

1. Create a backup of the existing installation, including configuration, themes, and other files.

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

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

4. Copy conf/ from the existing 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 SafeNet Agent for Keycloak 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 about the migration procedure, see the Upgrading Guide version 24.0.5.

Terminology

• Keycloak directory: Keycloak server installation directory.

• Authentication flow: A container for all authentications, screens, and actions that are mandatory during login, registration, and other Keycloak workflows.

Package contents

SafeNet Agent for Keycloak 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 (SPI)

On a 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 SafeNet Agent for Keycloak.

This setup is mandatory when SAS is configured with MySQL database.

SAS API encounters an issue with the MySQL database (MySQL EF6 DLL in GAC missing). It is a limitation of MySQL Connector 9.2.0.

When SafeNet Agent for Keycloak is configured with SAS using MySQL database, perform the following steps:

1. Click here to download the mysql.data.entityframework.9.2.0 nuget package. This library is freely available from Oracle’s MySQL website and must be used in compliance with the GPL-2.0 license. Ensure to understand the GPL-2.0 obligations before using this library.
2. Change the extension of the downloaded package from .nupkg to .zip by renaming the package.
3. Extract the package mysql.data.entityframework.9.2.0.zip.
4. Open the extracted folder, navigate to lib > net462 > MySql.Data.EntityFramework.dll, and copy the complete path of this DLL file. It will be required in the next step.

5. Copy the following text in a text file and save the file in the .ps1 file format. Also check and update the DLL path as per the above step:

   # Note that you should be running PowerShell as an Administrator
[System.Reflection.Assembly]::Load("System.EnterpriseServices, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")
$publish = New-Object System.EnterpriseServices.Internal.Publish
$publish.GacInstall("C:\Downloads\mysql.data.entityframework.9.2.0\lib\net462\MySql.Data.EntityFramework.dll")
# If installing into the GAC on a server hosting web applications in IIS, restart IIS for changes to take effect
iisreset

6. Run the .ps1 file as an administrator in the PowerShell.

7. To validate whether your script runs successfully, go to C:\Windows\Microsoft.NET\assembly\GAC_MSI and verify that MySql.Data.EntityFramework folder is created after execution of the above script.

   

Points to remember

• Default location:
  System Directory:\Downloads\mysql.data.entityframework.9.2.0\lib\net462 (Assuming it will be the path of your directory where the nuget package is downloaded)

  

• 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.

Set up of SAS PCE is required for end-to-end setup and validation for a STA Hybrid environment.