Technote: Keycloak support in IBM Sterling Transformation Extender, V10.1.0.1

Keycloak support in IBM Sterling Transformation Extender, V10.1.0.1
----------------------------------------------------------
Introduction
----------------------------------------------------------
Keycloak is an open-source identity and Access Management solution. It is a single sign-on security application for web applications and RESTful web services. Design Server and Runtime REST API supports Keycloak solution  of user administration and authorization.
Existing user databases hold user credentials. Keycloak federates these existing external user databases through the concept of storage providers. By default, Keycloak supports an LDAP and Active Directory storage provider.
When an user tries to access the Design Server Web-console, the browser is redirected to Keycloak authentication system to authenticate user credentials. User gets a reference token from the Keycloak to connect to the server. 
----------------------------------------------------------
Installation
----------------------------------------------------------
See Getting Started guide for installation of Keycloak.
----------------------------------------------------------
User Administration
----------------------------------------------------------
After you install Keycloak, you must consider how the server manages users and authentication.
You can review the default user management provided by the Keycloak server and decide what additional controls you might want to add. If you manage users and authentication through an existing LDAP/AD server, you can review how to use that server to manage users.
----------------------------------------------------------
Default User Administration
----------------------------------------------------------
Keycloak uses the concept of a realm to manage and authenticate users. When you install the Keycloak server, a realm called testserver is created for you in Keycloak. All server users belong to this realm and when they log in to the server, they log into that realm.
As an administrator, it is important to consider the following points about the Keycloak server administration:
  • By default, there is no admin user for Design server.
    Such an admin user is required for accessing additional Design server functions, which includes claiming ownership of Design server projects and unarchiving them. But you can assign administrative privileges to any user. You must do this by adding the admin role to the user in Keycloak. See Getting Started guide for more information
  • If Keycloak authentication is enabled in Design Server, you need to create the admin user or you can synchronize users from LDAP and assign administrative privileges to any user
  • Keycloak does not come with a default admin user. You need to create an admin user before using the Design Server application. To do this open http://localhost:8080/auth, fill the form with your preferred username and password

    After you log in to the Keycloak Admin Console, from the Users page, you can search and select the user that you want to make an administrator. From the Groups tab, you can join the user to the Admin group.

    For more information about assigning user roles, see Groups in the Keycloak documentation.
Now that you are the Keycloak server administrator, it is important to consider the following points about the default user management and authentication:
  • Minimum password length defaults to 8 characters
  • Email verification of new users is turned off
  • The Forgot Password feature is turned on by default, but no instructions are sent to the user to reset their password
  • Forgotten user passwords are changed  by you, if you do not enable Keycloak to send instructions to reset a password
You can review the following sections about changing the default authentication controls.
Email settings:
By default, the testserver realm sets the Forgot Password switch on. However, as an administrator, you must enable Keycloak to send an email to the user with instructions to reset their password. If you want to verify an email, you must also enable Keycloak to send an email to the user to verify their email address.
You must provide SMTP server settings for Keycloak to send an email. After you log in to the Keycloak Admin Console, see Email Settings in the Keycloak documentation.
To set up the email verification, see Forgot Password in the Keycloak documentation.
User password:
Organization can give user access to the account console located at:
https://<keycloak-url>/auth/realms/<realm>/account
There is a form to update password (and other useful information about the account).
See User Credentials in the Keycloak documentation.
User deletion:
When a user is inactive or no longer access to the Design server application, you can delete that user.
See Deleting Users in the Keycloak documentation.
----------------------------------------------------------
Creating a Realm
----------------------------------------------------------
  1. Log in to the Keycloak Admin Console.
  2. Click on the Select realm drop-down and click on Add realm button.
    The Add realm page opens.
  3. Import the realm-export.json file from the the Design server installation directory.
    When you import the realm-export.json, it will automatically configure all the settings of realm. You can edit the configuration settings as required.
  4. Specify the name of realm in the Name field. Default value is itx.
  5. Click on Create button to create a realm.
    The realm is created with the given name.
    Note: To facilitate easy setup, Design server includes the realm-export.json file for Keycloak server. You can modify before import as required for your environment or create your own configuration not using the realm-export.json file that best suits your requirements.
----------------------------------------------------------
Configuring Clients
----------------------------------------------------------
  1. Log in to the Keycloak Admin Console.
  2. Click on Clients option from the Configure property.
    The Clients page opens. User can see the list of application available in the Keycloak.
  3. Click on the design-server-rest client from the list.
    The Design-server-rest page opens.
    When you select the design-server-rest, it will automatically configure all the properties available in the Settings tab.
  4. Go to Credentials tab, click on Regenerate Secret button to create client secret for user.
  5. Go to Roles tab to edit the attributes of respective role, if required.
----------------------------------------------------------
Connecting  Design Server
----------------------------------------------------------
This topic documents how to set up connection between Keycloak and Design server.
  1. Install the Design server to connect to Keycloak.
  2. In Keycloak, make sure that Keycloak Auth Enabled is set to true.
  3. In text editor, open tx-server.env to confirm the connectivity information.
    You can see the below information and update as appropriate to your environment:
    # Flag indicating if keycloak is used for identity & access management
    TX_KEYCLOAK_AUTH_ENABLED=true
    # Keycloak server url
    TX_KEYCLOAK_SERVER_URL=http://localhost:XXXX/auth
    # Keycloak reaml id
    TX_KEYCLOAK_REALM_ID=itx
    # Keycloak client id for making rest calls
    TX_KEYCLOAK_CLIENT_ID=design-server-rest
    # Associated client secret for above client id
    TX_KEYCLOAK_CLIENT_SECRET=94a30704-7694-476c-b9c2-5fb78d151892
  4. Log in to Design Server using Keycloak or LDAP user credentials as configured.
    To unlock the maps if they are locked, go to Administration in Design Server and delete locks held by a user.
----------------------------------------------------------
LDAP User Authentication
----------------------------------------------------------
You are using a Lightweight Directory Access Protocol and Active Directory HTTP server to manage users and authentication. You want to know the best practices to use that LDAP/AD server to manage user access to Design Server.

Design Server uses Keycloak (https://www.keycloak.org/) to manage and authenticate users.
Existing user databases hold user credentials. Keycloak federates these existing external user databases through the concept of storage providers. By default, Keycloak supports an LDAP and Active Directory storage provider. By adding a storage provider, you can map LDAP user attributes into Keycloak. You can also configure more mappings.
Before you configure Keycloak to use an existing LDAP/AD provider, you must consider the following best practices:
  • Set up your LDAP/AD provider as a read-only repository so that Keycloak Server cannot change it
  • Add and remove users in LDAP/AD and not the Keycloak local user database
  • Import and synchronize your LDAP/AD users to your Keycloak local database
    • An import for an LDAP/AD user can fail, if the LDAP/AD field chosen for the username mapping in Keycloak is not filled in for that user in LDAP/AD
    • Filter LDAP/AD users by using the Custom User LDAP Filter, so you can import a subset of all your LDAP users. For example, you can set up a Server user group in LDAP and only import those users to Keycloak
  • Map a login style name, for example, user1@server.com, by using the UserPrincipalName attribute in LDAP/AD to a username in Keycloak. If you want the full name of the user as your login style, use the cn attribute in LDAP/AD
Note: The LDAP/AD user name attribute must match the LDAP/AD provider user name attribute (Username LDAP attribute) in Keycloak for the LDAP/AD provider to connect with Keycloak.
The following sections use these best practices to guide you to set up Keycloak to connect to your LDAP/AD HTTP server.
----------------------------------------------------------
Selecting LDAP provider in Keycloak
----------------------------------------------------------
You can use the Keycloak Admin Console to add an LDAP/AD provider.
  1. Log in to the Keycloak Admin Console.
  2. Go to the User Federation page to add your provider.
  3. Select the provider named ldap from the list from the Add Provider drop-down list.
    The ldap provider is created.
----------------------------------------------------------------------------------------
Required settings for a successful connection to your LDAP/AD provider
-----------------------------------------------------------------------------------------
The form includes many fields and several fields include default values.
  1. Click on the ldap provider to open the settings to configure.
  2. In the Settings tab, select Active Directory from the drop-down list of Vendor. Many fields complete with default values based on this selection.
  3. Enter your LDAP/AD URL to connect to your LDAP/AD user database, for example:
    ldap://<hostname>.<domain>
  4. Click on Test connection button to test the connection and confirm that the connection is successful.
  5. Provide the directory where the LDAP users are listed, for example:
    cn=User,dc=MYCOMPANY,dc=COM.
  6. From the Bind Type drop-down list, select Simple option.
  7. Provide the LDAP/AD user database administrator user ID for BIND DN and password for the BIND Credential. These credentials are used by Keycloak to access the LDAP/AD user database.
  8. Click on Test Authentication button to test the authentication and confirm that the authentication is successful.
  9. Click on Save button to save the configuration.
User synchronization:
You must import all users from your LDAP/AD user database by using the option to Synchronize all users. Users are imported based on your saved settings when you set up your LDAP/AD provider.
A successful import is followed by a success message with the number of users imported. A failed import typically results when there is a mismatch between user attributes in the Keycloak user database and the LDAP/AD user database.
You can view all the LDAP/AD database users that were imported and authenticated from the Users page in the Keycloak Admin Console.
Users are listed with ID, Username, Email, Last Name, and First Name. The ID is generated by Keycloak. The value of the other attributes is fetched from the LDAP/AD user database by using mappers.
Mappers:
Keycloak uses mappers to map the user attributes defined in the Keycloak user model such as username and email to the corresponding user attributes in the LDAP/AD user database. By default, when you saved your settings and created your LDAP/AD provider, the following mappers were created.
The username attribute that you specified in the Username LDAP attribute must match the username attribute defined in the Keycloak mapper for the LDAP/AD user database to connect with Keycloak.
If you changed the Username LDAP attribute from the default value cn to userPrincipalName, Keycloak would make the same change in the mapper called username to match.
----------------------------------------------------------
Runtime REST API
----------------------------------------------------------
Runtime REST API supports Keycloak authentication of user credentials for running maps and flows.
Like Design Server, Runtime REST API can be configured to authenticate users with Keycloak.
Connecting Runtime REST API server:
This topic documents how to set up connection between Keycloak and Runtime REST API server.
  1. Install Design Studio or Runtime & Monitoring.
  2. In Keycloak, make sure that Keycloak Auth Enabled is set to true.
  3. In test editor, open tx-rest.properties to confirm the connectivity information.
    You can see the below information and update as appropriate to your environment:
    #Flag indicating whether Keycloak is enabled for identity & access management
    authntication.keycloak.enabled=true
    #Keycloak specific properties
    authentication.keycloak.serverUrl=http://localhost:8080/auth
    authentication.keycloak.realmId=itx
    authentication.keycloak.clientId=itx-runtime-rest
    authentication.keycloak.clientSecret=9465403f-0ae6-4cfd-98fb-ecdf8c4485ed
  4. Run Runtime REST API server to service REST client calls.
  5. REST clients invoking the Runtime REST API should include the user credentials that can be authenticated with Keycloak to run the maps or flows, or to fetch any runtime information.

Page Feedback