Thursday, November 3, 2016

The interaction of CHLAUTH and CONNAUTH in IBM MQ - Middleware News

When an application connects to MQ using client bindings, network connections have to be opened up which can have security implications. In the last few MQ releases these have been addressed with the introduction of the CHLAUTH and CONNAUTH features. This is the first in a series of articles that will look at these features. This article will explain how they fit together when a receiving end of a channel is started.
Different types of bindings
IBM MQ supports two ways that an application can connect:
  1. Local bindings: This is when the application and queue manager are on the same operating image. CHLAUTH is not relevant to this type of application connection.
  2. Client bindings: This is when the application and queue manager use the network to communicate. The application and queue manager may be running on the same machine or they may be on different machines. In MQ a client connection is handled in the form of a server-connection (SVRCONN) channel. Both CONNAUTH and CHLAUTH are applicable, and it is this type of connection which is discussed.

The binding steps of a receiving end of a channel
When an application connects to a queue manager there is a lot of checking to perform to ensure that both ends of the channel understand what is supported by the other end. The receiving end does some extra checking to ensure that the client is allowed to connect. This checking involves CHLAUTH and CONNAUTH. This process may also include a security exit as this can affect the result. This channel connecting phase is also referred to as the binding phase.
In MQ version 7 SHARECNV was added to SVRCONN channels so multiple connections/conversations can share the same channel. This article does not cover what happens in terms of CHLAUTH and CONNAUTH when a second and following conversations share the same channel.
Figure 1 shows the steps that a SVRCONN channel goes through when the server end (at the queue manager) starts.
image
Figure 1: the steps that a SVRCONN channel goes through when starting up.
Step 1: Receive a connection request The channel initiator or listener receives a connection request from somewhere on the network.
Step 2: Is address allowed to connect? Before any data is read from the wire, MQ will check the partner's IP address against the CHLAUTH rules to see if the address is in the BLOCKADDR rule. If the address is not found and so not blocked the flow proceeds to the next step.
Step 3: Read data from the channel MQ can now read the data from the wire into a buffer and start to process the sent information.
Step 4: Look up channel definition In the first data flow MQ sends amongst other things the name of the channel which the sending end is trying to start. The receiving queue manager can then look up the channel definition, which has all the settings that are specified for the channel.
Step 5: Pre CONNAUTH checks when using CHLAUTH and CONNAUTH there is a situation where the user id of the channel rather than the asserted user id is used in the CHLAUTH mapping. To give an example if CONNAUTH is using LDAP to map an email address to a serial number you would properly want the result e.g. serial number to be used in the CHLAUTH mapping. By default this doesn't happen. An APAR has been done to add an ini parameter called ChlauthEarlyAdopt which performs an extra check before the CHLAUTH mapping. This APAR went into MQ 8.0.0.5, IT12825: IBM MQV8: A CLIENT APPLICATION FAILS TO CONNECT TO A QUEUE MANAGER WITH ERROR AMQ9777: CHANNEL WAS BLOCKED details how to turn the option on. This was slightly altered at version 9.0 where the option is just Y which covers all the options described in the APAR.
Step 6: CHLAUTH mapping The CHLAUTH cache is inspected again to look for mapping rules (SSLPEERMAP, USERMAP, QMGRMAP and ADDRESSMAP). The rule that matches the incoming channel most specifically will be used. If the rule has USERSRC(CHANNEL) or USERSRC(MAP) the channel continues on binding. Rules that have USERSRC(NOACCESS) means that the channel would be blocked from connecting and the network connection is ended.
Step 7: Call security exit If the channel has a security exit (SCYEXIT) defined, this is called with the exit reason (MQCXP.ExitReason) set to MQXR_SEC_PARMS. If the client application has specified security credentials on a MQCONNX call (via MQCSP on the MQCNO) these will be passed in the exit parameters (a pointer to MQCSP will be present in the SecurityParms field of the MQCXP). The MQCSP structure has pointers to the user ID (MQCSP.CSPUserIdPtr) and password (MQCSP.CSPPasswordPtr). It is possible for the security exit to change these. Example 1 shows how a security exit would access the userId and password fields.

if (pMQCXP -> ExitReason == MQXR_SEC_PARMS)
{
  /* It is not a good idea for security reasons to print out the user ID */
  /* and password but the following is shown for demonstration reasons */
  printf("User ID: %.*s Password: %.*s\n",
         pMQCXP -> SecurityParms -> CSPUserIdLength,
         pMQCXP -> SecurityParms -> CSPUserIdPtr,
         pMQCXP -> SecurityParms -> CSPPasswordLength,
         pMQCXP -> SecurityParms -> CSPPasswordPtr);
}

Example 1: accessing the user ID and password in an exit
The exit could tell MQ to close the channel by returning MQXCC_CLOSE_CHANNEL or MQXCC_FAILED in MQCXP.ExitResponse field. Otherwise, channel processing continues to the connection authorisation phase.
Step 8: Is user authorised? The authorisation phase happens if CONNAUTH is enabled on the queue manager. To check this issue the MQSC command 'DISPLAY QMGR CONNAUTH'. Figures 2 and 3 show the output of this command on MQ for z/OS and distributed MQ.

 CSQM201I !MQ25 CSQMDRTC DISPLAY QMGR DETAILS
 QMNAME(MQ25)
 CONNAUTH(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)
  END QMGR DETAILS
 CSQ9022I !MQ25 CSQMDRTC ' DISPLAY QMGR' NORMAL COMPLETION

Figure 2: output of the command DISPLAY QMGR CONNAUTH from a queue manager running on z/OS

    1 : DISPLAY QMGR CONNAUTH
AMQ8408: Display Queue Manager details.
   QMNAME(DEMO)
   CONNAUTH(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)

Figure 3: output of the command DISPLAY QMGR CONNAUTH from a distributed MQ queue manager
The CONNAUTH value is a name of an AUTHINFO MQ object. MQ version 8 supports two methods of authentication: using the operating system (AUTHTYPE(IDPWOS)) or using LDAP (not available on z/OS) (AUTHTYPE(IDPWLDAP)). This article concentrates on operation system authentication. In a future article. I will cover using LDAP for authentication. Figures 4 and 5 shows the shipped default object for AUTHINFO type(IDPWOS) in MQ for z/OS and distributed MQ.

 CSQM293I !MQ25 CSQMDRTC 1 AUTHINFO FOUND MATCHING REQUEST CRITERIA
 CSQM201I !MQ25 CSQMDRTC DISPLAY AUTHINFO DETAILS
 AUTHINFO(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)
 AUTHTYPE(IDPWOS)
 QSGDISP(QMGR)
 ADOPTCTX(NO)
 CHCKCLNT(NONE)
 CHCKLOCL(OPTIONAL)
 FAILDLAY(1)
 DESCR()
 ALTDATE(2015-06-04)
 ALTTIME(10.43.04)
   END AUTHINFO DETAILS
 CSQ9022I !MQ25 CSQMDRTC ' DISPLAY AUTHINFO' NORMAL COMPLETION

Figure 4: displaying the shipped default object for AUTHINFO type(IDPWOS) from a queue manager running on z/OS

    1 : display authinfo(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)
AMQ8566: Display authentication information details.
   AUTHINFO(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)
   AUTHTYPE(IDPWOS)                     ADOPTCTX(NO)
   DESCR( )                             CHCKCLNT(REQDADM)
   CHCKLOCL(OPTIONAL)                   FAILDLAY(1)
   ALTDATE(2015-06-08)                  ALTTIME(16.35.16)

Figure 5: displaying the shipped default object for AUTHINFO type(IDPWOS) from a distributed queue manager.
The AUTHINFO TYPE(IDPWOS) has an attribute called CHCKCLNT. If the value is changed to REQUIRED all client applications would have to supply a valid user ID and password. While we are looking at the attributes involved with CONNAUTH, I must mention the adopt context (ADOPTCTX) option. The ADOPTCTX attribute controls whether the channel runs under MCAUSER or the user ID the application has supplied If ADOPTCTX is YES then the channel will adopt that user to run under (the active MCAUSER) and the object authorization will be done against this user. This will also be used in step 8 in the CONNAUTH check.
For example, say I don't have a MCAUSER set on the SVRCONN channel and my client is running under 'markw1' on my linux machine. My application specifies user 'fred' in the MQCSP the channel will start running with 'markw1' as the active MCAUSER. After the CONNAUTH check the user 'fred' will be adopted and the channel run with 'fred' as the active MCAUSER.
Step 9: Is user allowed on this channel? If the CONNAUTH checking is successful the CHLAUTH cache is then inspected again to check if the active MCAUSER is blocked by a BLOCKUSER rule. If the user is blocked the channel will be terminated.
Steps 10 and 11: Object authorisation checks The client application has now connected. As with locally bound applications any objects that the application opens e.g. a queue, requires a check will be made to ensure that the active MCAUSER has the appropriate authority for that object.
Conclusion In this article I have described what stages a channel goes through when connecting in terms of security checking. In the next article I will demonstrate how an application supplies user credentials.
Resources
The following links are provided to give more information the topics covered:


Friday, October 28, 2016

Installing IBM Integration Bus on Linux - Middleware News

Before you begin

About this task

As a user without administrative rights, you can create a single-user installation of IBM Integration Bus in your home directory. This single-user installation is then accessible only by your user ID.
As a user with administrative rights, you can create a shared installation of IBM Integration Bus. To authorize any users of the computer to access the shared installation of IBM Integration Bus, add the users to the mqbrkrs group by using the security facilities that are provided by your operating system.
If you deploy IBM Integration Bus for a single user, you can convert the deployment to a shared installation later, see Converting from a single-user installation of IBM Integration Bus to a shared installation of IBM Integration Bus.

Installing the software

Procedure

To install IBM Integration Bus, complete the following steps:
  1. Log in to the system where you are installing IBM Integration Bus.
    • If you are deploying a single-user installation, log in with your personal user ID.
    • If you are deploying a shared installation, log in as root or as a super user who has write access to the /var directory.
  2. Unpack the installation image by completing the following steps:
    1. Create or navigate to a directory where you have write access. For example, $HOME for a single-user installation, or /opt/IBM for a shared installation.
    2. Run the following command to unpack the installation image:
      tar -xzvf iib-10.0.0.n.tar.gz
      Note: On all Linux systems, except for Linux on IBM z Systems and Linux on POWER®, the installation includes the IBM Integration Toolkit. If you do not want to install the IBM Integration Toolkit, you can run the following command instead:
      tar -xzvf iib-10.0.0.n.tar.gz --exclude iib-10.0.0.n/tools
  3. Accept the IBM Integration Bus license by completing the following steps:
    1. Navigate to the installation directory. For example, install_dir/iib-10.0.0.n where install_dir is the directory where you unpacked the installation image.
    2. Type one of the following commands:
      • For a single-user installation:
        • ./iib accept license. If you use this command, you are prompted to accept the license.
        • ./iib accept license silently. If you use this command, the license is accepted even though the license dialog is not displayed.
        The following directory is created: $HOME/iibconfig. This directory is the work path for IBM Integration Bus, and stores the IBM Integration Bus configuration files.
      • For a shared installation:
        • ./iib make registry global accept license. If you use this command, you are prompted to accept the license.
        • ./iib make registry global accept license silently. If you use this command, the license dialog is suppressed and the license is automatically accepted.
        The following directory is created: /var/mqsi. This directory is the work path for IBM Integration Bus, and stores the IBM Integration Bus configuration files.
  4. Optional: If you installed a shared installation of IBM Integration Bus, grant users access to the installation by adding them to the mqbrkrs user group.
    Note: On Linux, the user ID that installed IBM Integration Bus is not automatically added to the mqbrkrs group. If you want to use this user ID with IBM Integration Bus, you must add the user ID to the mqbrkrs group.
[root@localhost iib-10.0.0.6]# ./iib make registry global accept license
International License Agreement for Non-Warranted Programs

Part 1 - General Terms

BY DOWNLOADING, INSTALLING, COPYING, ACCESSING, CLICKING ON
AN "ACCEPT" BUTTON, OR OTHERWISE USING THE PROGRAM,
LICENSEE AGREES TO THE TERMS OF THIS AGREEMENT. IF YOU ARE
ACCEPTING THESE TERMS ON BEHALF OF LICENSEE, YOU REPRESENT
AND WARRANT THAT YOU HAVE FULL AUTHORITY TO BIND LICENSEE
TO THESE TERMS. IF YOU DO NOT AGREE TO THESE TERMS,

* DO NOT DOWNLOAD, INSTALL, COPY, ACCESS, CLICK ON AN
"ACCEPT" BUTTON, OR USE THE PROGRAM; AND

* PROMPTLY RETURN THE UNUSED MEDIA AND DOCUMENTATION TO THE

Press Enter to continue viewing the license agreement, or
enter "1" to accept the agreement, "2" to decline it, "3"
to print it, "4" to read non-IBM terms, or "99" to go back
to the previous screen.
1
License accepted
Group 'mqbrkrs' will be created
[root@localhost iib-10.0.0.6]#

Verifying the installation

Procedure

To start the IBM Integration Toolkit and verify your installation, complete the following steps:
Note: If you did not install the IBM Integration Toolkit on this computer, you can use the iib verify all command instead; see iib command.

  1. Start the IBM Integration Toolkit by running the following command from the installation directory:
    ./iib toolkit
    The first time that you start IBM Integration Toolkit, the following entities are created:
    • A directory: $HOME/IBM/IIBT10/workspace, which is used as the IBM Integration Toolkit workspace directory. You can change the location of the workspace directory by clicking File > Switch Workspace > Other from the IBM Integration Toolkit menu.
    • An integration node: TESTNODE_user_name where user_name is the name of the ID that you used to log in. If you do not want to keep this default integration node, see Preventing the creation of the default integration node.
    • An integration server: default.
    The Welcome page for the IBM Integration Toolkit is displayed.
  2. Close the Welcome page to display the Integration Development perspective of the IBM Integration Toolkit. The TESTNODE_user_name integration node and default integration server are started and they are displayed in the Integration Nodes pane.
  3. Optional: You can verify the version of all the components you installed by running ./iib version from the installation directory. The details of the product components are displayed. For example:
    Version:       10000
    Product:       IBM Integration Bus
    Build Number:  221
    IB Level:      ib000-L140528.221_P
    Server level:  S000-L140527.2
    Toolkit level:   20140526-1900
    For information about the iib command, see iib command.
[root@localhost iib-10.0.0.6]# ./iib verify all
Verifying checksums of files in installation, this may take a few minutes ...
All of the file checksums are as expected
Create a node using:
mqsicreatebroker VERIFY1164
BIP8071I: Successful command completion.

Verify the node using:
mqsicvp VERIFY1164
BIP8873I: Starting the component verification for component 'VERIFY1164'.
BIP8876I: Starting the environment verification for component 'VERIFY1164'.
BIP8894I: Verification passed for 'Registry'.
BIP8894I: Verification passed for 'MQSI_REGISTRY'.
BIP8894I: Verification passed for 'Java Version - 1.7.0 IBM Linux build pxa6470_27sr3fp40-20160422_01(SR3 FP40)
BIP8894I: Verification passed for 'MQSI_FILEPATH'.
BIP8878I: The environment verification for component 'VERIFY1164' has finished successfully.
BIP8882I: Starting the WebSphere MQ verification for component 'VERIFY1164'.
BIP8294I: ODBC environment verification was skipped because the ODBCINI environment variable is not set.
BIP8874I: The component verification for 'VERIFY1164' has finished successfully.
BIP8071I: Successful command completion.

Set the web admin port on the node using:
mqsichangeproperties VERIFY1164 -b webadmin -o HTTPConnector -n port -v 4429
BIP8071I: Successful command completion.

Start the node using:
mqsistart VERIFY1164
BIP8096I: Successful command initiation, check the system log to ensure that the component started without problem and that it continues to run without problem.

List all nodes using:
mqsilist
BIP1325I: Integration node 'VERIFY1164' with administration URI 'http://localhost.localdomain:4429' is running.
BIP8071I: Successful command completion.

Create a server on the node using:
mqsicreateexecutiongroup VERIFY1164 -e default -w 90
BIP1124I: Creating integration server 'default' on integration node 'VERIFY1164'...
BIP1117I: The integration server was created successfully.

The integration node has initialized the integration server.
BIP8071I: Successful command completion.

List the server status using:
mqsilist VERIFY1164
-----------------------------------
BIP1286I: Integration server 'default' on integration node 'VERIFY1164' is running.
BIP8071I: Successful command completion.

Stop the node using:
mqsistop VERIFY1164
BIP8071I: Successful command completion.

Delete the node using:
mqsideletebroker VERIFY1164
BIP8071I: Successful command completion.

[root@localhost iib-10.0.0.6]#

You installed and started IBM Integration Bus. If you experienced problems during installation, see Resolving problems when you install IBM Integration Bus.

What to do next

Note: In IBM Integration Bus Version 10.0, you do not need to install the IBM Integration ODBC Database Extender program to use database nodes in your applications. The program code is installed as part of the IBM Integration Bus installation.

Setting up a command environment


Check whether the following conditions apply to your environment:
  • If you have a previous version of IBM® Integration Bus on this system, then ensure that you run the correct profile before you use Version 10.0. The mqsiprofile command places the Version 10.0 commands and libraries at the front of your search path, and can override any combination of PATH, CLASSPATH, or library PATH.
  • If you use the same user ID, and you run multiple profiles (from multiple different installations or versions), you might get unexpected results. Log off and log on again before you run the specific profile that you require.
  • If you are using Linux or UNIX, then ODBC settings on Linux and UNIX systems are found in a text file that is defined by the ODBCINI environment variable. Set ODBCINI to point to a copy of the sample file install_dir/server/ODBC/unixodbc/odbc.ini, where install_dir is the IBM Integration Bus installation directory.
    You can check that your ODBC environment is configured correctly by running the mqsicvp command. This command also validates the connection to all data sources (listed in the odbc.ini file) that are associated with an integration node by using the mqsisetdbparms command. For more information, see mqsicvp command.

About this task

The following steps explain how to initialize your command environment by running the mqsiprofile command.
If required, you can perform the following customizations before you run the command:
Ensure that you use this environment each time you run an administrative command, or start an integration node.
  • On Windows 7 and Windows 2008:
    • Open a command console by clicking Start > All Programs > IBM Integration Bus 10.0.0.n > IBM Integration Console 10.0.0.n.
  • On Windows 8 and Windows 2012:
    • Open a command console by searching for IBM Integration Console. If you have multiple installations of IBM Integration Bus, make sure that you are running the IBM Integration Console from the build of the IBM Integration Bus installation that you want to administer.
  • On Linux or UNIX systems: Locate and run the mqsiprofile.sh script in the directory in which you installed the appropriate product.
    . install_dir/server/bin/mqsiprofile
    You must include the period and space for this command to work correctly. Add this command to your login profile if you want it to be run at the start of every session.
    If you use the zsh shell, then running the mqsiprofile might cause the terminal session to exit. To resolve this issue, run the unsetopt function_argzero command before you run the mqsiprofile command.
This command also runs any additional scripts that you copied to the common\profiles directory (on Windows) or the common/profiles directory (on Linux or UNIX systems), so that the environment is initialized for runtime components and other resources such as databases.

[root@localhost iib-10.0.0.6]# su - mqbrkrs
Last login: Fri Oct 28 08:08:34 PDT 2016 on pts/0

[mqbrkrs@localhost ~]$ . /opt/IBM/iib-10.0.0.6/server/bin/mqsiprofile
MQSI 10.0.0.6
/opt/IBM/iib-10.0.0.6/server

[mqbrkrs@localhost ~]$ mqsicreatebroker BRK10
BIP8071I: Successful command completion.
[mqbrkrs@localhost ~]$

[mqbrkrs@localhost ~]$ mqsistart BRK10
BIP8096I: Successful command initiation, check the system log to ensure that the component started without problem and that it continues to run without problem.

[mqbrkrs@localhost ~]$ mqsilist
BIP1325I: Integration node 'BRK10' with administration URI 'http://localhost.localdomain:4414' is running.
BIP8071I: Successful command completion.
[mqbrkrs@localhost ~]$

[mqbrkrs@localhost ~]$ mqsilist BRK10
BIP1282I: No integration servers have been defined on integration node 'BRK10'.
BIP8071I: Successful command completion.

[mqbrkrs@localhost ~]$ mqsicvp BRK10
BIP8873I: Starting the component verification for component 'BRK10'.
BIP8876I: Starting the environment verification for component 'BRK10'.
BIP8894I: Verification passed for 'Registry'.
BIP8894I: Verification passed for 'MQSI_REGISTRY'.
BIP8894I: Verification passed for 'Java Version - 1.7.0 IBM Linux build pxa6470_27sr3fp40-20160422_01(SR3 FP40)
BIP8894I: Verification passed for 'MQSI_FILEPATH'.
BIP8878I: The environment verification for component 'BRK10' has finished successfully.
BIP8882I: Starting the WebSphere MQ verification for component 'BRK10'.
BIP8294I: ODBC environment verification was skipped because the ODBCINI environment variable is not set.
BIP8874I: The component verification for 'BRK10' has finished successfully.
BIP8071I: Successful command completion.
[mqbrkrs@localhost ~]$


iib command:

Command Description Available on Windows? Available on Linux? Available on UNIX systems?
iib accept license
iib accept license silently
Starts the license acceptance process for IBM Integration Bus. If you use the command followed by the silently option, then the license is accepted even though the license dialog is not displayed. No Yes Yes
iib make registry global Converts from a single-user installation of IBM Integration Bus to a shared installation of IBM Integration Bus. /var/mqsi is created as the new IBM Integration Bus work path directory. No Yes Yes
iib help Displays help about the iib command. Yes Yes Yes
iib toolkit
iib tools
Starts the IBM Integration Toolkit. Yes Yes No
iib toolkit without testnode
iib tools without testnode
Starts the IBM Integration Toolkit, but does not create the default integration node. If the default integration node (TESTNODE_user_name) already exists, the integration node is not started. Yes Yes No
iib verify
iib verify install
Verifies the checksum of each installed file in the IBM Integration Bus installation. No Yes Yes
iib verify node Verifies that integration nodes and integration servers can be created. The following tasks are completed:
  1. An integration node and integration server are created and started.
  2. Information about the integration node and integration server is displayed.
  3. The integration node and integration server are stopped and deleted.
Yes Yes Yes
iib verify all Validates the integrity and operation of the IBM Integration Bus installation. The following tasks are completed:
  1. The checksum of each installed file is verified.
  2. An integration node and integration server are created and started.
  3. Information about the integration node and integration server is displayed.
  4. The integration node and integration server are stopped and deleted.
No Yes Yes
iib version Displays the version level of all the build components in the IBM Integration Bus installation. Yes Yes Yes
All other commands are prefixed with mqsi. For details of all the commands, see Commands.
Note: When you run the iib commands on the command line or from a script, a banner is included in the system output:
_/\\\\\\\\\\\__/\\\\\\\\\\\__/\\\\\\\\\\\\\__________/\\\_____/\\\\\\\____
_\/////\\\///__\/////\\\///__\/\\\/////////\\\____/\\\\\\\___/\\\/////\\\__
 _____\/\\\_________\/\\\_____\/\\\_______\/\\\___\/////\\\__/\\\____\//\\\_
  _____\/\\\_________\/\\\_____\/\\\\\\\\\\\\\\________\/\\\_\/\\\_____\/\\\_
   _____\/\\\_________\/\\\_____\/\\\/////////\\\_______\/\\\_\/\\\_____\/\\\_
    _____\/\\\_________\/\\\_____\/\\\_______\/\\\_______\/\\\_\/\\\_____\/\\\_
     _____\/\\\_________\/\\\_____\/\\\_______\/\\\_______\/\\\_\//\\\____/\\\_
      __/\\\\\\\\\\\__/\\\\\\\\\\\_\/\\\\\\\\\\\\\/________\/\\\__\///\\\\\\\/_
       _\///////////__\///////////__\/////////////__________\///_____\///////__
If you want to suppress the banner, type one of the following commands on the command line, or add the following command as the first line of your script:
  • On Windows:
    SET IIB_BANNER=1
  • On Linux and UNIX systems:
    EXPORT IIB_BANNER=1