Lighthouse Blog

  • Lighthouse Blog
  • IBM Integration Bus v10: Securing Web Administration Through LDAP Authentication & File-Based Authorization

IBM Integration Bus v10: Securing Web Administration Through LDAP Authentication & File-Based Authorization

IBM Integration Bus v10: Securing Web Administration Through LDAP Authentication & File-Based Authorization


IIB v10 introduced various new features and functionalities. One of the very important new functionalities is the ability to secure Web Administration through LDAP authentication and file based authorization. This blog provides an overview of Web Administration Security and details its implementation.

 IBM Integration Bus Node.jpg


In IIB v10, an administrator can secure access to IIB resources by authenticating users via LDAP rather than native OS.

IIB Authentication:


When LDAP is used for authentication, the integration node needs to determine whether the incoming username is a member of the given group. To do this, the integration node requires specific information.

To resolve the username to an LDAP entry, the integration node needs to know the base distinguished name (Base DN) of the accepted login IDs. This is required to enable the integration node to differentiate between different entries with the same name.

To get an entry list from a group name, the group name specified must be a distinguished name. An LDAP search is made for the group, and the username is checked by finding the entry matching the distinguished name of the user.

If the LDAP directory does not permit login by unrecognized IDs and does not grant search access rights on the subtree, a separate authorized login ID that the integration node can use for the search must be setup. The mqsisetdbparms command is used to specify a username and password:

mqsisetdbparms <INodeName> -n ldap::LDAP -u username -p password


mqsisetdbparms <INodeName> -n ldap::<servername> -u username -p password

where <servername> is your base LDAP server name. For example:

If ldap::LDAP is specified, it creates a default setting for the integration node, which the integration node attempts to use if not explicitly setup via the mqsisetdbparms command to create a login ID for a specific <servername>. All servers that do not have an explicit ldap::servername entry then start using the credentials in the ldap::LDAP entry. This means that any servers that were previously using anonymous bind by default will start using the details in ldap::LDAP.

The username that is specified in the -u parameter must be recognized by the LDAP server as a complete user name. In most cases this means that you need to specify the full DN of the user. Alternatively, by specifying a username to be anonymous, you can force the integration node to bind anonymously to the LDAP server. This might be useful if a non-anonymous bind is specified as the default (ldap::LDAP). For example:

mqsisetdbparms <INodeName> -n ldap::<servername> -u anonymous -p password

In this case, the value specified for password is ignored.

If the LDAP directory does not permit unrecognized user IDs to log in, and does not grant search access rights on the subtree, you must set up a separate, authorized ID that the integration node can use for the search. 

To set the LDAP server to be used for authentication, the following command is utilized:

mqsichangeproperties intNode -b webadmin -o server -n ldapAuthenticationUri

-v "ldapURL"

where intNode is the name of your integration node and ldapURL is the URL for your LDAP.

Enter the ldapURL by using the following syntax:


ldap or ldaps

(Required) Fixed protocol string. Use ldaps to specify that SSL is used.


(Required) Name or IP address of the LDAP server.


(Optional) Port on the LDAP server. If SSL is not enabled, the default port is 389. If SSL is enabled, the default port is 636.


(Required) String that defines the base distinguished name (DN) of all users in the directory. If users exist in different subtrees, specify a common subtree under which a search on the user name uniquely resolves to the required user entry, and set the sub attribute.

If users who need access to the integration exist in multiple base DNs, you can specify more than one base DN in the ldapURL by enclosing each base DN in parentheses. The following syntax shows how to specify the ldapURL when users exist in 3 base DNs:



(Optional) String that defines the attribute to which the incoming user name maps, typically uid, CN, or email address. The default is uid.

base or sub

(Optional) Defines whether to perform a base or subtree search. If base is selected, the authentication is faster because the DN of the user is constructed from the uid_att, username, and baseDN values. If sub is selected, a search must be performed before the DN can be resolved. The default is sub.

For example:





In addition to authenticating users to access IIB resources, administrators can elect to authorize users via employment of an out-of -the-box feature called file-based authorization.

When IIB file based authorization is to be leveraged, user roles and their associated permissions must be defined. Permissions are assigned to each role that is defined; for example, web users can be categorized into several different main roles: administrators and developers, users, etc. Role is defined for each of these groups of users (for example, iibAdmins, iibDevelopers, iibUsers) with permissions that allow them to perform the required tasks, such as viewing, running or modifying resources:

  1. If the integration node is configured to use file-based authorization (file mode), define the roles and associated permissions on the integration node, by using the mqsichangefileauth
  2. Use the mqsiwebuseradmin command to create your web user accounts and assign them to the appropriate roles.

File Authorization

Since the IIB v10 no longer has MQ dependency file authorization can be used. The mqsichangeauthmode command can be executed to select a queue-based or file-based mode of administration authority.


Ensure that the integration node is stopped.

Use the mqsichangeauthmode command to enable administration security and to specify the required authorization mode:

Specify -s active to enable administration security.

Specify the required mode:

Specify -m file to use file-based permissions, which are set using the mqsichangefileauth command. If you create an integration node without specifying an associated queue manager, file-based administration security is used by default for the integration node.

Specify -m mq to use WebSphere MQ queues for setting permissions. You can use queue-based security only if you have installed WebSphere MQ and specified a queue manager on the integration node. If a queue manager is specified on the integration node, administration security is queue-based by default, and the required queues used for setting authorization are created automatically when the integration node is created.

For example:

mqsichangeauthmode IB10NODE -s active -m file

Restart the integration node for the changes to take effect.


Grant and revoke administration authority by using the mqsichangefileauth command to configure file-based permissions for specified roles. Use file-based permissions for authorization only if the file-based mode of administration security has been specified for the integration node. Use the mqsichangeauthmode command to change the administration security mode, and the mqsireportauthmode command to see which security mode is currently in effect.

Three levels of authorization are supported for IIB administration security: read, write, and execute. Assign permissions to a role (system user) by specifying the type of permission followed by a plus (+) to grant permissions, or a minus (-) to revoke permissions:





Specify the permissions as a comma-separated list of values. A value can be specified for each permission (read, write, and execute) only once in the list of values. For example, you cannot specify all-,read+ because it would be attempting to set the read permission twice (once explicitly, and once as part of all). If all is specified, it must be the only value. If you specify all-, all permission records in the registry are removed.

These permissions can be applied to each role for the following types of objects:

Integration node resources

Integration server resources

Data capture objects (record-replay)

If you grant permissions to a role at the integration node level, that permission is not applied to the node's integration servers; you must set permissions explicitly for individual integration servers.


If you grant permissions associated with integration server resources or data capture objects to users that use the web user interface, you must also grant the users read access to the integration node.

Control of access to integration node resources through the web user interface and REST application programming interface (API), is implemented by associating web users with roles.

A role is defined by a set of security permissions that control users' access to an integration node and its resources.

The access that web users are assigned to the integration node resources is controlled by assigning each user to a predefined role. Authorize users with a role to complete specific actions, by enabling or disabling aspects of the web or REST interface, or by configuring the web user interface to display only the options for which users are authorized.

Users can have the same permissions by being assigned to the same role, but each user can be assigned to only one role.

For commands that are run locally, and for a locally connected Toolkit, the system user ID that is running the command or the Toolkit is passed to the integration node, where it is used as the role name.

If an integration node is configured to use file-based authorization (file mode), granting permissions to a role by using the -r role parameter of the mqsichangefileauth command. If no permissions are granted to a role, a check is conducted to see whether the role name matches a system user ID name. If the command is a local mqsi command and run by a system user ID that is a member of the mqbrkrs group, permission is granted for all actions on all objects.

Use the mqsichangefileauth command to change the permissions that are assigned to a role. For example:

mqsichangefileauth IB10NODE -r iibAdmins -e default -p read+,execute+

In this example, the role iibAdmins is granted execute and read permission on IB10NODE.default (the default integration server on the IB10NODE integration node). If this role did not previously exist, the write permission is disabled.

If you are using the web user interface for administration, log off and log back on to refresh the web user interface to reflect the new permissions. If permissions have been revoked, the change takes effect immediately and actions requiring that permission fail because access is denied.

User Accounts

Configure the web user accounts for each user that you want to authenticate. Either create new web user accounts or modify existing web user accounts:

Create a new web user account by using the mqsiwebuseradmin command. For example:

mqsiwebuseradmin intNode -c -u ldapusername -x -r sysrole

where ldapusername is the user name in the LDAP directory, and sysrole is the role to associate with the web user account.


If you add a local password by using the -a parameter, the local password is used instead of the LDAP authentication.

Modify an existing web user account to remove any local password. For example:

mqsiwebuseradmin intNode -m -u ldapusername -x -r sysrole


You can modify an existing web user account to be authenticated by using LDAP only if the existing user name matches the user name in the LDAP directory. If the user names do not match, you must create a new web user account.

Step by Step Instruction to Implement IIB v10 Web Administration Security. (LDAP authentication and File-Based Role Authorization)


     Define Groups and Users:

     IIB Administration Security Specifications

           For example:

iibAdmins Group: DEV, QAT, PROD

(All Access)

iibDevs Group: DEV

(Start, Stop, Create, Delete Nodes, No Access to Record and Play)

           iibUsers Group: QAT

            (Browse, No Access to Record and Play)

           IIBUsers Group: PRD

            (Browse, No Access to Record and Play)

Utilize LDAP Utility to Test and Verify Interaction with LDAP:


Create an Implementation Script:

#IIB Web Admin Security with LDAP and Local authentication\File Based Authorization


Check security setting:


mqsireportauthmode NODE_NAME


Stop the node:


mqsistop NODE _NAME


#Change authentication mode:


mqsichangeauthmode NODE _NAME -s active -m file


#Start node:

mqsistart NODE _NAME


#Define roles:




mqsichangefileauth NODE _NAME -r iibAdmins -p all+

mqsichangefileauth NODE _NAME -r iibAdmins -e NODE _NAME _IS01 -p all+

mqsichangefileauth NODE _NAME -r iibAdmins -o DataCapture -p all+




mqsichangefileauth NODE _NAME -r iibDevs -p all+

mqsichangefileauth NODE _NAME -r iibDevs -e NODE _NAME _IS01 -p all+





mqsichangefileauth NODE _NAME -r iibUsers -p read+

mqsichangefileauth NODE _NAME -r iibUsers -e NODE _NAME _IS01 -p read+


Define web users and assign roles:


#This is a local account which will not validate against AD (testing account)

mqsiwebuseradmin NODE _NAME -c -u testuser -a password -r iibUsers

#This is an admin local account which will not validate against AD (this account can still be used if the active directory server goes down)

mqsiwebuseradmin NODE _NAME -c -u iibAdmin -a password -r iibAdmins

mqsiwebuseradmin NODE _NAME -c -u johndoe -x -r iibAdmins

mqsiwebuseradmin NODE_NAME -c -u janedoe -x -r iibDevs

mqsiwebuseradmin NODE _NAME -c -u johnsmith -x -r iibUsers


#List all web accounts:


mqsiwebuseradmin NODE _NAME -l


#Report permissions for all roles:

mqsireportfileauth NODE _NAME -r iibAdmins

mqsireportfileauth NODE _NAME -r iibDevs

mqsireportfileauth NODE _NAME -r iibUsers


#Set LDAP Connection login and search LDAP search URI (utilizing samaccountname)


mqsichangeproperties NODE _NAME -b webadmin -o server -n ldapAuthenticationUri -v \"ldap://ldapsvrname:389/ou= someorganizationalunit,ou= someorganizationalunit,dc=somedomaincomponent,dc= somedomaincomponent?samaccountname\"

mqsisetdbparms NODE _NAME -n ldap::ldapsvrname -u "cn= someorganizationalunit,ou= someorganizationalunit,dc= somedomaincomponent,dc= somedomaincomponent " -p yourLDAPpassword


#Stop node:


mqsistop NODE _NAME


#Start node:


mqsistart NODE _NAME


#AD Checks with java LDAP jar


#This is a debugging utility command which aids in error capture and returns syntax for dbparms for connection and LDAP URI

java -jar G:\LdapAuthentication.jar ldap:// ldapsvrname:389 cn=" someorganizationalunit ",ou=" someorganizationalunit ",dc=somedomaincomponent,dc=somedomaincomponent ldappassword ou=someorganizationalunit,ou= someorganizationalunit,ou= someorganizationalunit,dc= somedomaincomponent,dc= somedomaincomponent samaccountname janedoe janedoepassword

#Full DN:

#CN=Jane Doe,OU= someorganizationalunit,OU= someorganizationalunit,OU= someorganizationalunit,DC=somedomaincomponent,DC=somedomaincomponent





Related Posts
Analytics Choosing Smarter Analysis Over Routine Reports Can Improve Security Intelligence
Security Managing and Securing Devices Begins With Knowing That They’re There