Keycloak + JAS + IBM RSE — OIDC Integration (Step-by-step)

Last updated: 2026-02-07

0. What this setup does

IBM RSE is registered to JAS. JAS is configured to use Keycloak as a 3rd-party OpenID Connect (OIDC) Identity Provider. When a user opens IBM RSE, they get redirected to JAS, then to Keycloak for login. Keycloak authenticates the user and sends an ID token back to JAS. JAS validates the token and maps the user to the LDAP registry using the uid attribute. After that, access to IBM RSE works normally.

0.1 Placeholders to replace

Replace these placeholders to match your environment:

• <KEYCLOAK_HOST> (Keycloak hostname/FQDN; must match certificate CN/SAN)
• <KEYCLOAK_HTTPS_PORT> (Keycloak HTTPS port; example: 8443)
• <REALM> (Keycloak realm name; example: JAS)
• <CLIENT_ID> (Keycloak client ID used by JAS; example: jas-client)
• <CLIENT_SECRET> (Keycloak client secret from Keycloak → Client → Credentials)
• <JAS_HOST> (JAS hostname/FQDN)
• <OIDC_LOGIN_ID> (oidcLogin id in JAS appConfig.xml; example: keycloak)
• <KEYCLOAK_CONTAINER> (Docker container name; example: keycloak)
• <JAS_SERVER_DIR> (JAS Liberty server dir; example: C:\...\wlp\usr\servers\<SERVER_NAME>)
• <CERT_PATH> (path to keycloak.crt on the JAS machine)
• <TRUSTSTORE_PATH> (truststore path used by JAS/Liberty)
• <TRUSTSTORE_PASSWORD> (truststore password)

Config files are typically under <JAS_SERVER_DIR>. Replace <SERVER_NAME> with your server name (for example: jazzop).

1. Authentication flow diagram

User → IBM RSE → JAS → Keycloak → JAS → IBM RSE

Figure 1 — OIDC redirect flow between IBM RSE, JAS and Keycloak

2. Install Keycloak (Docker)

2.1 Run Keycloak in dev mode (HTTP)

docker run -p 8080:8080   -e KEYCLOAK_ADMIN=admin   -e KEYCLOAK_ADMIN_PASSWORD=admin   quay.io/keycloak/keycloak:latest start-dev

Open: http://<KEYCLOAK_HOST>:8080

2.2 Create a self-signed certificate for HTTPS

mkdir -p /root/certs

openssl req -x509 -nodes -days 365   -newkey rsa:2048   -keyout /root/certs/keycloak.key   -out /root/certs/keycloak.crt   -subj "/CN=<KEYCLOAK_HOST>"

2.3 Run Keycloak with HTTPS enabled

docker run -p <KEYCLOAK_HTTPS_PORT>:<KEYCLOAK_HTTPS_PORT>   -e KC_BOOTSTRAP_ADMIN_USERNAME=admin   -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin   -v /root/certs/keycloak.crt:/opt/keycloak/conf/tls.crt   -v /root/certs/keycloak.key:/opt/keycloak/conf/tls.key   quay.io/keycloak/keycloak:latest   start --https-certificate-file=/opt/keycloak/conf/tls.crt         --https-certificate-key-file=/opt/keycloak/conf/tls.key         --hostname=<KEYCLOAK_HOST>         --https-port=<KEYCLOAK_HTTPS_PORT>

Open: https://<KEYCLOAK_HOST>:<KEYCLOAK_HTTPS_PORT>

3. Configure Keycloak (Realm + Client)

3.1 Create a realm

• Create a realm named <REALM> (example: JAS).

3.2 Create an OIDC client for JAS

• Client ID: <CLIENT_ID> (example: jas-client)
• Client authentication: ON (confidential client)
• Valid Redirect URI: https://<JAS_HOST>/ibm/api/social-login/redirect/<OIDC_LOGIN_ID>
• Web origins: https://<JAS_HOST> (or * for test only)

Figure 2 — Keycloak Client Settings showing Redirect URI / Web Origins

3.3 Copy the client secret

• Go to Clients → <CLIENT_ID> → Credentials and copy the Client Secret as <CLIENT_SECRET>.

Figure 3 — Keycloak Client Credentials showing Client Secret

3.4 Use the well-known configuration URL to get endpoints

To populate appConfig.xml endpoints, open the well-known configuration URL and copy values from the JSON.

https://<KEYCLOAK_HOST>:<KEYCLOAK_HTTPS_PORT>/realms/<REALM>/.well-known/openid-configuration

Useful JSON keys: authorization_endpoint, token_endpoint, jwks_uri, issuer

4. Match Keycloak token with JAS LDAP (uid mapping)

JAS maps the authenticated user to LDAP using uid. So the Keycloak token must include a claim called uid. If uid is missing, JAS can fail with: CWWKS1738E.

4.1 Enable uid attribute in Keycloak user profile (new UI)

1. Realm settings → User profile
2. Create attribute named uid
3. Save

Figure 4 — Realm settings → User profile showing uid attribute

4.2 Create/Update user in Keycloak and set UID

1. Users → Create user (or open existing user)
2. Set Username to match LDAP uid
3. Set UID field/value to match LDAP uid (example: elmadmin)
4. Save

Figure 5 — Keycloak user details showing UID value

4.3 Add mapper so uid is included in the token

1. Clients → <CLIENT_ID> → Client scopes
2. Open <CLIENT_ID>-dedicated
3. Mappers → Add mapper
4. Mapper type: User Attribute
5. User attribute: uid
6. Token claim name: uid
7. Add to ID token: ON; Add to access token: ON
8. Save

Figure 6 — Client scopes screen showing the dedicated scope

Figure 7 — Dedicated scope showing uid mapper (User Attribute)

4.4 LDAP reference

LDAP uid must match the uid/username used in Keycloak.

Figure 8 — Example LDAP entry where uid is used as the user identifier

5. Trust Keycloak certificate in JAS

Required when Keycloak uses a self-signed certificate. This prevents SSL handshake errors between JAS and Keycloak.

5.1 Export Keycloak certificate from Docker (Linux host)

# On the Keycloak host

docker exec -it <KEYCLOAK_CONTAINER> bash

# Inside the container
cat /opt/keycloak/conf/tls.crt > /tmp/keycloak.crt
exit

# Copy cert from container to host
docker cp <KEYCLOAK_CONTAINER>:/tmp/keycloak.crt /tmp/keycloak.crt

# Copy /tmp/keycloak.crt to the JAS machine (SCP / file copy)

5.2 Import certificate into JAS/Liberty truststore (Windows example)

keytool -import -trustcacerts ^
 -alias keycloak ^
 -file <CERT_PATH> ^
 -keystore "<TRUSTSTORE_PATH>" ^
 -storepass <TRUSTSTORE_PASSWORD>

Restart JAS after importing the certificate.

6. Configure JAS (appConfig.xml)

File location: <JAS_SERVER_DIR>\appConfig.xml (example format: C:\...\wlp\usr\servers\<SERVER_NAME>\appConfig.xml). Replace <SERVER_NAME> with your server name.

<oidcLogin id="<OIDC_LOGIN_ID>" displayName="OIDC Login"
      clientId="<CLIENT_ID>"
      clientSecret="<CLIENT_SECRET>"
      authorizationEndpoint="https://<KEYCLOAK_HOST>:<KEYCLOAK_HTTPS_PORT>/realms/<REALM>/protocol/openid-connect/auth"
      tokenEndpoint="https://<KEYCLOAK_HOST>:<KEYCLOAK_HTTPS_PORT>/realms/<REALM>/protocol/openid-connect/token"
      jwksUri="https://<KEYCLOAK_HOST>:<KEYCLOAK_HTTPS_PORT>/realms/<REALM>/protocol/openid-connect/certs"
      issuer="https://<KEYCLOAK_HOST>:<KEYCLOAK_HTTPS_PORT>/realms/<REALM>"
      scope="openid profile email"
      userNameAttribute="uid"
      mapToUserRegistry="true">
</oidcLogin>

Keycloak client Valid Redirect URI must include:

https://<JAS_HOST>/ibm/api/social-login/redirect/<OIDC_LOGIN_ID>

7. Configure JAS (server.xml and LDAP registry)

server.xml location: <JAS_SERVER_DIR>\server.xml (example format: C:\...\wlp\usr\servers\<SERVER_NAME>\server.xml).

ldapUserRegistry.xml location (if separate): <JAS_SERVER_DIR>\ldapUserRegistry.xml (example format: C:\...\wlp\usr\servers\<SERVER_NAME>\ldapUserRegistry.xml).

7.1 Enable required Liberty features in server.xml

<featureManager>
    <feature>openidConnectServer-1.0</feature>
    <feature>jdbc-4.0</feature>
    <feature>appSecurity-2.0</feature>
    <feature>ldapRegistry-3.0</feature>
    <feature>localConnector-1.0</feature>
    <feature>socialLogin-1.0</feature>
    <feature>ssl-1.0</feature>
</featureManager>

7.2 LDAP registry (uid-based) example

<ldapRegistry ldapType="Custom" baseDN="dc=jazz,dc=com" host="<LDAP_HOST>"
      id="<LDAP_HOST>:<LDAP_PORT>" ignoreCase="true" port="<LDAP_PORT>"
      realm="<LDAP_REALM>" recursiveSearch="true" sslEnabled="false">

    <customFilters
        groupFilter="(&(cn=%v)(|(objectclass=groupOfUniqueNames)(objectclass=posixGroup)))"
        groupIdMap="*:cn"
        groupMemberIdMap="groupOfUniqueNames:uniquemember"
        userFilter="(&(uid=%v)(objectclass=inetOrgPerson))"
        userIdMap="*:uid" />
</ldapRegistry>

8. Troubleshooting

8.1 CWWKS1738E: claim [uid] was not included in the token

• Cause: JAS expects uid (userNameAttribute=uid) but Keycloak token did not include uid.
• Fix: Add uid attribute to the Keycloak user and add the uid mapper in the dedicated client scope.

8.2 Redirect URI invalid / mismatch

• Fix: Ensure Keycloak client has the exact redirect URI: https://<JAS_HOST>/ibm/api/social-login/redirect/<OIDC_LOGIN_ID>

8.3 SSL handshake errors between JAS and Keycloak

• Fix: Import the Keycloak certificate into the JAS truststore (Section 5) and restart JAS.

Document prepared for internal use. Replace placeholders for your environment before running any commands.