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.

Caution

SAS API is not supported with SAS configured on PostgreSQL. Hence SafeNet Agent for Keycloak setup with SAS user federation does not work. But LDAP user federation works.

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.

Note

For more details, refer to https://www.keycloak.org/docs/26.0.7/release_notes/#keycloak-24-0-5.

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

Caution

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

Note

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

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

1. Install SafeNet server.
2. Install MySQL 8.0.32 connector.
3. Configure SafeNet server with MySQL database.
4. Save the following text in .ps1 file format:
   
   #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:\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
   
5. Run the .ps1 file, as an administrator in the PowerShell.
6. 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 the directory location changes while installing the MySQL connector, the path for the default location must also 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.

Note

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