Figure 1: MF Directory Server Start Screen
If you enable external security in Enterprise Server, then you need to understand the implications and how security is checked upon an action. This document describes the relationship between a user and the different classes used to implement security.
In order to use External Security with Enterprise Server, you need first to create users and groups in Active Directory. These users and groups will have different properties, these properties will be used to verify that the user can access a resource.
This topic assumes that you have already read the Introduction to Enterprise Server Security topic. More documentation on CICS and RACF can be found at: .
Terms used in this document.
| TERM | Description |
|---|---|
| ACL | An ACL is a list of zero or more Access Control Entries, or ACEs. ACEs aren't related to ACEEs. |
| ACE | An ACE is a set of permissions granted to a user or group |
| ACEE | An ACEE (Access Control Environment Element) represents a single signed on userid with his defined properties. (There is one ACEE block per signed User in the system). |
| Resource | RESOURCES are identified by both a CLASS name and ENTITY name. A RESOURCE is anything that you can restrict access to, such as a transaction or file. |
| Class | A CLASS is used to identify a collection of ENTITIES. |
For a description of the classes used in Enterprise Server, their meanings, the types of entities that they contain and the minimum permissions that users require on those enties, see Resource Classes used by Enterprise Server
To define a user or a group in Active Directory, the easiest way would be to use an LDIF(LDAP Directory Interchange Format) file with the properties you want to define for the user or the group, and then use the ldifde command to import the definitions into Active Directory. You can also use ADSI Edit.
From a command prompt run: ldifde -i -f filename.ldf -s localhost:389 -k -v -j . (There is a dot at the end of the command)
In all the definitions we use DC=local. Note that this only applies if you are using ADAM as your LDAP directory. If you use Active Directory, rather than ADAM, DC must be equal to the domain name of your Active Directory domain, e.g. DC=mftesting,DC=com. For instance, if we want to create a user called "SEC01" with a default group of "PAYROLL", we will have a definition in our LDIF file as shown by the example in Defining a user with LDIF.
We then need to create the default group for the user: (A user can be part of several groups, but has one and only one default group). This is illustrated by the example in Defining a group with LDIF.
When a user logs into Enterprise Server, a call to the External Security Module (ESM) is made to verify the user, if the call is successful an ACEE (Access Control Environment Element) is created with the properties defined for the user. This ACEE will be used to check the user authority when accessing the Enterprise Server different resources.
Enterprise Server has a set of default users that are used when no user is logged on for CICS, JES, IMS or ESMAC authentication. These users and the environment variables with which you can override them are detailed in Enterprise Server Default Users and Associated Enviroment Variables.
Using the environment variables, the default users can be overwritten by the users of your choice. For instance we could overwrite the ESMAC default user using in the region configuration:
[ES-Environment] ES_USR_DFLT_ESMAC=ESMACUSR
When a region is configured to use external security, a userid and password need to be used in order to be able to start the region. The userid and password are passed on the command line for CASSTART as :
casstart -rRegionName -uUserid -pPassword -cGroupid
If no groupid is specified, then the user default groupid is used.
The userid or the default group that the user belongs to, needs to be defined in the OPERCMDS class for the entity casstart in Active Directory with alter permissions (see es_default_ldap.ldf file for an example). The userid also needs to be added to the #System group.
To stop a region defined with an external security module, a userid and password need to be used in order to be able to stop the region. The userid and password are passed on the command line for CASSTOP as :
casstop -rRegionName -uUserid -pPassword -cGroupid
If no groupid is specified, then the user default groupid is used. The userid or the default group that he belongs to, needs to be defined in the OPERCMDS class for the entity casstop in Active Directory with alter permissions (see es_default_ldap.ldf file for an example). The userid also needs to be added to the #System group.
The command line utilities: casstart, casstop, casfile, casout, and cassub can be invoked by program using the call interface and passing the command line parameters to the call. For instance to start a server we can use:
01 ws-cmd-parms.
05 ws-cmd-len pic x(02) comp-x.
05 ws-cmd-value pic x(1024).
......
......
......
*> Start up the Server
move 1 to ws-cmd-len
move low-values to ws-cmd-value
string "-rMyRegion" delimited by size
" -uSYSAD -pSYSAD /w" delimited by size
into ws-cmd-value with pointer ws-cmd-len
end-string
subtract 1 from ws-cmd-len
call 'casstart' using ws-cmd-parms end-call
......
......
From MFDS when pressing Start or Stop you will need to enter the Userid
and Password on the following screen as :
Figure 1: MF Directory Server Start Screen
When a region starts with security enabled, the userid used to start the region will be verified against #System group and then against the class OPERCMDS for the casstart entity for alter privileges. You can define the resources in Active Directory using an LDIF file as show in Defining CAS resources with LDIF.
The user credentials for the user who started the region (CICS region userid) will be used in CICS to open the files declared in the CICS FCT , so these files need to be declared in Active Directory and the user needs to have authority to update them. If the file is defined in the FCT with the option to use the catalog, then the ENTITY name needs to match the DATASET NAME used in the catalog.
For instance if the FCT has a FILEA defined to use the catalog with a DATASET NAME of MFI01.MAG.FILEA then the ENTITY that CICS will use to check privileges will be MFI01.MAG.FILEA
If the file is defined in the FCT and does not use the catalog, then the ENTITY that CICS will use would be the physical filename including path. For instance, if the FCT has a FILEA defined, the filename will searched on disk using the "File Path" defined in the region configuration. Supposing that the filename including the path is D:\TEMP\FILEA.DAT, you will need to enter in ADSI Edit or in your LDIF file the following.
D\3A\\TEMP\\FILEA.DAT (3A is the hex value for ":" as this is a special character in LDAP, also you need to escape "\" the special characters)
You can define these files in Active Directory using an LDIF file as shown in the example, Defining files with LDIF.
When the region has finished to open the files, it will execute any program defined in the CICS PLTPI.
Ensure that PLTPI security is enabled at the desired level by using the ES_ESM_PLTPISEC environment variable. The variable can take the following values: NONE if no security checking should be done for PLTPI programs (this is the default), RESSEC for Resource Security checking, CMDSEC for CICS command security checking, ALL for both RESSEC and CMDSEC .
When security is activated for PLTPI processing, if you do not specify the ES_ESM_PLTPIUSR environment variable, CICS runs PLTPI programs under the authority of the CICS region userid, in which case CICS does not perform a surrogate user check. However, the CICS region userid must then be authorized to all the resources referenced by the PLT programs. Furthermore, the CICS region userid is associated with any transactions started by PLT programs, and therefore must be authorized to run such transactions.
If you specify a Userid for the PLT processing using ES_ESM_PLTPIUSR then you need to ensure that the CICS region userid is authorized as a surrogate of the PLT userid defined on the ES_ESM_PLTPIUSR environment variable. This means granting the CICS region userid access to a SURROGAT resource class profile owned by the PLT userid, as shown in the following example, where the CICS region userid is SYSAD, and the PLT security userid is PLTPISUR .
You can define the SURROGAT class and users in Active Directory using an LDIF file as defined in the example, Defining the SURROGAT class and users with LDIF.
During shutdown, CICS runs PLT programs under the authority of the userid for the transaction that requested the shutdown.
You can also set the level of security checking that you want to use for PLTPI processing using the environment variable ES_ESM_PLTPISEC. This variable is described in Variables for Configuring MTO Security Behaviour.
When security is active for a CICS region, a user must log onto CICS using the CESN transaction, otherwise the default CICSUSER will be used.
Figure 2: CICS Signon screen
If a groupid is not entered then the user will be logged using the default group that he belongs to. Once the user is signed on, the credentials for the user will be used until you sign on again as another user, or the session expires.
When security is active for an Enterprise Server, a user must log onto ESMAC using the signon screen, otherwise the default mfuser will be used.
Figure 3: ESMAC Signon screen
If a groupid is not entered then the user will be logged using the default group that he belongs to. Once the user is signed on, the credentials for the user will be used until another user is signed on, or the session expires.
When executing a transaction CICS uses 3 different categories to define the level of security to implement.
| Category 1 transactions | Transactions that are never associated with a terminal - that is, they are for CICS internal use only, and should not be invoked from a user terminal. |
| Category 2 transactions | Transactions that are initiated by the terminal user, or are associated with a terminal, and for which access should be restricted to specific signed-on users. |
| Category 3 transactions | Transactions that are either initiated by the terminal user, or are associated with a terminal, and for which access is required by all terminal users, whether signed-on or not. |
Once the user is signed on to CICS, an ACEE is created for the user with all his properties defined.
When a user executes a transaction from a terminal, CICS will first check in the CICS definitions (PCT table) that the transaction is declared and enabled .
If it is, it will then make an AUTH call to the External Security Module with the user ACEE to check that the user has authority to run the transaction. The transaction needs to be defined in the TCICSTRN class with read access granted for the user. The default class name for transactions is TCICSTRN, but this can be changed using the environment variable ES_CLASS_XTRAN. The name would always be prefixed by a "T" so if you set the variable as:
ES_CLASS_XTRAN=CLASSTR
CICS will be checking against the class called TCLASSTR. You can define all the transactions and user privileges using and LDIF file as shown in the example, Defining a CICS Transaction with LDIF:
Figure 4: Relationship between LDAP classes
A user enters a transaction on a terminal.
If the transaction is defined in the PCT with the Cmd flag checked, then every CICS system programmer commands such as INQUIRE, SET, PERFORM, and COLLECT will be checked for access in the CCICSCMD class.
The following environment variable can affect the rule: ES_ESM_RESSEC=ASIS|ALWAYS.
ASIS (default) specifies you must use the value specified for RESSEC(RLS and Cmd flag) on the transaction definition. ALWAYS specifies that CICS ignores the RESSEC on the transaction definition; and it always calls RACF for every resource access. This can result in poor performance.
You can turn off the resource security for the resource itself using the relevant environment as described in Environment Variables for CICS Resource Classes.
For instance if you set ES_CLASS_XTRAN to the value MYTRANS then CICS will look for TMYTRANS as the class.
If you issue an EXEC CICS START TRANSID command with no TERMID parameter specified, CICS will check permissions against the ACICSPCT class. If you specify the TERMID parameter, CICS will check permissions against the TCICSTRN class. If you specify the USERID parameter, CICS will also check that the signed on user is a surrogate for USERID in the SURROGAT class.
JES Dataset Setup:
Our initial recommendation for JES would be to allow everyone access to the JESJOBS, JESINPUT, and JESSPOOL and control access via DATASET access rules. In a typical mainframe shop a high level qualifier is used to determine whether a user has access to a given set of datasets.
To that end, we would define Group rules for development teams which had access to one set of high level qualifiers followed by individual rules for developers for their own work spaces. Given a Team where everyone's userid starts with TV and we had team members TVDF, and TVMG, and the second two levels are their initials we might have the following DATASET rules:
Entity ACL
TV** - allow:TVTEAM group:alter
deny:*:execute
TVDF** - allow:TVDF:alter
deny:*:execute
TVMG** - allow:TVMG:alter
deny:*:execute
This set of rules would allow TVDF and TVMG to share any TV01.* or TV02.* datasets and not allow anyone but the individual users to access datasets that started with their userid.
Spool Restriction
If you find it necessary to restrict who can view the spooled output then you can implement rules for JESSPOOL. If you want everyone to access everything and have the ability to purge jobs, requeue them, etc then you can get by with an Entity of ** which has an acl of allow:*:alter. If you had one group for which you didn't want anyone else to access their spooled output or have any form of control over their spooled output then you could define a rule as follows. (Assumes a group is already defined named "Payroll" and all of their jobs run under the userid of PAYME. An additional example is provided where all jobnames start with the first 3 letters "PAY" in case you restrict access based on jobname instead of userid) The rules are based on the following entity format:
localnodeid.userid.jobname.jobid.dsnumber.name
Entity: ACL
** allow:*:alter
*.PAYME.** allow:Payroll group:alter
deny:*:execute
*.*.PAY** allow:Payroll group:alter
deny:*:execute
You can even write rules that restrict access down to individual DD's within a job. This is unlikely to be needed for a typical shop but it's there if you want it.
The "localnodeid" will always be the name of your Enterprise Server, userid is the name of the person under who's authority the job was executed, jobname I the name of the job from the jobcard, jobid is the job number, dsnumber is the relative dd within the job, and name is the ddname.
Resources are identified by class and entity name. To control access to a resource, there must be an object in the LDAP directory that matches the resource entity name, within the namespace of the class name. These objects are sometimes referred to as "rules". Each object, of the "microfocus-MFDS-Resource" type, will have an attribute that contains an ACL (Access Control List).
In LDAP, the ACL is defined as a multi-valued attribute. Each value is an ACE (Access Control Entry), which specifies:
A setting of "allow" grants the specified permission; "deny" denies it. Use "deny" sparingly; it takes precedence over allow and may have unanticipated consequences. It's somewhat more useful with enhanced permissions than with zOS permission levels, though even there it's best avoided whenever possible. Usually it's sufficient to just create the allow rules for the operations you wish to permit, and let other operations be denied by default. This is discussed in more detail below.
One case where deny is useful is in a generic rule for a class. For example, creating a rule for resource name "*" with a single ACE that says "deny:*:read" will prevent any access other than "execute" (which is the logically lowest permission level) to any resource in that class, unless a more-specific rule applies, as discussed below.
The syntax for an ACE in LDAP (in the MF schema) is:
setting:actor:action-1[,...,action-n]
For example, an ACE might be "allow:mww:control" or "deny:a*:alter". Multiple actions are useful primarily for MFDS resources, since they're really only meaningful for XAUTH requests. AUTH operates on zOS permissions levels, which are hierarchical, so for an AUTH request the effective permission of an ACE is the highest (for allow) or lowest (for deny) of the listed permissions. For example, "allow:user:execute,read,update" is equivalent to "allow:user:update" for an AUTH request.
The MLDAP ESM Module supports two kinds of wildcards:
| * | Match zero or more characters, except the period (".", aka full stop, dot) character. This exception is generally only useful in dataset names, where it indicates that the wildcard only applies to the current DSN qualifier. |
| ** | Match zero or more characters, including ".". Usually used only in dataset names, to indicate any number of qualifiers, since the period character does not usually appear in other names. |
Wildcards can appear in two places:
Match Rank
Both rules and ACEs are prioritized by match rank, which is a measure of how closely the wildcarded string matches the literal string that the ESM Module is searching for (either the resource name or the user/group name). Match rank is an integer value; the higher the value, the closer the match, and the higher the priority of the matched item.
Match rank only applies to matching patterns - patterns that do not match are skipped and never ranked.
Match rank is computed from the number of literal characters and the number of distinct wildcard sequences in the pattern. A distinct wildcard sequence is any number of adjacent wildcard characters, so "*" and "**" both count as one sequence. The rank is also normalized by the length of the name being matched to the pattern; this lets the ESM Module compare rank for user ACEs and group ACEs even if the user name and the group name are different lengths (as they usually are). The formula is:
R = 512 x L / N - W + 1
where R is the rank value, L is the number of literal characters in the pattern, N is the length of the name being matched, and W is the number of wildcard sequences. So "pat" would outrank "p**t**", which would outrank "p*", which would outrank "*a*", which would outrank "*".
When the MLDAP ESM Module gets back multiple rules for a wildcard search, it sorts them by match rank and processes them in priority order. (Processing stops when the query can be answered - see Resource Rules for details.) When the module is processing the ACEs in an ACL, it lets higher-ranked ACEs (ones that better match the user's or group's name) override lower ones.
For example, if the module is asked to authorize access to a resource named "RESOURCE", and has found rules named "R*" and "R*E", the latter rule will be processed first, because it has higher rank. If it is authorizing for user "USER" and finds ACEs "allow:U*:read" and "deny:*:read", the former would take effect because of its higher rank.
When two rules or ACEs have the same rank, their relative priority is undefined, and either may take effect; so avoid creating conflicting rules and ACEs with the same rank.
Since the MLDAP ESM Module supports wildcards in resource rule names, it's possible that several rules may apply to a single reosurce access query. The module has to communicate with the LDAP server to retrieve rules, and the server has to search for rules that match the search string sent by the module. That makes it prohibitively expensive, generally speaking, for the module to simply search for all the rules that might apply to a request.
To provide adquate performance, the MLDAP ESM Module tries to answer an access query (AUTH or XAUTH call) with as few LDAP searches as possible, using these principles:
One consequence of this approach that may not be immediately obvious is that a short prefix followed by a wildcard will take effect before a wildcard followed by a long (or indeed any) suffix. For example, when searching for "NAME", a rule named "N*" would be found and used before one named "*AME".
To define permissions for an object, let's say all datasets with names that begin with "MFIDMF.TEST.VSAM", begin by starting ADSIEdit (from the Start menu, ADAM folder, or by running "ADAM-ADSIEdit.msc" from the command line). If you do not see the MF application partition (named "CN=Micro Focus,CN=Program Data,DC=local") in the left-hand pane, follow the instructions for creating connections in the product documentation.
CICS Resource and Command Checks
Example of RACF commands compared with Active Directory definitions
Related topics:
Guides
General tasks
Active Directory and ADAM tasks
OpenLDAP tasks