This is part of a series of small blog posts which will cover some of the smaller, perhaps less likely to be noticed, features of IBM MQ. Read other posts in this series.

It seems to come up quite regularly on the various fora where users of IBM MQ ask questions that they forget to look in the AMQERR01.LOG for authorization errors. In fact it is possibly true that users forget to look in the AMQERR01.LOG for all sorts of errors, but today, in this post, I want to just concentrate on authorization errors.

I think this particular area has had somewhat of a potted history. In older releases of MQ you had to enable Authority Events in order to discover the authorization failure, or set an environment variable or two to force the queue manager to tell you what you need to know, and answers that contain such advice can still be found if searching old questions, so in order to try and combat some of that, I thought this article might be helpful.

Given that IBM MQ V8 is now the oldest version of MQ in service, it is now safe to say that the AMQERR01.LOG contains all the information you need to resolve your MQRC_NOT_AUTHORIZED issue.

We often see questions along the lines of, "My application got a 2035 reason code. How do I solve this?"

Of course this is not enough information to provide a solution. Here are a few steps to follow assuming that you believe your application is supposed to have access. Later in this article we will discuss what to think about if you suspect an application is trying to use your queue manager when it shouldn't be.

• If you don't know what the number that was returned to your application means (in our example 2035), first issue the following command.

  mqrc 2035

  This will show you that 2035 means MQRC_NOT_AUTHORIZED. This means that the queue manager refused your application for a security reason, but it does not tell you, the application any more than that. There are a number of different security reasons that you might encounter, but these are not differentiated for the application, so as not to give it any further clues if it is trying to break in!
• Now, on the machine where the queue manager is running, inspect the AMQERR01.LOG file. This file is found in MQ_DATA_PATH/qmgrs/queue-manager-name/errors/AMQERR01.LOG. If you don't have access to the queue manager machine, or access to view this file you will need to get help from an administrator who does have access. You cannot solve an authorization failure such as this without such access.

• If you received a failure on the connect verb in your application, you may hit one of several connection time security features. There is Connection Authentication which checks for password authentication, Channel Authentication which checks for network authentication by IP address or digital certificate, and then there is object authorization which, having passed the previous two, checks that you are allowed to work with the objects in the queue manager. You'll get different errors in the AMQERR01.LOG file depending on which one you have fallen foul of.

  To learn more about Connection Authentication, read the many posts written from IBM Hursley about this feature. If you are blocked by a Channel Authentication rule, this post will help. If however, you have found an authorization error, read on.

• And authorization error will provide an error message in your queue manager's AMQERR01.LOG file which looks something like this:

  AMQ8077W: Entity 'mqgusr1' has insufficient authority to access object 'MQG1'.
  
  EXPLANATION:
  The specified entity is not authorized to access the required object. The
  following requested permissions are unauthorized: connect
  ACTION:
  Ensure that the correct level of authority has been set for this entity against
  the required object, or ensure that the entity is a member of a privileged
  group. 

  In this error message you get all the information you need to formulate a command to grant the missing authority. You get:-
  • User ID: mqgusr1
  • Object Name: MQG1 - the queue manager name in this case
  • Object Type: Not provided, but inferable from the missing authority, and knowledge that the application failed on an MQCONN(X) call.
  • The missing authority: connect

  Before issuing a command to grant the missing authority, you should discover what the appropriate group that this user is in, and grant the authority for that group, rather than the user id (unless you have a queue manager that is set up to expect authorities to be granted on a per user id basis - not the default on Unixes!). In this example, the user 'mqgusr1' is in group 'mqgemapp'.

• Now issue a command against the queue manager to grant the missing authority. You can do this from the command line using setmqaut, using MQSC via the SET AUTHREC command, or with your favourite MQ GUI administrative tool which will use the PCF interface. Here are some examples.

  setmqaut -m MQG1 -t qmgr -g mqgemapp +connect

  SET AUTHREC OBJTYPE(QMGR) GROUP('mqgemapp') AUTHADD(CONNECT)

• Once you have fixed the connection authentication error, it is likely that you will hit another authorization error but this time for the queue or topic you might be trying to use. Don't be disheartened when your application fails again with the same reason code after you thought you had fixed it. Look closely at the output from your application and realise that it is from the next API call, perhaps an MQOPEN, and follow the same process again.
• You'll see another authorization error in your queue manager's AMQERR01.LOG file, something like this:

  AMQ8077W: Entity 'mqgusr1' has insufficient authority to access object 'Q1'.
  
  EXPLANATION:
  The specified entity is not authorized to access the required object. The
  following requested permissions are unauthorized: put
  ACTION:
  Ensure that the correct level of authority has been set for this entity against
  the required object, or ensure that the entity is a member of a privileged
  group.

• As before, pull out the relevant pieces of information from the error message and use them to build up the command to grant the missing authority. This time you will also need the object name in the command, which you didn't need in the first example for the queue manager object. Here are some example commands again.

  setmqaut -m MQG1 -t queue -g mqgemapp -n Q1 +put

  SET AUTHREC OBJTYPE(QUEUE) PROFILE(Q1) GROUP('mqgemapp')  AUTHADD(PUT)

So these messages in your queue manager's AMQERR01.LOG file are very useful when ensuring that your application, which is supposed to have access to use the queue manager and its objects, is granted the appropriate authorities. What about if you see such error messages when you are not expecting them?

In the case when you do not have an application asking for authorities to be granted, error messages such as these might be indicative of an application trying to use resources it is not allowed to use, or one that has been configured to point to the wrong queue manager. In this case, the error messages do not give you enough information to identify the application in question. It is at this point that it is useful to use Authority Event messages.

Authority Event messages are enabled on the queue manager using the following command:

ALTER QMGR AUTHOREV(ENABLED)

and are written to the SYSTEM.ADMIN.QMGR.EVENT queue. To show the difference between what is in an error message and an event message, the best way is to show an example.

[  624 bytes] Message Content
Command      :44 (QMgr Event)
Reason       :2035 (Not authorized.)
Parameter Id :2015 (QMgr Name)
Value        :'MQG1                                            '
Parameter Id :1020 (Reason Qualifier)
Value        :2 [0x'2'] MQRQ_OPEN_NOT_AUTHORIZED
Parameter Id :2016 (Q Name)
Value        :'Q1                                              '
Parameter Id :1022 (Open Options)
Value        :00002810
              00002000 Fail if quiescing
              00000010 Output
              00000800 Set all context
Parameter Id :3025 (User Identifier)
Value        :'mqgusr1     '
Parameter Id :1 (Appl Type)
Value        :11 [0x'B'] MQAT_WINDOWS_NT
Parameter Id :3024 (Appl Name)
Value        :'d:\nttools\q.exe            '
Parameter Id :3501 (Channel Name)
Value        :'MQGEM.SVRCONN       '
Parameter Id :3506 (Connection Name)
Value        :'127.0.0.1.............................................................'

As you can see, there is some additional information in the event message that helps with tracking down the application in question. You get the channel name and connection if this is a client connected application, and you get the application name as well. Hopefully this is enough to be able to figure out which application is trying to use your queue manager resources when it shouldn't be.

#Little-Gem
#IBMMQ
#ChampionsCorner