SAML authentication with Verify

Edit online

IBM Security Verify can serve as a SAML 2.0 identity provider for Keycloak, enabling centralized user authentication and single sign-on capabilities for IBM® Cyber Fraud applications.

Switching to the cyberfraud realm in Keycloak

Edit online

Access the Keycloak administration console and switch to the cyberfraud realm to configure LDAP user federation.

Before you begin

Ensure that you have access to the Red Hat OpenShift cluster where IBM Cyber Fraud is deployed and that the oc command-line tool is installed and configured.

About this task

The Keycloak console URL and administrator credentials are stored in Red Hat OpenShift secrets. Before configuring LDAP, you must access the Keycloak console and ensure that you are working in the cyberfraud realm.

Procedure

Set the IBM Cyber Fraud namespace by running the following command.
```
export NAMESPACE=<cyberfraud-name>
```

Retrieve the Keycloak console URL by running the following command.

Red Hat OpenShift

oc get route -lapp=keycloak -n $NAMESPACE -o json | jq '.items[]' | jq -r '.spec.host'

Linux

kubectl get httproute -l app=keycloak -n $NAMESPACE  -o json | jq -r '.items[] | .spec.hostnames | join(",")'

The command displays the Keycloak console URL.

Retrieve the Keycloak administrator username by running the following command.

Red Hat OpenShift

oc get secret kc-cyberfraud-admin-credentials -n $NAMESPACE -o jsonpath='{.data.username}' | base64 -d

Linux

kubectl get secret kc-cyberfraud-admin-credentials -n $NAMESPACE -o jsonpath='{.data.username}' | base64 -d

The command displays the administrator username.

Retrieve the Keycloak administrator password by running the following command.

Red Hat OpenShift

oc get secret kc-cyberfraud-admin-credentials -n $NAMESPACE -o jsonpath='{.data.password}' | base64 -d

Linux

kubectl get secret kc-cyberfraud-admin-credentials -n $NAMESPACE -o jsonpath='{.data.password}' | base64 -d

The command displays the administrator password.

Open a web browser and navigate to the Keycloak console URL that you retrieved in step 2.
Log in using the administrator username and password that you retrieved in steps 3 and 4.
From the Keycloak administration console, navigate to Manage realms in the top left of the navigation side panel.
Ensure that you are in the cyberfraud realm.
The current realm name displays in the top left of the navigation side panel.

Results

You are logged in to the Keycloak administration console and are in the cyberfraud realm. You can now proceed with the IdP configuration.

Configuring Verify as a SAML identity provider

Edit online

Configure Verify as a SAML 2.0 identity provider for Keycloak to enable centralized authentication for IBM Cyber Fraud applications.

Before you begin

Ensure you have read the top-level documentation on configuring SAML in Keycloak.
Obtain administrative access to both Verify and Keycloak instances.
Have your Verify tenant URL available; for example, https://uss-vpc01.verify.ibm.com/.

About this task

This procedure guides you through the complete configuration of Verify as a SAML identity provider in Keycloak, including metadata exchange, attribute mapping, and entitlements configuration.

Procedure

From the Keycloak administration console, in the Configure section, click Identity providers.
On the Identity providers page, click SAML 2.0 to open the Add SAML provider page.

Configure the identity provider alias.


Field	Value	Notes
Redirect URI	Generated by Keycloak	This value is generated by Keycloak and is required in the Verify configuration.
Alias	`verify-saml`	The alias is used in building the redirect URI and is required for onboarding users.
Display name	`Verify SAML`	This value determines how theSAML option appears on the login page.

Keep this page open. You will return to it after configuring Verify.

Open a new browser tab and log in to your Verify instance.
Switch to the admin view by clicking the admin toggle.
Create a custom application in Verify:
1. Click Add application.
  
  Note: If you already have a custom application for your cluster or namespace in this Verify instance, you can edit the existing application instead of creating a new one.
2. On the General tab, provide a name for the application.
  
  A recommended naming convention is to use the cluster and namespace, for example, clx001-cyberfraud. Enter IBM in the company name field.
3. Click the Sign-on tab.
4. Select both User unique ID and Use identity provider initiated single sign-on checkboxes.
5. Scroll down to locate the metadata URL message that reads "If the Use unique ID check box is selected, the metadata URL is:".
6. Download the federation metadata file to your local machine.
Switch back to the Keycloak browser tab.
Set Use entity descriptor to off.
Upload the federation metadata file that you downloaded from Verify.

If the upload is successful, the fields in Keycloak are automatically populated with values from the metadata file.
Locate the Want AuthnRequests signed toggle and enable the option.
Scroll down and click Add.
Copy both the Redirect URI and Service provider entity ID values from Keycloak.

Note: The XML metadata provided by Keycloak when you click Endpoint causes an error in Verify. Instead, manually populate the required fields in Verify.
Switch back to the Verify browser tab.
Clear the Use metadata checkbox.
Populate the following fields with the values copied from Keycloak:
- In the Provider ID field, paste the Service provider entity ID value.
- In the Use unique ID field, paste the Redirect URI value.
- In the Single logout URL (HTTP-POST) field, paste the Redirect URI value.
Scroll down to the Attribute mappings section.
Select the Send all known user attributes in the SAML assertion checkbox.
Click Save.

The application is created and the Entitlements tab opens automatically.
Under Access Type, select Automatic access for all users and groups.
Click Save.
An Update workflow dialog box appears asking you to confirm that changing the workflow configuration overrides entitlement-level configurations, deletes existing accesses, and invalidates outstanding requests. Click OK to confirm the change and to update the workflow.

Results

Verify is now configured as a SAML identity provider for Keycloak. You can proceed to create attribute mappers in Keycloak to synchronize user attributes.

What to do next

After completing this configuration:

Create attribute mappers in Keycloak to map Verify user attributes to Keycloak user attributes. See Creating Keycloak mappers for the IdP.
Configure SAML logout to enable proper session termination. See Configuring SAML logout.
Import Verify users into Keycloak. See Importing Verify users into Keycloak.

Creating Keycloak mappers for the IdP

Edit online

Create attribute mappers in Keycloak to synchronize user attributes from the IdP SAML assertions to Keycloak user profiles.

Before you begin

Complete the SAML identity provider configuration in Keycloak.
Ensure the IdP is configured to send all known user attributes in the SAML assertion.

About this task

Keycloak mappers define how SAML attributes from the IdP are imported and stored in Keycloak user profiles. You must create six mappers to properly synchronize user information: Broker ID, Broker Username, Email, Username, First Name, and Last Name.

Procedure

From the Keycloak administration console, navigate to the identity provider configuration.
Click the Mappers tab.
Click Add mapper.

Create the mappers with the information in the following tables:

Table 1. Broker ID mapper configuration
Field	Value	Notes
Name	`Broker Id`	Visual name of the mapper in Keycloak.
Sync mode override	`import`	Select from dropdown.
Mapper type	`Username Template Importer`	Select from dropdown.
Template	`${ATTRIBUTE.uid}`	References the uid SAML attribute.
Target	`BROKER_ID`	Select from dropdown.

Table 2. Broker Username mapper configuration
Field	Value	Notes
Name	`Broker Username`	Visual name of the mapper in Keycloak.
Sync mode override	`import`	Select from dropdown.
Mapper type	`Username Template Importer`	Select from dropdown.
Template	`${ATTRIBUTE.email \| lowercase}`	References the email SAML attribute and converts to lowercase.
Target	`BROKER_USERNAME`	Select from dropdown.

Table 3. Email mapper configuration
Field	Value	Notes
Name	`Email`	Visual name of the mapper in Keycloak.
Sync mode override	`inherit`	Select from dropdown.
Mapper type	`Attribute Importer`	Select from dropdown.
Attribute Name	`email`	Must reference the SAML attribute name from the IdP.
Name Format	`ATTRIBUTE_FORMAT_BASIC`	Select from dropdown.
User Attribute Name	`email`	Name of the attribute in Keycloak.

Table 4. Username mapper configuration
Field	Value	Notes
Name	`Username`	Visual name of the mapper in Keycloak.
Sync mode override	`inherit`	Select from dropdown.
Mapper type	`Attribute Importer`	Select from dropdown.
Attribute Name	`email`	Must reference the SAML attribute name from the IdP.
Name Format	`ATTRIBUTE_FORMAT_BASIC`	Select from dropdown.
User Attribute Name	`username`	Name of the attribute in Keycloak.

Table 5. First Name mapper configuration
Field	Value	Notes
Name	`First Name`	Visual name of the mapper in Keycloak.
Sync mode override	`Force`	Select from dropdown.
Mapper type	`Attribute Importer`	Select from dropdown.
Attribute Name	`given_name`	Must reference the SAML attribute name from the IdP.
Name Format	`ATTRIBUTE_FORMAT_BASIC`	Select from dropdown.
User Attribute Name	`firstName`	Name of the attribute in Keycloak.

Table 6. Last Name mapper configuration
Field	Value	Notes
Name	`Last Name`	Visual name of the mapper in Keycloak.
Sync mode override	`Force`	Select from dropdown.
Mapper type	`Attribute Importer`	Select from dropdown.
Attribute Name	`family_name`	Must reference the SAML attribute name from the IdP.
Name Format	`ATTRIBUTE_FORMAT_BASIC`	Select from dropdown.
User Attribute Name	`lastName`	Name of the attribute in Keycloak.

Click Save.

Results

All six mappers are now configured. When users authenticate through the IdP, their attributes are automatically synchronized to their Keycloak user profiles.

What to do next

After creating the mappers:

Verify that the SAML attribute names match those provided by the IdP. You can view available attributes in the IdP interface.
Test the SAML authentication flow to ensure user attributes are properly synchronized.

Configuring SAML logout

Edit online

Configure SAML logout to enable Verify to validate logout requests from Keycloak and properly terminate user sessions.

Before you begin

Complete the Verify SAML identity provider configuration in Keycloak.
Ensure you have administrative access to both Keycloak and Verify.

About this task

To enable SAML logout, Verify must validate that logout requests are not forged. This validation requires uploading Keycloak's signer certificate to Verify and configuring the custom application to reference it.

Procedure

From the Keycloak administration console, navigate to Realm Settings > Keys.
Locate the Certificate entry for the rsa-generated certificate.
Click the certificate to view its details.
Copy the certificate content to your clipboard.
Create a new file on your local machine with a .pem extension.
Paste the certificate content into the file and save it.
Log in to Verify and navigate to Security > Certificates.
Click Add signer certificate.
Upload the Keycloak certificate PEM file.
Provide a descriptive name for the certificate.

Note: The name you provide is used as a reference when configuring the custom application.
Click Save.
Navigate to your custom application configuration in Verify.
On the Sign-on tab, in the Service provider signer certificate dropdown, select the certificate you added in the previous steps.
Click Save.

Results

SAML logout is now configured. Verify can validate logout requests from Keycloak and properly terminate user sessions.

Importing Verify users into Keycloak

Edit online

Import users from IBM Security Verify into Keycloak to make them discoverable in IBM Cyber Fraud. The current version of Keycloak does not include SCIM support, so users must be manually imported.

Before you begin

Download and install the cfctl tool. For information about cfctl, see Installing the cfctl utility.
Obtain the idp_alias value that you assigned when configuring the identity provider alias.
Obtain your Verify account or tenant URL, for example, https://uss-vpc01.verify.ibm.com/.
Obtain the Verify Client id and Client Secret.

Procedure

From the Verify interface, navigate to Security > API access.
Click the three dots for the admin API client and click Edit.
Scroll down the page to the API credentials section, which contains the Client id and Client Secret.

Run the cfctl command with the following syntax.

cfctl -- import_users_from_idp --tenant <verify-account-url> --idp VERIFY --idp_alias <alias-in-keycloak> --client_id <client-id> --client_secret <client-secret> --users <comma-seperated-list-user-emails>

Replace the placeholder values with your specific configuration:

verify-account-url: Your Verify account URL
alias-in-keycloak: The identity provider alias configured in Keycloak
client-id: Your Verify client ID
client-secret: Your Verify client secret
comma-seperated-list-user-emails: Comma-separated list of user email addresses to import

The tool displays the import results. Successfully imported users are listed, and any users not found in your Verify instance are flagged.

The tool will output what users were successfully imported, and will flag any users not found in your Verify instance.

The following users could not be added as they couldn't be found in the verify instance 'https://qroctest.ice.ibmcloud.com'.
xxx.xxxxx@ibm.com
The following users have been added to keycloak and linked to your idp instance.
xxxxx-xxxxx@ibm.com
xxxxxx.xxxxxx@ibm.com

Results

Note:

Only successfully imported users can be added to the CyberfraudAccount custom resource.
Only successfully imported users can be added to an account in the Cyberfraud user management portal.