IBM Support

WebSphere application security role mapping to external groups

How To


Summary

When WebSphere is configured SAML web SSO or OIDC SSO, web users are able to accessing applications. These web users and groups are sent from an external SAML identity provider (IdP) or OIDC provider (OP) and might not be part of WebSphere user repositories.

How can we map application security roles to these external users and groups? Since the users and groups are not part of WebSphere user repository, it is not possible to do the mapping from WebSphere Application Server admin console. For example, Applications > Application types > WebSphere enterprise applications > application_name > Security role to user or group mapping.

This can be done by manually editing ibm-application-bnd.xmi or ibm-application-bnd.xml files of application after the application is deployed to WebSphere.

Objective

Mapping application security roles to external groups, which are not part of WebSphere user repository.

Steps

When WebSphere is configured for users to access applications by authenticating with a third party identity provider (like Microsoft Azure), the users and groups from that identity provider might not be part of the WebSphere user registry.  You can access an application on WebSphere via a third party identity provider by using WebSphere's SAML SSO TAI or OIDC TAI.    
If you have an application that requires one or more roles, you can ordinarily do role mapping in the administrative console. For example, Applications > Application types > WebSphere enterprise applications > application_name > Security role to user or group mapping.  However, if the users and groups are not part of WebSphere user registry, you cannot map the roles in WebSphere administrative console.
SSO users and groups are not part of the WebSphere user registry when the TAI is configured to perform identity assertion.  This is the default configuration for both TAIs: sso_(id).idMap=idAssertion for SAML and provider_(id).mapIdentityToRegistry=false for OIDC.
If the users or groups that are retrieved from your identity provider do not map to your WebSphere registry, what do you do?  You can do one of the following, depending the needs of your application:

Assigning groups to security roles in an ibm-application-bnd file

 
image-20240425115156-2 This method does not work to assign groups to admin roles.  Admin roles are required for admin applications, such as the administrative console.  Use the admin-authz.xml method instead.
  1. Find the group accessId
    1. Make sure that you have the appropriate SSO trace enabled, see SSO trace specifications on MustGather: Web Single Sign-on problems with WebSphere Application Server.
      • image-20240425120045-1 Avoid trouble: Make sure to restart the deployment manager or base server after changing the trace specification.
    2. Navigate to your protected URL and perform a successful login with to your identity provider (IdP or OpenId Provider).
      image-20240425115135-1 Because your user does not have the groups that are currently required by the application, your application will not come up.  That's ok.
    3. Open the trace.log file in an editor.
    4. Search the trace for com.ibm.wsspi.security.cred.groups.  You can find an entry like this in the trace:
      [6/15/21 7:20:35:967 CST] 0000013f WebAuthentica 3   TAI [com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor] has been validated successfully.
      [6/15/21 7:20:35:967 CST] 0000013f WebAuthentica 3   Subject retrieved is [Subject:
      Private Credential: {com.ibm.wsspi.security.cred.cacheKey=saml_acs_tai:sso_saml20_1000553865n1302154505, com.ibm.wsspi.security.cred.uniqueId=SAMLRealm/testUser@ibm.com, com.ibm.wsspi.security.cred.realm=SAMLRealm, Saml20TaiSsoPartners=saml_acs_tai:sso_saml20_, com.ibm.wsspi.security.cred.securityName=testUser@ibm.com, com.ibm.wsspi.security.cred.groups=[group:SAMLRealm/myGroup]}
      Private Credential: com.ibm.ws.wssecurity.platform.websphere.wssapi.token.impl.WasSAML20TokenImpl:Wsz8YbUDaeJgb3k4D2DFtJ9
      ]
      • In this sample trace message, the group accessId is: group:SAMLRealm/myGroup. We will use this accessId in the next steps.
      • image-20240425115135-1 If there is no group associated with the user, take note of the uniqueId.
  2. Stop WebSphere processes, including deployment manager (dmgr), node agent, and app servers.
  3. Back up the application's ibm-application-bnd.xmi or ibm-application-bnd.xml file:
    1. Navigate to the following directory for the application, where profile_root is the (dmg_profile_root) for an ND cell, and (appserver_profile_root) for a base server:
      (profile_root)/config/cells/<cell_name>/applications/<app_name>.ear/deployments/<app_name>/META-INF
      image-20240425120055-2 Avoid trouble: If you edit the file under a (node_profile_root) directory, it will be overwritten after node synchronization.
    2. Back up each of the following files, if they exist (only one should exist):
      • ibm-application-bnd.xmi
      • ibm-application-bnd.xml
  4. Add your group to the application's ibm-application-bnd file:
    1. Open the ibm-application-bnd.xmi or ibm-application-bnd.xml file
      image-20240425120055-2 Avoid trouble: If you edit the file under a (node_profile_root) directory, it is overwritten after node synchronization.
    2. Based on the file type, perform the following steps:
      • For an ibm-application-bnd.xmi file:
        1. Locate the section that looks like the following:
            <authorizationTable xmi:id="AuthorizationTable_xxxxxx">
              <authorizations xmi:id="RoleAssignment_xxxxx">
          ....
                <role href="META-INF/application.xml#SecurityRole_xxxxxxx"/>
          ....
              </authorizations>
            </authorizationTable>
        2. Under the role element, add a group element for your SSO group.  Here is an example that uses the accessId taken from the trace snip earlier in this document.
          <groups xmi:id="Group_9999999" name="myGroup" accessId="group:SAMLRealm/myGroup"/>
        3. Result:
            <authorizationTable xmi:id="AuthorizationTable_xxxxxx">
              <authorizations xmi:id="RoleAssignment_xxxxx">
          ....
                <role href="META-INF/application.xml#SecurityRole_xxxxxxx"/>
                <groups xmi:id="Group_9999999" name="myGroup" accessId="group:SAMLRealm/myGroup"/>
          ....
              </authorizations>
            </authorizationTable>
      • For an ibm-application-bnd.xml file:
        1. Locate the security role that you want to add the group to, for example:
           <security-role name="admin_role">
        2. Add a line that looks like the following within the security-role element.  This example uses the accessId taken from the trace snip earlier in this document:
          <group name="myGroup" access-id="group:SAMLRealm/myGroup"/>
        3. Result:
            <security-role name="admin_role">
              <group name="myGroup" access-id="group:SAMLRealm/myGroup"/>
            </security-role>
    3. Save the file.
  5. Restart and Sync:
    1. Restart the deployment manager or base application server.
    2. For a deployment manager:
      1. For each node profile, manually synchronize the node with the syncNode command.
      2. Start the node agent and servers in the node.
  6. Test the application.

Assigning users to security roles in an ibm-application-bnd file

 
image-20240425115156-2 This method does not work to assign users to admin roles.  Use the admin-authz.xml method instead.
If you need to assign users to security roles, use the procedure shown previously:
  • Instead of using the group string from the trace snip:
    <group name="myGroup" access-id="group:SAMLRealm/myGroup"/>
  • use the uniqueId string:
    <users name="testuser@ibm.com" accessId="user:SAMLRealm/testuser@ibm.com"/>
  • Similarly, instead of using:
    <groups xmi:id="Group_9999999" name="myGroup" accessId="group:SAMLRealm/myGroup"/>
  • Use
    <users xmi:id="User_9999999" name="testuser@ibm.com" accessId="user:SAMLRealm/testuser@ibm.com"/>
 

Assigning groups to administrative roles in admin-authz.xml

 
image-20240425115135-1 Use this method to assign groups to admin roles.  Admin roles are required for admin applications, such as the administrative console.
If you need to assign users and groups to administrative roles, you must manually edit the admin-authz.xml file.  The following example describes how to add a group to a Configurator roll on a deployment manager.
  1. Open the following file in an editor:
    (dmgr_profile_root)/config/cells/<cell_name>/admin-authz.xml
  2. Search for the string configurator and find this line
    <roles xmi:id="SecurityRoleExt_3" roleName="configurator"/>
  3. Search for SecurityRoleExt_3 and find this line:
      <authorizations xmi:id="RoleAssignmentExt_3" role="SecurityRoleExt_3"/>
  4. Under that line, add a line like the following. This example uses the accessId taken from the trace snip earlier in this document.
        <groups xmi:id="UserExt_99999999" name="myGroup" accessId="group:SAMLRealm/myGroup"/>
    image-20240425115156-2 Note that this authorizations element is self-closed; you need to account for this when you add your new child element.  
  5. Result:
      <authorizations xmi:id="RoleAssignmentExt_2" role="SecurityRoleExt_2"/>
      <authorizations xmi:id="RoleAssignmentExt_3" role="SecurityRoleExt_3">
          <groups xmi:id="    UserExt_99999999" name="myGroup" accessId="group:SAMLRealm/myGroup"/>
      </authorizations>
      <authorizations xmi:id="RoleAssignmentExt_4" role="SecurityRoleExt_4"/>
  6. image-20240425115135-1 If your target application is the admin console, also perform steps 1 through 4 for the administrator and adminsecuritymanager roles.
    • If you do not modify these roles for the admin console, your users can login to the console, but they cannot change any settings.
  7. Save the file.
  8. Restart and Sync:
    1. Restart the deployment manager.
    2. For each node profile, manually synchronize the node with the syncNode command.
    3. Re-start the node agent and servers in each node.

Assigning users to administrative roles in admin-authz.xml

 
image-20240425115135-1 Use this method to assign users to admin roles.  Admin roles are required for admin applications, such as the administrative console.
If you need to assign users to administrative roles, use the admin-authz.xml procedure shown previously:
  • Instead of using the group string from the trace snip:
    <groups xmi:id="UserExt_99999999" name="myGroup" accessId="group:SAMLRealm/myGroup"/>
  • use the uniqueId string:
    <users xmi:id="UserExt_99999999" name="testuser@ibm.com" accessId="user:SAMLRealm/testuser@ibm.com"/>

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB67","label":"IT Automation \u0026 App Modernization"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"ARM Category":[{"code":"a8m3p000000F7xdAAC","label":"WebSphere Application Server traditional-All Platforms"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

Document Information

Modified date:
11 July 2024

UID

ibm16527320

Page Feedback