Authorize the CICS DA server ID

CICS® DA users can issue requests to the CICS DA server to run specific commands. You can use external security manager (ESM) facility classes to protect the commands so that only authorized users can run certain commands.

When the CICS DA server requests information from a CICSPlex® SM target server, it must do so securely. You can configure DA to secure these requests either by using passwords, or PassTickets. It is advised that you use the more secure method of using PassTickets.

A PassTicket is a password for a specified application that has a limited lifetime. The PassTicket can be used in place of a password provided it is generated for the application and it is still valid. By using PassTickets, you can validate a user at login, from their user ID and password, and then discard that password. When CICS DA logs in to another system such as a WUI server, CICS DA requests a PassTicket and uses that PassTicket.

Using PassTickets prevents security issues such as accidentally writing out passwords in trace and dumps, and PassTickets also remove the need for the user to put the password for the server user ID in the cphprops file. In addition, it ensures that the credentials that CICS DA uses to log in to WUI servers are not easily reusable if they are captured (either from a non-encrypted connection, CICS region trace, or a CICS DA trace).

For more information about PassTickets, see Using the Secured Signon Function in the Security Server RACF Security Administrator's Guide.

Procedure

  1. This authorization step is required for the CICS DA server ID to run the discovery function. Select one of the following choices:
    1. Set up PassTicket support for the DA server.
      Note: PassTicket support is required only for a WUI server. It is not required for a stand-alone CICS region (SMSS).

      All CICSPlex SM WUI or CMCI servers must be configured for PassTicket support for CICS DA discovery.

      When the CICS DA server receives a request from a CICS DA client, the client user ID and password are authenticated by the CICS DA server. The CICS DA server then requests a PassTicket from the security manager. The PassTicket, along with the user ID, is used to complete the client request to a CICSPlex SM target server. The PassTicket method is used as an alternative to sending unencrypted passwords across the network. RACF® (or some other external security manager) must be configured to use PassTicket support for all target CICSPlex SM servers.

      A PTKTDATA profile must be defined to RACF (or some other external security manager) for each target CICSPlex SM server. Before the PTKTDATA profiles are defined, your security administrator must activate the class by issuing a SETROPTS command for the PTKTDATA general resource class. The syntax for the RACF command is:

      		SETROPTS CLASSACT(PTKTDATA) RACLIST(PTKTDATA)

      If the PTKTDATA profile is already activated, then, it can be refreshed by issuing the following RACF command:

      		SETROPTS RACLIST(PTKTDATA) REFRESH

      When you define the PTKTDATA profile, the APPLID of the target CICSPlex SM server must be used as the profile name. The syntax for the RACF command is:

      		RDEFINE PTKTDATA target_server_applid SSIGNON(KEYMASKED(key_value))  +
          			APPLDATA(’NO REPLAY PROTECTION’)
      or alternatively, if Integrated Cryptographic Service Facility (ISCF) is active, you can use the following command:
      		RDEFINE PTKTDATA target_server_applid SSIGNON(KEYENCRYPTED(key_value))  +
          			APPLDATA(’NO REPLAY PROTECTION’)

      Where key value is the 64 bit (8 byte) key that is assigned by your RACF security administrator. The key is entered as 16 hexadecimal characters. You must use the NO REPLAY PROTECTION option because more than one PassTicket might be requested within 1 second.

      The DA server uses a UNIX System Services service for generating PassTickets from RACF. The user ID of the DA server must be authorized to obtain PassTickets on behalf of a client user ID for a target CICSPlex SM server. The syntax for the RACF commands to configure this authorization are:

      		RDEFINE PTKTDATA IRRPTAUTH.target_server_applid.* UACC(NONE)
      		PERMIT IRRPTAUTH.target_server_applid.* CLASS(PTKTDATA) ID(DA_server_id or group) ACC(UPDATE)
      Where target_server_applid is the APPLID of the WUI server where the CMCI port is defined.

      For more information about defining PTKTDATA general resource class profiles, see the z/OS Security Server RACF Security Administrator’s Guide.

    2. Set up password support for the DA server.
      The CICS DA properties file contains the properties for the CICS DA V5.3 server process. A sample file, cphprops is provided in the z/OS® UNIX directory /usr/lpp/cicsda/v530/samples/ that was created during the SMP/E process. It is good practice to copy the sample file and place it in a different location before you change the file. You can choose to save the file anywhere in your z/OS UNIX file system. However, a practical solution might be to create a directory in the same folder you created for the server files. That way, all files are in the same place.
      Note: If a password is used, it is advised that you restrict access to the cphprops file.

      To use password support, you must set the com.ibm.cph.server.userid and com.ibm.cph.server.password properties in your copy of the cphprops file. The comments in the sample cphprops file provide more information of the properties that must be set.

  2. Authorize the CICS DA server ID to run the discovery function on MVS™ images.

    CICS DA runs a batch-based utility program, CPHDISC, as part of discovery processing. This program identifies CICS and other subsystems that are running on the MVS image. Discovery is run under the server user ID. The server user ID must have authority to discover subsystems on all MVS images. If the server user ID does not have authority to access an MVS image, the subsystems on that MVS image are not shown in the model.

    The server user ID requires READ access to a FACILITY class resource called CPH.server_id.DISCOVER.MVS.system_name where system_name is the name of the z/OS system, and server-id is the optional server identity name. The server identity name is specified in the CICS DA properties file. You can use the server identity name to specify different command protection on multiple servers that are running in the same Sysplex. If you did not specify a server identity in the properties file, you can omit server-id from the following commands.

    To enable this checking, the FACILITY class must be activated on the target MVS system. See the appropriate documentation for your external security manager for details. When the class is activated, you can define security profiles to start protecting the discovery utility.

    For example, RACF users might use the following TSO commands:

    		RDEFINE FACILITY CPH.server_id.DISCOVER.MVS.** UACC(NONE)
    		PERMIT CPH.server_id.DISCOVER.MVS.** CLASS(FACILITY) ID(SYSPROG) ACCESS(READ)
    
    		RDEFINE FACILITY CPH.server_id.DISCOVER.MVS.TST1 UACC(NONE)
    		PERMIT CPH.server_id.DISCOVER.MVS.TST1 CLASS(FACILITY) ID(SYSPROG,TSTUSR1) ACCESS(READ)
    
    		SETROPTS RACLIST(FACILITY) GENERIC(FACILITY) REFRESH 
    where server_id is the CICS DA server ID.

    In the example, the first pair of commands defines a generic profile that grants access for user, or group, SYSPROG to run discovery on any system. The second pair of commands defines a discrete profile that protects a system that is called TST1. The users, or groups, SYSPROG, and TSTUSR1, are given access to TST1.

    The sequence of commands in the example grant permission for the user, or group, SYSPROG to run discovery on any system, and the user TSTUSR1 to run discovery only on system TST1.

    CICS DA uses the UNIX System Services host service to query the domain name server and resolve the IP address to a name. You must ensure that any running discovery has authority to start the UNIX System Services host command.

  3. Set up CICS DA command protection.

    CICS DA users can issue requests to the server to run specific commands under their client user ID. You can use external security manager (ESM) facility classes to protect the commands, so that only authorized users can run certain commands. This protection is in addition to any underlying ESM checks that exist on data sets or within CICSPlex SM.

    To enable this checking, the FACILITY class must be activated on the target MVS system. See the appropriate documentation for your external security manager for details. When the class is activated, you can define security profiles to start protecting the discovery utility.

    For example, RACF users might use the following TSO commands:

       RDEFINE FACILITY CPH.server_id.MODEL.POLICY.** UACC(NONE)
       PERMIT CPH.server_id.MODEL.POLICY.** CLASS(FACILITY) ID(SYSPROG) ACCESS(UPDATE)
    
       RDEFINE FACILITY CPH.server_id.MODEL.POLICY.APPL1 UACC(NONE)
       PERMIT CPH.server_id.MODEL.POLICY.APPL1 CLASS(FACILITY) ID(SYSPROG,TSTUSR1) ACCESS(UPDATE)
    
       SETROPTS RACLIST(FACILITY) GENERIC(FACILITY) REFRESH
    where server_id is the CICS DA server ID.

    In the example, the first pair of commands defines a generic profile that grants access for user, or group, SYSPROG to modify any start or stop policy. The second pair of commands defines a discrete profile that protects CICS model entities with an APPLID of APPL1. The users, or groups, SYSPROG, and TSTUSR1, are given access to change the start and stop policy for CICS model entities with an APPLID of APPL1.

    The sequence of commands in the example grant permission for the user, or group, SYSPROG to change any start or stop policy on CICS DA servers with an identity of server_id, and the user TSTUSR1 to change the start or stop policy only on CICS model entities with an APPLID of APPL1.

    The following table lists the CICS DA FACILITY class profiles in the ESM FACILITY classes, and their uses:
    Note: If you did not specify a server identifier in the DA properties file, then the profiles must start withCPH. instead of CPH..server_id
    Table 1. CICS DA FACILITY class profiles in the ESM FACILITY classes, and their uses
    FACILITY class profile Use
    CPH.server_id.DISCOVER.MVS This FACILITY class profile is not part of command protection. However, it is used by the server process during discovery. READ access level is required.
    CPH.server_id.** Enable/disable all user command actions. ALTER access level is required.
    CPH.server_id.DISCOVER Enables clients to invoke discovery for the named server. READ access level is required.
    CPH.server_id.MODEL Enables clients to read, or act on, the CICS DA model. This profile can have different access levels:
    READ
    Enables clients to obtain the discovered model
    UPDATE
    Enables clients to change discovered model elements. (UPDATE is required to change JES member name, change CMAS network name, and add and remove tags)
    ALTER
    Enables clients to delete discovered model elements
    CPH.server_id.MODEL.POLICY.* Enables clients to change the start and stop policies with specific APPLIDs (or * for all). UPDATE access level is required.
    CPH.server_id.MODEL.TAG.CREATE Enables clients to create new tags. This class requires UPDATE access.
    CPH.server_id.MODEL.TRANSFRM Enables clients to create, update, and delete the name transform rule sets. This profile can have different access levels:
    UPDATE
    Enables clients to create or update name transform rule sets.
    ALTER
    Enables clients to delete name transform rule sets.
    CPH.server_id.REGION.CLONE Enables clients to clone regions. This class requires READ access.
    CPH.server_id.REGION.PLEXIFY Enables clients to add a region to a CICSplex. This class requires READ access.
    CPH.server_id.REGION.CREATE Enables clients to create new regions. This class requires READ access.
  4. Provide MVS console access for the CICS DA server ID. This authorization is required for the discovery function.

    CICS DA uses the MVS console interface for some actions, so the CICS DA server, and the users, require access to the commands issued by CICS DA, and also authority to access the console. RACF users can control access to the console by using a suitable profile in the OPERCMDS class. For example:

    		RDEFINE OPERCMDS MVS.MCSOPER.console_name UACC(NONE)
    		PERMIT MVS.MCSOPER.console_name CLASS(OPERCMDS) ID(cics-da-user) ACCESS(READ)
    		SETROPTS RACLIST(OPERCMDS) GENERIC(OPERCMDS) REFRESH 

    console_name is the name of the console, and cics-da-user is the user authorized to use the console.

    The console name that is used by the CICS DA user is specified on the CICS DA connection in the z/OS console setting.

    You must ensure that only the specified user is allowed to use the console, especially if CICS terminal definitions or autoinstalled consoles use preset security.

  5. This authorization step is required for the CICS DA server ID to run the discovery function. Create a TSO segment for the user ID that the CICS DA server job is running under, and make the user ID a member of the TSOAUTH class. The length of the user ID must be 7 characters or less before you can define the TSO segment. CONSOLE COMMAND authority is granted by using the CONSOLE profile in the TSOAUTH class. For example:
    		RDEFINE TSOAUTH CONSOLE UACC(NONE)
    		SETROPTS RACLIST(TSOAUTH)
    		PERMIT CONSOLE CLASS(TSOAUTH) ID(...) ACCESS(READ)
    		SETROPTS RACLIST(TSOAUTH) REFRESH 

    Depending on your security manager, more setup might be required to use the console. For example, RACF users might require an OPERPARM segment that is associated with the TSO user ID. For more information, see z/OS MVS Planning: Operations.

  6. Provide the server user ID with MVS command security. This authorization step is required for the CICS DA server ID to run the discovery function.
    To run the discovery operation, the server user ID must have access to the following z/OS commands:
    DISPLAY TCPIP
    Class: OPERCMDS resource name
    Resource name: MVS.DISPLAY.TCPIP
    Access required: READ
    To initiate a shutdown of a CICS region from CICS DA, users must have access to:
    Modify cics_jobname
    Class: OPERCMDS
    Resource name: MVS.MODIFY.cics_jobname
    Access required: UPDATE
    Note: For started tasks and started jobs, the profile name might be slightly different. For more information, see z/OS MVS Planning: Operations.
  7. Authorize the CICS DA server ID to access the OMVSAPPL resource in the CLASS(APPL) This authorization step is required for the CICS DA server ID to run the discovery function. You must ensure that the server ID has the necessary authority. For more information about controlling access to applications, see the z/OS UNIX System Services Planning documentation.
  8. Authorize the CICS DA server ID to have full access to all CICSPlex SM and CICS objects in the external security manager. This authorization step is required for the CICS DA server ID to run the discovery function. The CICS DA server requires authorization to access all CICSPlex SM resources, otherwise the discovery operation might fail, or return unexpected results. You must ensure that the server ID has the necessary authority. For more information about implementing CICSPlex SM security, see CICSPlex SM security.
  9. Authorize the server to run tasks under the logged-in client user ID.

    The CICS DA server ID must be able to switch to the client user ID to run tasks with the client authority. This ability is enabled by giving the server user ID UPDATE access to the BPX.SERVER profile in class FACILITY and defining BPX.SRV profiles for the SURROGAT class, in your System Authorization Facility (SAF).

    The following example shows the RACF command that is required to give access to the BPX.SERVER:

    		PERMIT BPX.SERVER ID(CPHSRV) CLASS(FACILITY) ACCESS(UPDATE)
    		SETROPTS RACLIST(FACILITY) REFRESH

    If the SURROGAT class is not already active, you can activate it using the following RACF command:

    		SETROPTS CLASSACT(SURROGAT) RACLIST(SURROGAT)
    Note: Adding SURROGAT to RACLIST is optional.

    Caution: You can define BPX.SRV.userid profiles for each client, or you might prefer to use a generic profile that covers some or all users. In any case, the surrogate access that is allowed via BPX.SRV profiles is not confined to CICS DA, and caution is advised where the server user ID (CPHSRV in the following example) is used for other servers or tasks.

    If generic processing for the SURROGAT class is not already active, you can activate it using the following RACF command:

    		SETROPTS GENERIC(SURROGAT)

    The following example shows the RACF commands that you might use to create the generic profile, where the CICS DA server user ID is CPHSRV:

    To define the BPX.SRV.** generic profile, use the following RACF command:

    		RDEFINE SURROGAT BPX.SRV.** UACC(NONE)
    		PERMIT BPX.SRV.** CLASS(SURROGAT) ACCESS(READ) ID(CPHSRV)
    		SETROPTS GENERIC(SURROGAT) REFRESH
    		SETROPTS RACLIST(SURROGAT) REFRESH 
    Note: The last SETROPTS command is required only if you previously added SURROGAT to RACLIST
    For more information about SURROGAT job submission, see the related links.

  10. Authorize CICS DA client IDs to submit jobs when provisioning.

    Every user that submits jobs through the CICS DA server, for example to clone CICS regions, must have access to the CICS DA server SUBMIT profile in the SURROGAT class.

    The following example shows the RACF commands that you might use to enable this access, where CPHSRV is the CICS DA server user ID and cics-da-user is the client user ID:
    RDEFINE SURROGAT cics-da-user.SUBMIT OWNER(cics-da-user) (UACC(NONE)
    PERMIT cics-da-user.SUBMIT CLASS(SURROGAT) ID(CPHSRV) ACCESS(READ)
    SETR RACLIST(SURROGAT) REFRESH 

    For more information about SURROGAT job submission, see the related links.

What to do next

Complete the remaining tasks to configure CICS DA. For more information, see the related tasks.


authorize_users_cicsda_server.html | Timestamp icon Last updated: Friday, 11 December 2015