setmqaut (grant or revoke authority)

Change the authorizations to a profile, object, or class of objects. Authorizations can be granted to, or revoked from, any number of principals or groups.

For more information about authorization service components, see Configure installable services, Service components, and Authorization service interface.

For more information about how authorizations work, see How authorizations work.

From IBM MQ Version 8.0, on UNIX and Linux systems, the object authority manager (OAM) can use user-based authorization as well as group-based authorization. For more information about user-based authorizations, see Security: OAM user-based permissions on UNIX and Linux systems.


Syntax

setmqaut -m QMgrName -n Profile -t ObjectType -s ServiceComponent -p PrincipalName -g GroupName -u SIDMQI authorizationsContext authorizationsAdministration authorizationsGeneric authorizations +remove  -remove MQI authorizations +altusr  -altusr  +browse  -browse  +connect  -connect  +get  -get  +inq  -inq  +pub  -pub  +put  -put  +resume  -resume +set  -set  +sub  -sub Context authorizations +passall  -passall  +passid  -passid  +setall  -setall  +setid  -setid Administration authorizations +chg  -chg  +clr  -clr  +crt  -crt  +dlt  -dlt  +dsp  -dsp  +ctrl  -ctrl  +ctrlx  -ctrlx Generic authorizations +all  -all  +alladm  -alladm  +allmqi  -allmqi  +none  +system  -system


Description

Use setmqaut both to grant an authorization, that is, give a principal or user group permission to perform an operation, and to revoke an authorization, that is, remove the permission to perform an operation. We can specify a number of parameters:

  • Queue manager name
  • Principals and user groups
  • Object type
  • Profile name
  • Service component

The authorizations that can be given are categorized as follows:

  • Authorizations for issuing MQI calls
  • Authorizations for MQI context
  • Authorizations for issuing commands for administration tasks
  • Generic authorizations

Each authorization to be changed is specified in an authorization list as part of the command. Each item in the list is a string prefixed by a plus sign (+) or a minus sign (-). For example, if we include +put in the authorization list, you grant authority to issue MQPUT calls against a queue. Alternatively, if we include -put in the authorization list, you revoke the authority to issue MQPUT calls.

On UNIX, Linux, and Windows, we can use the SecurityPolicy attribute to control the queue manager authorization:

  • On Windows systems, the SecurityPolicy attribute applies only if the service specified is the default authorization service, that is, the OAM. The SecurityPolicy attribute allows you to specify the security policy for each queue manager.
  • On UNIX and Linux systems, for Version 8.0 and later, the value of the SecurityPolicy attribute specifies whether the queue manager uses user-based or group-based authorization. If we do not include this attribute, the default, which uses group-based authorization, is used.

For more information about the SecurityPolicy attribute, see Configure installable services, Configure authorization service stanzas on Windows, and Configure authorization service stanzas on UNIX and Linux.

For more information about the effect of the user and group settings of the SecurityPolicy attribute, see OAM user-based permissions on UNIX and Linux systems.

We can specify any number of principals, user groups, and authorizations in a single setmqaut command, but we must specify at least one principal or user group.

If a principal is a member of more than one user group, the principal effectively has the combined authorities of all those user groups.

On Windows systems, the principal also has all the authorities that are granted to it explicitly using the setmqaut command.

On UNIX and Linux, if the SecurityPolicy attribute is set to user, the principal has all the authorities that are granted to it explicitly using the setmqaut command. However, if the SecurityPolicy attribute is set to group or default, or if the SecurityPolicy attribute is not set, all authorities are held by user groups internally, not by principals. Granting authorities to groups has the same implications as it did before Version 8.0:

  • If we use the setmqaut command to grant an authority to a principal, the authority is granted to the primary user group of the principal. This means that the authority is effectively granted to all members of that user group.
  • If we use the setmqaut command to revoke an authority from a principal, the authority is revoked from the primary user group of the principal. This means that the authority is effectively revoked from all members of that user group.

To alter authorizations for a cluster sender channel that has been automatically generated by a repository, see Channel definition commands.


Required parameters

    -t ObjectType
    The type of object for which to change authorizations. Possible values are as follows:

    Value Description
    authinfo An authentication information object
    channel or chl A channel
    clntconn or clcn A client connection channel
    comminfo A communication information object
    listener or lstr A listener
    namelist or nl A namelist
    process or prcs A process
    queue or q A queue
    qmgr A queue manager
    rqmname or rqmn A remote queue manager name
    service or srvc A service
    topic or top A topic

    -n Profile
    The name of the profile for which to change authorizations. The authorizations apply to all IBM MQ objects with names that match the profile name specified. The profile name can be generic, using wildcard characters to specify a range of names as explained in Use OAM generic profiles on UNIX, Linux, and Windows systems. This parameter is required, unless we are changing the authorizations of a queue manager, in which case we must not include it. To change the authorizations of a queue manager use the queue manager name, for example 
    setmqaut -m QMGR -t qmgr -p user1 +connect
    where QMGR is the name of the queue manager and user1 is the principal for which we are adding or removing permissions. Each class of object has authority records for each group or principal. These records have the profile name @CLASS and track the crt (create) authority common to all objects of that class. If the crt authority for any object of that class is changed then this record is updated. For example: 
    profile:   @class
object type: queue
entity:   test
entity type: principal
authority:  crt
    This shows that members of the group test have crt authority to the class queue.


Optional parameters

    -m QMgrName
    The name of the queue manager of the object for which to change authorizations. The name can contain up to 48 characters.

    This parameter is optional if we are changing the authorizations of our default queue manager.

    -p PrincipalName
    The name of the principal for which to change authorizations. For IBM MQ for Windows only, the name of the principal can optionally include a domain name, specified in the following format: 
    userid@domain

    For more information about including domain names on the name of a principal, see Principals and groups on UNIX, Linux and Windows.

    We must have at least one principal or group.

    -g GroupName
    The name of the user group for which to change authorizations. We can specify more than one group name, but each name must be prefixed by the -g flag. For IBM MQ for Windows only, the group name can optionally include a domain name, specified in the following formats: 
    GroupName@domain
domain\GroupName

    The IBM MQ Object Authority Manager validates the users and groups at the domain level, only if you set the GroupModel attribute to GlobalGroups in the Securing stanza of the queue manager.

    -u SID
    The SID for which authorities are to be removed. We can specify more than one SID, but each name must be prefixed by the -u flag.

    This option must be used with either +remove or -remove.

    This parameter is only valid on IBM MQ for Windows.

    -s ServiceComponent
    The name of the authorization service to which the authorizations apply (if the system supports installable authorization services). This parameter is optional; if you omit it, the authorization update is made to the first installable component for the service.

    +remove or -remove
    Remove all the authorities from IBM MQ objects that match the specified profile.

    Authorizations
    The authorizations to be granted or revoked. Each item in the list is prefixed by a plus sign (+) or a minus sign (-). The plus sign indicates that authority is to be granted. The minus sign indicates that authority is to be revoked.

    For example, to grant authority to issue MQPUT calls, specify +put in the list. To revoke the authority to issue MQPUT calls, specify -put.

    Table 2 shows the authorities that can be given to the different object types.

    Authority Queue Process Queue manager Remote queue manager name Namelist Topic Auth info Clntconn Channel Listener Service Comminfo
    all 1 Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
    alladm 2 Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes
    allmqi 3 Yes Yes Yes Yes Yes Yes Yes No No No No No
    none Yes Yes Yes Yes Yes No Yes Yes Yes Yes Yes Yes
    altusr No No Yes No No No No No No No No No
    browse Yes No No No No No No No No No No No
    chg Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes
    clr Yes No No No No Yes No No No No No No
    connect No No Yes No No No No No No No No No
    crt Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes
    ctrl 4 No No Yes No No Yes No No Yes Yes Yes No
    ctrlx No No No No No No No No Yes No No No
    dlt Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes
    dsp Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes
    get Yes No No No No No No No No No No No
    pub No No No No No Yes No No No No No No
    put Yes No No Yes No No No No No No No No
    inq Yes Yes Yes No Yes No Yes No No No No No
    passall Yes No No No No No No No No No No No
    passid Yes No No No No No No No No No No No
    resume No No No No No Yes No No No No No No
    set Yes Yes Yes No No No No No No No No No
    setall 5 Yes No Yes No No No No No No No No No
    setid 5 Yes No Yes No No Yes No No No No No No
    sub No No No No No Yes No No No No No No
    system No No Yes No No No No No No No No No
    Notes:
    1. The authority all is equivalent to the union of the authorities alladm, allmqi, and system appropriate to the object type.
    2. The authority alladm is equivalent to the union of the individual authorities chg, clr, dlt, dsp, ctrl, and ctrlx appropriate to the object type. crt authority is not included in the subset alladm.
    3. The authority allmqi is equivalent to the union of the individual authorities altusr, browse, connect, get, inq, pub, put, resume, set, and sub appropriate to the object type.
    4. The authority ctrl on the qmgr object is included when the you specify alladm on the setmqaut command.
    5. To use setid or setall authority, authorizations must be granted on both the appropriate queue object and also on the queue manager object. setid and setall are included in allmqi.


Description of specific authorities

We should not grant a user an authority (for example, set authority on a queue manager, or system authority) that allows the user to access IBM MQ privileged options, unless the required authority is specifically documented, and required to run any IBM MQ command, or IBM MQ API call.

For example, a user requires system authority to run the setmqaut command.

    chg
    A user needs chg authority to make any authorization changes on the queue manager. The authorization changes include:

    A user also needs chg authority to change or set the attributes of an IBM MQ object, using PCF or MQSC commands.

    ctrl

    Within CHLAUTH rules it is possible to insist that users connecting are not privileged.

    For the channel to check whether a user is privileged, the real user id running the channel process must have +ctrl authority on the qmgr object.

    For example, when the SVRCONN channel is running as a thread in an amqrmppa process and the real uid for this process is a userid named mqadmin (the userid that started the queue manager), then mqadmin must have +ctrl authority on the qmgr object.

    crt

    If you grant an entity +crt authority to the queue manager, then that entity also gains +crt authority for each object class.

    However, when you remove +crt authority against the queue manager object that only removes the authority on the queue manager object class; crt authority for other objects classes are not removed.

    Note that crt authority on the queue manager object has no functional use, and is available for backwards-compatibility purposes only.

    dlt

    Note that the dlt authority against the queue manager object has no functional use, and is available for backwards-compatibility purposes only.

    set

    A user needs set authority against the queue to change or set the attributes of a queue using the MQSET API call.

    set authority on the queue manager is not required for any administrative purpose, or for any application connecting to the queue manager.

    However, a user needs set authority against the queue manager to set privileged connection options.

    Note that set authority on the process object has no functional use, and is available for backwards-compatibility purposes only.

    Important: Privileged connection options are internal to the queue manager and are not available in IBM MQ API calls used by IBM MQ applications.

    system

    The setmqaut command makes a privileged IBM MQ connection to the queue manager.

    Any user who runs IBM MQ commands that makes a privileged IBM MQ connection needs system authority on the queue manager.


Return codes

Return code Explanation
0 Successful operation
26 Queue manager running as a standby instance.
36 Invalid arguments supplied
40 Queue manager not available
49 Queue manager stopping
58 Inconsistent use of installations detected
69 Storage not available
71 Unexpected error
72 Queue manager name error
133 Unknown object name
145 Unexpected object name
146 Object name missing
147 Object type missing
148 Invalid object type
149 Entity name missing
150 Authorization specification missing
151 Invalid authorization specification


Examples

  1. This example shows a command that specifies that the object on which authorizations are being given is the queue orange.queue on queue manager saturn.queue.manager. 
    setmqaut -m saturn.queue.manager -n orange.queue -t queue
         -g tango +inq +alladm
    The authorizations are given to a user group called tango, and the associated authorization list specifies that the user group can:

    • Issue MQINQ calls
    • Perform all administration operations on that object

  2. In this example, the authorization list specifies that a user group called foxy:

    • Cannot issue any MQI calls to the specified queue
    • Can perform all administration operations on the specified queue 

    setmqaut -m saturn.queue.manager -n orange.queue -t queue
         -g foxy -allmqi +alladm
  3. This example gives user1 full access to all queues with names beginning a.b. on queue manager qmgr1. The profile applies to any object with a name that matches the profile. 
    setmqaut -m qmgr1 -n a.b.* -t q -p user1 +all
  4. This example deletes the specified profile. 
    setmqaut -m qmgr1 -n a.b.* -t q -p user1 -remove
  5. This example creates a profile with no authority. 
    setmqaut -m qmgr1 -n a.b.* -t q -p user1 +none


Related reference