Integrations using Keycloak

This section will walk you through various integrations for SAS PCE using Keycloak IDP and Keycloak Agent.

Certificate Based Authentication Support

Thales’s SafeNet portfolio of certificate-based tokens offers strong multi-factor authentication in a traditional token form factor, enabling organizations to address their PKI security needs.

This section provides details on the usage of certificate based authentication (CBA) with SAS PCE in conjunction with SafeNet Keycloak Agent, where applications are configured to use SAS Keycloak instance as the primary IDP.

A typical CBA workflow includes:

1. Client sends an authentication request over SSL/TLS channel.
2. During the SSL/TLS handshake, the server and the client exchange their x.509 certificates.
3. The Keycloak validates the client certificate.
4. The user is redirected to SAS for authentication.
5. After successful authentication, the user is redirected to the end application.

To configure CBA with SAS PCE, follow the steps mentioned below:

1. Configure Prerequisites
2. Add an Issuing CA to the Keycloak Trust Store
3. Keycloak Tenant Configuration to enable CBA
4. Extract User Identifiers from Client Certificate
5. Test the CBA User Flow

Configure Prerequisites

• Ensure the Keycloak server version is 22.0.5 or below along with the latest SafeNet Keycloak Agent installed on the machine.

• To enable CBA, you need to add at least one certificate chain from an issuing certificate authority (CA) to your trust store in Keycloak. The trust store lists the certificate chains from the CAs that your organization trusts for the authentication of your users. Adding an issuing CA establishes a trust relationship that the system relies on to verify the authenticity of your users when they authenticate through SAS Keycloak instance.

• TLS/SSL certificate and key file in PEM format.

Supported Certificate Types

The certificates must meet the following conditions:

• The certificates are configured for client authentication (ISO OID code 1.3.6.1.5.5.7.3.2).
• For Chrome, Internet Explorer, and Microsoft Edge browsers on Windows, certificate containers are managed by Microsoft Cryptographic Application Programming Interface (MS-CAPI) middleware.
• For Firefox browsers, certificate containers are managed by PKCS#11 middleware.
• For Safari browsers on macOS, certificates are configurable in the Keychain Access app.

There are usability limitations on Firefox and Safari browsers due to the browser’s implementation of TLS authentication and the associated certificate handling. For example, on these browsers, the user may not be prompted to insert their smart card.

Add an Issuing CA to the Keycloak Trust Store

To validate client certificates and enable the certificate based authentication methods, you need to create a trust store with all the certificates chains (intermediate and root) that the Keycloak should trust. Follow the below sub-sections to add and configure the TLS/SSL certificate and the issuing CA certificate to the Keycloak trust store.

Create a new Trust Store

You can use the Java keytool utility that is provided in the JDK installation directory to create a trust store file, as shown in the following steps:

1. Open command prompt, go to <JDK Home Directory>/bin directory.

2. Execute the below command to generate a trust keystore file in .jks format.

   keytool -import -alias <Alias name> -file <CA Cert file>.crt-keystore <Trust Store file>.jks

   Where,

   Alias name is a unique name which can be set as per your preference.
   CA Cert file is the path of issuing CA certificate file in .crt format.
   Trust Store file is the path where you wish to create the trust store file in .jks format.

   

3. Set the password as per your preference.

4. Press Y to trust the certificate.

   This process creates the trust store file in the current directory.

   Ensure the trust store file generated in the above step is located in Keycloak conf directory: <Path of Keycloak Directory>/conf/<Trust Store File>.jks

Configure TLS/SSL certificate and Trust Store in Keycloak

You need to configure the TLS/SSL certificate and trust store containing the issuing CA in Keycloak.

Follow the below steps to configure the trust store:

1. Go to the conf folder located in the Keycloak directory.

   For example: <Path of Keycloak Directory>/conf

2. Open keycloak.conf file in a text editor and add below parameters:

   https-certificate-file: The file path to TLS/SSL certificate in PEM format.

   https-certificate-key-file: The file path to TLS/SSL certificate private key in PEM format.

   https-client-auth: Enter the value as request.

   https-trust-store-file: The path of the trust store file which holds the certificate information of the issuing CA certificates to trust.

   https-trust-store-password: The password of the trust store file.

   For more information, refer to https://www.keycloak.org/server/enabletls.

   

3. Restart the Keycloak server.

Keycloak Tenant Configuration to enable CBA

To enable CBA, you have to add a new authenticator in your Keycloak realm.

Follow the steps mentioned below to add a new authenticator for CBA:

1. Login to Keycloak Admin console.

   Ensure the admin console is based on old theme.

2. In the left pane, select your desired realm.

   

3. In the left pane, click Authentication. Under the Flows tab, click the three vertical dots in front of Safenet OTP Flow and select the Duplicate option to copy the flow.

   Duplicate Flow pop-up is displayed.

   

4. In the pop-up, enter the name and description of the flow. For example: Safenet OTP flow with CBA.

   

5. Click Duplicate.

6. Now, click the Add step button. A pop-up is displayed, search for X509/Validate Username Form and click Add to save the form.

   

7. Mark X509/Validate Username Form as Alternative and move it above SafeNet OTP Flow Forms as shown below:

   Ensure SafeNet OTP Flow Forms is also marked as Alternative. By configuring this setting, if the end user is accessing the application from a device which doesn’t have the company provided smart card (client certificate) then the user will be asked for OTP based authentication instead of CBA based authentication.

   

8. Select the setting button (highlighted in the below image) and perform the following steps in the X509/Validate Username Form config window:

   1. In the Alias field, enter the name of the configuration. For example: pki-config.

   2. In the User Identity Source field, select the unique identity source which will extract the user identity from X509 Certificate. For example: Subject’s email.

      This mapping can vary between customer depending on their CA - user certificate profiles.

   3. In the User mapping method field, select Username or Email.

   4. Ensure Check certificate validity option is ON.

   5. Click Save.

      

9. Click the CBA flow, select Bind flow from the Action drop-down.

   

10. In the Bind Flow pop-up, select the instance that you have created from the Browser flow field, and click Save.

Extract User Identifiers from Client Certificate

You need to create the client certificate using the issuing CA certificate that you have configured as a trust store in Add an issuing CA to the Keycloak trust store section.

While creating the client certificate, ensure that the user has the same username and email address in Keycloak and SAS PCE as provided for common name and email address in the certificate.

For example, for the user with the username as test.user and email address as test.user@example.com, the user details in Client Certificate, Keycloak Agent and SAS PCE will appear as shown in the pictures below.

Client Certificate

Keycloak User

SAS PCE User

Test the CBA User Flow

To test the CBA authentication, you need to install the client certificate where the authentication needs to happen. You need to install the .pfx client certificate in the Certificate Manager under Personal > Certificate.

Ensure the browser is able to fetch the above certificate details.

Follow the steps mentioned below to test the authentication:

1. Access the application URL that you have configured as client in your Keycloak Realm. For example:

   https://<Your Domain Name>:8443/auth/realms/<Realm Name>/account

   

2. Select the client certificate and click OK.

   

3. Click on Sign In. You will be redirected to SafeNet Authentication Service page that will display the user attributes fetched from the client certificate. Then, click on Continue button if the information is valid.
   However, you can choose the authentication method based on your requirement.

4. After successful authentication, you will be redirected to the application.