Authorizing API Requests

Authenticated users must be authorized to issue API requests. A server authorization file, described in this section, can be used for this purpose, depending on how SMAPI is configured. For more information on configuring SMAPI to decide if a request is authorized, see the description of the authorization policy properties in Configuring SMAPI.

The authorization file contains entries that authorize authenticated users to perform specific functions for specific virtual images (target users) or lists of virtual images. Each entry is a single record in the file consisting of three fields. Field 1 contains the requesting user (authenticated user), field 2 contains the target virtual image or list field, and field 3 contains the requested function. Note that each entry may be represented as a name list. When a name list is used in the authorization file, all of the items in the list (image names and/or function names) are considered part of that authorization entry. Nested lists, however, are not expanded. If a list name is specified in the authorization file, the items in that list are treated as image or function names.

The authorization file is located on the source SFS directory (VMSYS:VSMWORK1.). It is placed there as part of the default z/VM installation. The default file name is VSMWORK1 AUTHLIST. If you choose to use a different name for the authorization file, you must specify the new name in variable AuthListFileIdAny in file DMSSICNF COPY. See the “Authorization List and Name List Configuration” entry in Configuring SMAPI.

There are Authorization_List APIs which can be used to update and query the authorization file without stopping the server. These APIs are listed under Authorization. Note that in order for a user to call any of the Authorization_List APIs, there must be an entry in the authorization file that specifically authorizes that user to do so.

The authorization file may also be updated manually. If the file is updated manually, the attributes of fixed record format (RECFM) with a record length (LRECL) of 195 must be maintained, and all entries must be in upper case.

The three fields are described in more detail below:

requesting user

This is the name of a user, or a list name for a list of users, who will be allowed to perform the requested function against the target virtual image or list. (Note that the requesting user is the same as the authenticated_userid on an API call.) The requesting user field must start in column 1 of the authorization file entry and be no more than 64 characters in length (8 characters for a single user and 64 characters for a list name).

target virtual image (or list)

This is the name of the virtual image, or a list name for a list of virtual images to be updated. A keyword ALL may also be specified to indicate that the requesting user is authorized to modify all virtual images (users). This field must start in column 66 of the authorization file entry and be no more than 64 characters in length (8 characters for a single user and 64 characters for a list name).

Note: Although an equal sign (=) is accepted by the Authorization_List APIs, it is not a valid token and should not be manually inserted in place of the target virtual image or list.

requested function

This is the function name, or the list name for a list of functions, that the requesting user is authorized to perform. A keyword ALL may also be specified to indicate an authorization file entry that allows the requesting user authorization to all functions for the specified target virtual image or list. This field must start in column 131 of the authorization file entry and is a maximum of 64 characters.

Names in the authorization file may be specified as one of the following:

name

Specific userid or virtual image or function

name list

The name of a list containing a group of userids or virtual images or functions

ALL

A keyword encompassing all userids or virtual images or functions

Figure 1 shows the default entries that are provided in the VSMWORK1 AUTHLIST file (headings are not included in the actual file).

Column 1                                     Column 66                                    Column 131
|                                            |                                            | 
|                                            |                                            | 
V                                            V                                            V 
DO.NOT.REMOVE                                DO.NOT.REMOVE                                DO.NOT.REMOVE
MAINT                                        ALL                                          ALL
IBMVM1                                       ALL                                          ALL