RACLINK (Administer user ID associations)

Purpose

Issuing options

The following table identifies the eligible options for issuing the RACLINK command:

For information on issuing this command as a RACF TSO command, refer to RACF TSO commands.

For information on issuing this command as a RACF operator command, refer to RACF operator commands.

You must be logged on to the console to issue this command as a RACF operator command.

Related commands

• To add a user profile, see ADDUSER (Add user profile).
• To display information from a user profile, see LISTUSER (List user profile).
• To change a user profile, see ALTUSER (Alter user profile).
• To delete a user profile, see DELUSER (Delete user profile).
• To obtain a list of user profiles, see SEARCH (Search RACF database).

Authorization required

When issuing this command as a RACF operator command, you might require sufficient authority to the proper resource in the OPERCMDS class. For details about OPERCMDS resources, see "Controlling the use of operator commands" in z/OS Security Server RACF Security Administrator's Guide.

You have the authority to issue the RACLINK command for your own user ID.

To issue the RACLINK DEFINE command you must also have sufficient authority to the proper profiles in the RRSFDATA class. For RACLINK DEFINE, this is the first security check performed. For more information, see z/OS Security Server RACF Security Administrator's Guide.

Parameters

subsystem-prefix

Specifies that the RACF subsystem is the processing environment of the command. The subsystem prefix can be either the installation-defined prefix for RACF (1 - 8 characters) or, if no prefix has been defined, the RACF subsystem name followed by a blank. If the command prefix was registered with CPF, you can use the MVS command D OPDATA to display it or you can contact your RACF security administrator.

Only specify the subsystem prefix when issuing this command as a RACF operator command. The subsystem prefix is required when issuing RACF operator commands.

ID(userid1 ...)

Specifies the user for whom the RACLINK operation is to be performed. Specify one or more user IDs on the RRSF node from which the command is issued.

If this operand is not specified, the command defaults to the user issuing the command at the node where the command is issued.

LIST([node | *].[userid2 |*] ...)

Specifies that a list of associations for node.userid2 is to be displayed. If multiple user IDs are specified, then multiple lists are displayed, one for each user ID specified.

RACLINK LIST (*.*) is the default. RACLINK LIST (*.*) lists all user ID associations for the specified user ID or the issuer's user ID if the ID keyword is not specified.

If the node name is not specified, the default is the local node.

The node names you specify must have been defined as RRSF nodes with the TARGET command.

The following information is displayed for each user ID association:

• User ID association type
  • Peer association
  • Managed association (including whether the specified user ID is the managed user ID or the managing user ID)
• Password synchronization status
  • YES (password synchronization is active)
  • NO (password synchronization is inactive)
  • N/A (password synchronization is not applicable to a managed association)
• User ID association status
  • PENDING APPROVAL BY userid (waiting for userid to approve or reject the user ID association)
  • ESTABLISHED (the user ID association has been approved)
  • SYSTEM ERROR (an unexpected error occurred on the target node that prevented the user ID association from being completed) The user ID association should be deleted and then defined again. See the notes under the DEFINE keyword for additional details.

DEFINE([node].userid2[/password] ...)

Specifies that a user ID association is to be formed between userid1 at the node where the command was issued, and userid2 at node. If you specify more than one node.userid2 operand, an association is established between userid1 and each node.userid2 specified. A user ID association enables RACF users to utilize command direction and password synchronization.

If the password or phrase contains special characters that cause problems with TSO/E, the entire string ([node].userid2[/password]) must be enclosed in single quotation marks. For example, if the phrase contains blanks, or special characters such as the comma, parenthesis, or comment delimiter (/*), the string must be enclosed in quotes. Likewise, when a password or phrase starts with an asterisk, the string must be enclosed in quotes.

To issue the RACLINK DEFINE command, you need READ access to the following profile in the RRSFDATA class:

• RACLINK.DEFINE.node

The RRSFDATA class must be active.

When the DEFINE keyword is specified and the command issuer has sufficient authority to perform the RACLINK command for the user ID, the user ID association is implicitly approved if any of the following are true:

• A valid password is supplied for node.userid2 on the DEFINE keyword.
• The command issuer has one of the following authorities over userid2 on the DEFINE keyword:
  • The command issuer has the SPECIAL attribute.
  • The profile is within the scope of a group in which the command issuer has the group-SPECIAL attribute.
  • The command issuer is the owner of the profile.
• The command issuer has an association with a user ID on the node specified on the DEFINE keyword. That association must be either a PEER association or a MANAGED association with the command issuer as the manager. The user ID with which the command issuer has the association must have one of the following authorities over userid2 on the DEFINE keyword:
  • The command issuer has the SPECIAL attribute.
  • It is within the scope of a group that has the group-SPECIAL attribute.
  • It is the owner of the profile.

Otherwise, a user ID association requires explicit approval by node.userid2 with the RACLINK APPROVE command.

Although it is possible for the command issuer to have more than 50 associated user IDs on the target node, only the first 50 are used for authority checking. RACLINK issues a message if more than 50 user ID associations exist for the command issuer.

An association is PENDING until node.userid2 either approves the association with a RACLINK APPROVE command or rejects the association with a RACLINK UNDEFINE command.

Note:

1. Under certain circumstances, RACLINK DEFINE(node.userid) requests can be issued by two users. If both requests are consistent, RACF treats this as an implicit approval. The entry is marked established in the target user IDs profile. An entry is considered consistent if the association type (PEER(PWSYNC) or PEER(NOPWSYNC)) is the same. If the request is not consistent (for example, differing PEER definitions or both users requesting a MANAGED association), RACF fails the request and the entries remain in a pending state. In order to correct this situation, the user(s) need to undefine and redefine the user ID associations.
2. When creating a user ID association with a revoked user ID:
   • If a RACLINK DEFINE command is coded without the password operand and the target user ID is a revoked user, the results vary depending on the authority of the command issuer and the user ID associations of the command issuer. When:

     The user ID association with the revoked user ID is created and the status displayed by a RACLINK LIST command is ESTABLISHED when one of the following is true:

     • The command issuer has sufficient authority (SPECIAL, group-SPECIAL, or owner) over the target user ID or
     • The command issuer has a PEER association or is the manager of a MANAGED association with a user ID on the target node and the associated user ID has sufficient authority over the target user ID.
3. If a RACLINK DEFINE command is coded without the password operand, the target user ID is a revoked user ID, and the command issuer does not have sufficient authority (SPECIAL, group-SPECIAL, or owner) over the target user ID, the user ID association is created and the status displayed by a RACLINK LIST command is PENDING APPROVAL BY userid2.
4. If a RACLINK DEFINE command is coded with the password operand and the target user is a revoked user, the user ID association is not established and the status displayed by a RACLINK LIST is SYSTEM ERROR.
5. If a RACLINK DEFINE command is coded with a password phrase and the target system is at a release before z/OS V2R2, the association will be in the PENDING APPROVAL state and message IRRT032I will not be issued. In this case, the target user ID must log on and explicitly approve the request.
6. If a RACLINK DEFINE command is attempted to a node which is denying inbound work, the user ID association is not established and the status displayed by a RACLINK LIST is SYSTEM ERROR.

The type of association you want to establish is specified with one of the following:

MANAGED

Specifies a managed association.

A managed association does not provide password synchronization. A managed association allows commands to be directed from the managing user ID to the managed user ID (that is, from userid1 to node.userid2).

A managed association does not allow commands to be directed from the managed user ID to the managing user ID (that is, node.userid2 cannot direct commands to userid1).

PEER(NOPWSYNC)

Specifies a peer association without password synchronization.

Either user ID in a peer association can direct commands to the other user ID in the association.

If no association type is specified, PEER(NOPWSYNC) is the default.

PEER(PWSYNC)

Specifies a peer association with password synchronization.

Either user ID in a peer association can direct commands to the other user ID in the association.

If either user in the association changes their password, the password is automatically changed for the other user in the association.

READ access to the RACLINK.PWSYNC.node resource is required to use the RACLINK command to define a peer association with the PWSYNC attribute. READ access to the PWSYNC resource is required to synchronize the passwords when one of the associated users changes their password.

If the RRSFDATA class is not active, you cannot define an association with the PWSYNC attribute, or synchronize passwords.

UNDEFINE([node].userid2 ...)

Specifies that a user ID association is ended between userid2 on node and userid1 on the node where the command is processed. Either member of an association can end an association.

If a user ID has attempted to establish an association with your user ID which requires approval, and you do not want to approve it, use the UNDEFINE keyword to reject the pending association.

APPROVE([node1].userid1 ...)

Specifies that userid2 on node2 approves of a pending association between userid2 at node2 and userid1 at node1. node1 is the node where the RACLINK DEFINE was issued, and node2 is the node where userid2 issues the command.