IBM Support

Single Sign-On (SSO) Authentication Configuration using LDAP, OIDC, and SAML

How To


Summary

This technote provides a comprehensive guide to configure Single Sign-On (SSO) authentication for HCL Workload Automation, specifically for the Dynamic Workload
Console (DWC) and Master Domain Manager (MDM).

Objective

Outlines three primary methods for SSO integration: LDAP-based login, OpenID Connect (OIDC) federated login, and SAML (2.0) with optional MicroProfile-JWT support.
Each authentication method is configured independently and requires modifying Liberty's server.xml and related files. This documentation offers detailed instructions for configuration, validation, and troubleshooting for each approach, incorporating best practices and XML examples to facilitate the setup process.
diagram

Environment

This is applicable to any IWS version. 

Steps

LDAP Authentication Configuration
 
LDAP login uses an external directory (such as Active Directory or OpenLDAP) as the user registry for DWC/MDM. In Liberty, enable the LDAP registry and security features, then configure the directory settings. For example, add the appSecurity and ldapRegistry features to server.xml:
<featureManager>
    <feature>appSecurity-2.0</feature>
    <feature>ldapRegistry-3.0</feature>
</featureManager>
 Next define the LDAP connection. An example snippet (for IBM Directory Server) might look like:
<ldapRegistry id="ldap" realm="ExampleRealm"
    host="ldap.example.com" port="389" ignoreCase="true"
    baseDN="o=example,c=com"
    ldapType="IBM Tivoli Directory Server"
    bindDN="cn=admin,o=example,c=com"
    bindPassword="password">
    <idsFilters
        userFilter="(&(uid=%v)(objectclass=person))"
        groupFilter="(&(cn=%v)(objectclass=group0fNames))"
        userIdMap="*:uid" groupIdMap="*:cn" />
</ldapRegistry>
The attributes depend on your directory: use baseDN for the search base, bindDN / bindPassword for a service account, and appropriate userFilter and groupFilter for your schema. For Active Directory or OpenLDAP, adjust ldapType and filters accordingly.
After saving the configuration, put the updated server.xml into configDropins/overrides on both DWC and MDM so they share the same user registry.
Note: The DWC and MDM must use the same user registry for SSO. If using LTPA tokens or Liberty SSO, ensure the ltpa.keys files are identical on both servers.
Finally, assign DWC roles to your LDAP users or groups. In the Dynamic Workload Console's Manage Workload Security panel, add the LDAP group or user to a role (e.g. FULLCONTROL on Domain and root Folder). This ensures LDAP-authenticated users have the right permissions in DWC.
Validation:
1.) Test by starting Liberty, then logging into DWC with an LDAP account.
2.) Check that authentication succeeds and that you see DWC pages.
3.) If login fails, examine the Liberty console logs for errors (e.g. connection refused, bind failure, or user not found).
Common issues include wrong baseDN or missing LDAP filters. Verify the LDAP server is reachable (hostname/port) and the bindDN can authenticate. You can also enable debug security logs in Liberty to trace authentication.
OpenID Connect (OIDC) Authentication Configuration
OpenID Connect allows DWC/MDM to delegate login to an OAuth2/OIDC Identity Provider (such as Okta, Keycloak, Azure AD, etc.). In Liberty, use the openidConnectClient feature. For example, add to server.xml:
<featureManager>
    <feature>openidConnectClient-1.0</feature>
</featureManager>

<authFilter id="restFilterOpenID">
     <requestUrl id="restUrl" urlPattern="jwt/ibm/api/dwc/rest/roles|/metrics" matchType="notContain"/>
</authFilter>

<openidConnectClient id="oidcProvider"
    clientId="WA_CLIENT_ID"
    clientSecret="WA_CLIENT_SECRET"
    httpsRequired="true"
    userIdentifier="preferred_username"
    signatureAlgorithm="RS256"
    scope="openid"
    authFilterRef="restFilterOpenID"
    inboundPropagation="supported"
    groupIdentifier="groups"
    redirectToRPHostAndPort="https://<dwc_host>:<port>" 
    discoveryEndpointUrl="https://<oidc_host>/.well-known/openid-configuration"/>
Here, set clientId and clientSecret as issued by your IdP, and replace <dwc_host> and <oidc_host> with your actual hostnames. The discoveryEndpointUrl points to the OIDC issuer's metadata (replace with your realm or tenant endpoint). The authFilter typically allows certain REST URLs to bypass OIDC. Place this file under configDropins/overrides so Liberty picks it up.
Next, configure the IdP itself to trust the application. For example, in Okta or Keycloak, create a new OIDC Client (Redirect URI e.g. https://<dwc_host>/callback).
After updating server.xml, restart DWC and MDM. Then access the DWC URL; you should be redirected to the Identity Provider's login page.
Log in as an OIDC user. Upon successful login, Liberty will receive an ID token, map the preferred_username to a subject, and use the groups claim for roles.
Validation:
1.) Confirm that login redirects to the IdP and back, and that you enter DWC authenticated.
2.) Verify in Liberty logs or the DWC Logon page that the user name is coming from OIDC.
3.) If authentication fails, check the OIDC client configuration and Liberty logs.
Common issues include mismatched redirect URL, invalid client secret, or incorrect discovery URL. You can use external tools (e.g. JWKS URLs) to verify the OIDC metadata and keys. If users lack permissions in DWC, assign their group(s) to roles as described above.
SAML Web SSO and JWT Authentication Configuration
This section covers SAML 2.0 SSO (where Liberty acts as a SAML Service Provider) and MicroProfile-JWT (MP-JWT) token authentication. In Liberty, enable the SAML feature and configure SP settings, then handle JWT as needed.
Liberty Features:
Enable the SAML Web SSO feature and (optionally) the MP-JWT feature in server.xml. For example:
<featureManager>
    <feature>appSecurity-2.0</feature>
    <feature>samlWeb-2.0</feature>
    <feature>mpJwt-1.2</feature>
</featureManager>
Disable Default SP:
Liberty has a default SAML SP instance (defaultSP). If you create a custom SP, explicitly disable defaultSP. For example:
<samlWebSso20 id="defaultSP" enabled="false"/>
SAML SP Configuration:
Define your SP instance with its key and IdP metadata. Example:
<keyStore id="samlKeyStore"
    location="keystore.jks" password="password"/>
<samlWebSso20 id="workloadSP"
    keyStoreRef="samlKeyStore" keyAlias="samlKey"
    trustStoreRef="samlKeyStore"
    idpMetadata="${server.config.dir}/idpMetadata.xml"
    mapToUserRegistry="Group/User/No"
    realmName="******"/>
Place the IdP's metadata file (commonly named idpMetadata.xml) in the server's resources/security directory. The mapToUserRegistry attribute specifies if the identity in the SAML token should be mapped to a "User" or "Group" in the local registry, or if "No" mapping should occur, while the realmName attribute defines a specific realm for the configuration.
The SP's Assertion ConsumerService URL will be https://<dwc_host>:<port>/ibm/saml20/workloadSP/acs (Liberty constructs this from the id you give). In the IdP configuration (e.g. ADFS, Okta, etc.), set the SP metadata endpoint or ACS URL accordingly. Also ensure the Liberty keystore contains the SP's private key (alias "samlKey" above) and trusts the IdP's certificate.
MicroProfile-JWT (optional):
If your SAML IdP or other system issues JWTs for SSO, enable the mpJwt feature and configure it. For example:
<mpJwt id="mympjwt"
    issuer="https://idp.example.com"
    jwksUri="https://idp.example.com/.well-known/jwks.json"/>
<keyStore id="defaultKeyStore" password="changeit"/>
The issuer is the expected token issuer, and jwksUri points to the JSON Web Key Set used to verify signatures. Liberty will validate inbound JWTs against this config.
DWC/MDM Settings:
After configuring SAML/JWT in Liberty, restart servers. Users are now authenticated via SAML or JWT instead of the local registry. Assign DWC roles to the SAML/JWT principals or groups as with other methods. (For example, map SAML NameID or JWT sub claim to a user or group in DWC's security manager and give it FULLCONTROL on Domain/Folder).
Validation:
1.) To test SAML SSO, browse to DWC and you should be redirected to the Identity Provider's login page.
2.) Log in at the IdP, then confirm you land in DWC as an authenticated user.
3.) Check Liberty's messages.log to ensure the SAML assertion was consumed (e.g. look for assertions or subject names).
4.) For JWT, you can test by accessing an endpoint with an Authorization: Bearer <token> header; Liberty will accept it if signed by your IdP.
Troubleshooting:
Common issues include certificate or metadata mismatches. Verify the SAML IDP has the correct SP metadata and that idpMetadata.xml matches the IdP.
Ensure clocks are in sync (time skew can invalidate SAML tokens). If Liberty logs show SAML errors, enable higher debug logging (audit, verity) in the Liberty server.xml.
For JWT, ensure the token's iss and signature are correct per your mpJwt settings, and that the JWKS URL is reachable. Finally, if users still see a login prompt, re-check the defaultSP enabled="false" setting and the correctness of the SP configuration.

Additional Information

Example Codes and Settings Summary
In summary, here are key XML snippets (modify values for your environment):
LDAP (server.xml):
<featureManager>
    <feature>appSecurity-2.0</feature>
    <feature>ldapRegistry-3.0</feature>
</featureManager>

<ldapRegistry id="ldap" realm="ExampleRealm"
    host="ldap.example.com" port="389" ignoreCase="true"
    baseDN="o=example,c=com"
    ldapType="IBM Tivoli Directory Server"
    bindDN="cn=admin,o=example,c=com"
    bindPassword="password">
    <idsFilters
        userFilter="(&(uid=%v)(objectclass=person))"
        groupFilter="(&(cn=%v)(objectclass=group0fNames))"
        userIdMap="*:uid" groupIdMap="*:cn" />
</ldapRegistry>
OpenID (server.xml):
 
<featureManager>
    <feature>openidConnectClient-1.0</feature>
</featureManager>

<authFilter id="restFilterOpenID">
    <requestUrl id="restUrl" urlPattern="jwt/ibm/api/dwc/rest/roles|/metrics"
matchType="notContain"/>
</authFilter>

<openidConnectClient id="oidcProvider"
    clientId="WA_CLIENT_ID"
    clientSecret="WA_CLIENT_SECRET"
    httpsRequired="true"
    userIdentifier="preferred_username"
    signatureAlgorithm="RS256"
    scope="openid"
    authFilterRef="restFilterOpenID"
    inboundPropagation="supported"
    groupIdentifier="groups"
    redirectToRPHostAndPort="https://<dwc_host>:<port>"
    discoveryEndpointUrl="https://<oidc_host>/.well-known/openid-configuration"/>
SAML/JWT (server.xml):
<featureManager>
    <feature>appSecurity-2.0</feature>
    <feature>samlWeb-2.0</feature>
    <feature>mpJwt-1.2</feature>
</featureManager>
<keyStore id="samlKeyStore"
    location="keystore.jks" password="password"/>
<samlWebSso20 id="workloadSP"
    keyStoreRef="samlKeyStore" keyAlias="samlKey"
    trustStoreRef="samlKeyStore"
    idpMetadata="${server.config.dir}/idpMetadata.xml"
    mapToUserRegistry="Group/User/No"
    realmName="******"/>
<mpJwt id="mympjwt" issuer="https://idp.example.com"
    jwksUri="https://idp.example.com/.well-known/jwks.json"/>
<keyStore id="defaultKeyStore" password="changeit"/>
Following these configurations and restarting Liberty will enable the selected SSO method.
Always test logins and consult the Liberty logs for errors. With correct setup, DWC and MDM will use the chosen external authentication seamlessly.

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB77","label":"Automation Platform"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSGSPN","label":"IBM Workload Scheduler"},"ARM Category":[{"code":"a8m0z0000001iVGAAY","label":"Product Operations-\u003EWebSphere-\u003ELDAP"},{"code":"a8m50000000KzZHAA0","label":"Security"}],"ARM Case Number":"TS019142881","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"and future releases;10.1.0;10.2.0;10.2.1;10.2.2;10.2.3;10.2.4;10.2.5;9.5.0"}]

Document Information

Modified date:
03 July 2025

UID

ibm17238664

Page Feedback