RACMAP (Create, delete, list, or query a distributed identity filter)

Purpose

Use the RACMAP command to create, delete, list, and query a distributed identity filter. A distributed identity filter is a mapping association between a RACF® user ID and one or more distributed user identities. The filter consists of all or selected components of a distributed-identity user name and the distributed-identity registry name.

When you use the RACMAP command to add a distributed identity filter, RACF creates a general resource profile in the IDIDMAP class. RACF uses distributed identity filters to determine the RACF user ID of a user who attempts to access the system using a distributed identity.

RACF accepts distributed user information from authorized applications that issue the RACROUTE REQUEST=VERIFY request or the initACEE callable service (IRRSIA00), and determines the RACF user ID of the distributed user by matching the distributed-identity user name and registry name with the filters in IDIDMAP class profiles.

For information about how to use a distributed identity filter to map distributed identities to a RACF user ID, see "Distributed identity filters" in z/OS Security Server RACF Security Administrator's Guide.

Issuing options

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

As a RACF TSO command?	As a RACF operator command?	With command direction?	With automatic command direction?	From the RACF parameter library?
Yes	No	No. (See rules.)	No. (See rules.)	No
Rules: The following rules apply when issuing this command. The RACMAP command cannot be directed to a remote system using the AT or ONLYAT keyword. Updates made to the RACF database by RACMAP are eligible for propagation with automatic direction of application updates based on the RRSFDATA profile named AUTODIRECT.target-node.IDIDMAP.APPL, where target-node is the remote node to which the update is to be propagated.

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

Related commands

None.

The MAP, DELMAP and LISTMAP functions of the RACMAP command are unrelated to the MAP, DELMAP and LISTMAP functions of the RACDCERT command.

Authorization required

To issue the RACMAP command, you must have SPECIAL authority or sufficient authority to the IRR.IDIDMAP.function resource in the FACILITY class, where function is MAP, DELMAP, LISTMAP, or QUERY.

Table 1. Authority required for the RACMAP command
IRR.IDIDMAP.function
RACMAP function	Access level	Purpose
MAP	READ	Create a filter for your own RACF user ID.
MAP	UPDATE	Create a filter for another RACF user ID.
DELMAP	READ	Delete a filter for your own RACF user ID.
DELMAP	UPDATE	Delete a filter for another RACF user ID.
LISTMAP	READ	List a filter for your own RACF user ID.
LISTMAP	UPDATE	List a filter for another RACF user ID.
QUERY	READ	Query a filter to find the matching RACF user ID.

Activating your changes

To activate your changes, you must activate and RACLIST the IDIDMAP class. When you create a distributed identity filter for the first time, issue the following command.

Example:

SETROPTS CLASSACT(IDIDMAP) RACLIST(IDIDMAP)

If the IDIDMAP class is already active and RACLISTed, refresh the class to activate your changes.

Example:

SETROPTS RACLIST(IDIDMAP) REFRESH

Syntax

For the key to the symbols used in the command syntax diagrams, see Syntax of RACF commands and operands. The complete syntax of the RACMAP command is:


RACMAP
	[ ID(userid) ]
	MAP USERDIDFILTER(NAME('distributed-identity-user-name' \| '' )) REGISTRY(NAME('distributed-identity-registry-name' \| '' )) [ WITHLABEL('label-name') ]
	\| DELMAP [ (LABEL('label-name')) ]
	\| LISTMAP [ (LABEL('label-name')) ]
	QUERY USERDIDFILTER(NAME('distributed-identity-user-name')) REGISTRY(NAME('distributed-identity-registry-name'))

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

Parameters

ID(userid)

Specifies the RACF user ID mapped by the distributed identity filter. The user ID must already be defined to RACF. If you do not specify ID, the default value is the RACF user ID of the command issuer.

The ID operand is ignored when specified with the QUERY function.

MAP

Specifies the MAP function of the RACMAP command. Use the MAP function to create a distributed identity filter that maps a user's distributed identity to a RACF user ID. The MAP function creates a profile in the IDIDMAP class for each filter you create.

Rule: When you specify the MAP function, you must specify USERDIDFILTER and REGISTRY.

USERDIDFILTER(NAME('distributed-identity-user-name' | '*'))

Specifies the significant portion of the distributed-identity user name. RACF uses the user name as part of the distributed identity filter to map a distributed identity to a RACF user ID.

The USERDIDFILTER operand is required for the MAP and QUERY functions and ignored for other RACMAP functions.

Specify the user name value enclosed in single quotation marks. If a single quotation mark is intended to be part of the name, specify two single quotation marks together for each single quotation mark in the name, and enclose the entire name value in single quotation marks.

The maximum length for a user name is 246 bytes.

In general, the user name can contain blank and mixed-case characters. Any leading or trailing blank or null characters are removed from the value before it is stored in the IDIDMAP profile.

You cannot specify the name value as a hexadecimal character string.

Examples:

USERDIDFILTER(NAME('DENICE'))
USERDIDFILTER(NAME('UID=GUSKI,OU=Tools,O=IBM,C=US'))
USERDIDFILTER(NAME('Rich''s ID'))
USERDIDFILTER(NAME('Dev\+Test219'))
USERDIDFILTER(NAME('*'))

Restriction for names containing multibyte characters: Because RACF converts the name value you specify from EBCDIC to UTF-8 format prior to storing it in the RACF database, if your value contains multibyte characters, the resulting UTF-8 value might be longer than 246 bytes. If this occurs, the command fails and message IRRW213I is issued.

Format of the user name value: Specify the user name value in any of the following three formats:

As a single asterisk (X'5C') to indicate that any user name matches this filter.
As a simple character string, such as a user ID defined in a non-LDAP registry.
Typically, special characters do not appear in user names stored within a registry. However, if you need to specify a user name value that includes certain characters, they must be preceded by the backslash (\) escape character.

These characters include the plus sign (+), semicolon (;), comma (,), quotation mark ("), backslash (\), less than symbol (<), greater than symbol (>) and the equal sign (=).
As a character string that represents an X.500 distinguished name (DN).
A DN consists of one or more relative distinguished names (RDNs). Each RDN consists of an attribute type and attribute value, separated by an equal sign (=). RDNs are separated by a comma (,).

When you use mixed-case characters to specify the user name as a DN, the RACMAP command translates the attribute types to uppercase characters, and preserves the mixed-case characters of the attribute value.

The RACMAP command performs no validity checking of the X.500 names you specify.
Rules for specifying the user name as a distinguished name (DN):
- Specify the user name value in its canonical form, as it is defined within the registry, with any special characters preceded by the backslash (\) escape character. You must specify the RDNs in their correct sequence.
  For example, for users of WebSphere® Application Server applications, the canonical form of the user name must match the value returned by the WSCredential interface method called getUniqueSecurityName().
- Typically, special characters do not appear in user names stored within a registry. However, if you need to specify a user name value that includes certain characters, including LDAP special characters, they must be preceded by the backslash (\) escape character.
  These characters include the plus sign (+), semicolon (;), comma (,), quotation mark ("), backslash (\), less than symbol (<), greater than symbol (>), and the equal sign (=).
  
  Exception: Do not escape the equal sign (=), semicolon (;), or comma (,) when you specify them as delimiters of an RDN.
- Do not specify a blank character immediately preceding or following the equal sign (=) when using the equal sign as a delimiter of an attribute type or an RDN.
Normalization of the X.500 distinguished name (DN): When you specify the user name as a DN, the name is normalized before it is stored in the IDIDMAP profile. The normalized form of the DN appears in the output of the RACMAP LISTMAP command.
Normalization of the DN is done as follows:
- Any leading blank or null characters at the beginning of each RDN are removed.
- Any trailing blank or null characters at the end of each RDN are removed with the following exception.
  Exception: The last escaped blank or null character that precedes an RDN delimiter (an unescaped semicolon or comma) is not removed unless it appears in the last RDN.
- Any unescaped semicolon delimiter is replaced by a comma.
- Any lowercase characters that appear in the attribute type of each RDN are translated to uppercase characters.
Note: During normalization, a character is processed as an escaped character when it is preceded by an odd number of consecutive backslash characters.

REGISTRY(NAME('distributed-identity-registry-name' | '*'))

Specifies the registry that contains the distributed-identity user name. RACF uses the registry name as part of the distributed identity filter to map a distributed identity to a RACF user ID.

The REGISTRY operand is required for the MAP and QUERY functions and ignored for other RACMAP functions.

Specify the registry name value enclosed in single quotation marks. If a single quotation mark is intended to be part of the name, specify two single quotation marks together for each single quotation mark in the name, and enclose the entire name value in single quotation marks.

You can specify a single asterisk (X'5C') as the registry name to indicate that any distributed-identity registry name matches this filter.

The maximum length for a registry name is 255 bytes.

The registry name can contain blank and mixed-case characters. Any leading or trailing blank or null characters are removed from the value before it is stored in the IDIDMAP profile.

You cannot specify the name value as a hexadecimal character string.

Examples:

REGISTRY(NAME('ldaps://us.richradioham.com'))
REGISTRY(NAME('ldap://12.34.56.78:389'))

Restriction for names containing multibyte characters: Because RACF converts the name value you specify from EBCDIC to UTF-8 format prior to storing it in the RACF database, if your value contains multibyte characters, the resulting UTF-8 value might be longer than 255 bytes. If this occurs, the command fails and message IRRW213I is issued.

Defining registry names for LDAP servers: When the user's distributed identity is based on an LDAP registry, specify the distributed-identity-registry-name value as the URL of the LDAP server where the user is defined. The URL is defined with a listen option in the ds.conf configuration file of the LDAP server, or overridden using the -l command-line parameter when the LDAP server is started.

For information about LDAP URLs, see z/OS IBM Tivoli Directory Server Administration and Use for z/OS.

For users of WebSphere Application Server applications: The registry name must match the value returned by the WSCredential interface method called getRealmName().

The RACMAP command performs no validity checking of the registry names you specify.

WITHLABEL('label-name')

Specifies the label assigned to this distributed identity filter. If specified, the label must be unique to the RACF user ID associated with this filter.

If WITHLABEL is not specified, RACF generates a label for the filter in the form of LABELnnnnnnnn, where nnnnnnnn is the first integer value, starting at 00000001 that generates a unique label name.

Up to 32 characters can be specified for label-name. The label name can contain blank and mixed-case characters. Any leading or trailing blank characters are removed from the value before it is stored in the IDIDMAP profile.

Specify the label name value enclosed in single quotation marks. If a single quotation mark is intended to be part of the label name, specify two single quotation marks together for each single quotation mark in the name, and enclose the entire label name in single quotation marks.

The WITHLABEL operand is ignored when the RACMAP function is not MAP.

DELMAP

Specifies the DELMAP function of the RACMAP command. Use the DELMAP function to delete a distributed identity filter for the specified RACF user ID. The DELMAP function deletes the profile in the IDIDMAP class that contains the specified filter.

Rule: You must specify LABEL when the specified RACF user ID is associated with more than one filter.

LABEL('label-name'): Specifies the label name of the distributed identity filter to delete for the specified RACF user ID.
The LABEL operand is ignored when the RACMAP function is not DELMAP or LISTMAP.

Performance consideration: When you issue the RACMAP DELMAP command specifying both filter label and a user ID for which no user profile exists, RACF searches all profiles in the IDIDMAP class to locate and delete all distributed identity filters that match. This search might take an extended period of time.

LISTMAP

Specifies the LISTMAP function of the RACMAP command. Use the LISTMAP function to list information about a distributed identity filter for the specified RACF user ID.

Rule: You must specify LABEL when the specified RACF user ID is associated with more than one filter.

LABEL('label-name')

Specifies the label name of the distributed identity filter to list for the specified RACF user ID.

Tip: Omit LABEL to list all filters associated with the specified user ID.

The LABEL operand is ignored when the RACMAP function is not DELMAP or LISTMAP.

Note: When you define a distributed-identity user name as an X.500 distinguished name (DN), the DN appears in its normalized form in the LISTMAP output. For details about how a DN is normalized, see the description of the USERDIDFILTER operand of the MAP function.

If the filter cannot be listed because the IDIDMAP profile containing it is missing or incomplete, the following error text appears in the LISTMAP output:

Filter with label label-name not found.

Guideline: When this error text appears in the LISTMAP output, issue a RACMAP DELMAP command specifying this label name to remove residual filter information from the user's profile.

A missing or incomplete IDIDMAP profile might result if a previous RACMAP MAP command failed to complete due to a system failure or early termination by the issuer. If the filter or IDIDMAP profile were not created before the failure, the resulting user profile might contain residual filter information indicating that the RACF user ID is associated with a filter.

When you do not specify a RACMAP function, LISTMAP is the default function.

QUERY

Specifies the QUERY function of the RACMAP command. Use the QUERY function to find the matching RACF user ID that is associated with a distributed identity filter.

Rule: When you specify the QUERY function, you must specify USERDIDFILTER and REGISTRY.

USERDIDFILTER(NAME('distributed-identity-user-name'))

Specifies the significant portion of the distributed-identity user name. RACF uses the user name as part of the distributed identity filter to map a distributed identity to a RACF user ID.

The USERDIDFILTER operand is required for the MAP and QUERY functions and ignored for other RACMAP functions.

The maximum length for a user name is 246 bytes.

In general, the user name can contain blank and mixed-case characters. Any leading or trailing blank or null characters are removed from the value before it is stored in the IDIDMAP profile.

You cannot specify the name value as a hexadecimal character string.

Examples:

USERDIDFILTER(NAME('DENICE'))
USERDIDFILTER(NAME('UID=GUSKI,OU=Tools,O=IBM,C=US'))
USERDIDFILTER(NAME('Rich''s ID'))
USERDIDFILTER(NAME('Dev\+Test219'))

Format of the user name value: Specify the user name value in either of the following two formats:

As a simple character string, such as a user ID defined in a non-LDAP registry.
Typically, special characters do not appear in user names stored within a registry. However, if you need to specify a user name value that includes certain characters, they must be preceded by the backslash (\) escape character.

These characters include the plus sign (+), semicolon (;), comma (,), quotation mark ("), backslash (\), less than symbol (<), greater than symbol (>) and the equal sign (=).
As a character string that represents an X.500 distinguished name (DN).
A DN consists of one or more relative distinguished names (RDNs). Each RDN consists of an attribute type and attribute value, separated by an equal sign (=). RDNs are separated by a comma (,).

When you use mixed-case characters to specify the user name as a DN, the RACMAP command translates the attribute types to uppercase characters, and preserves the mixed-case characters of the attribute value.

The RACMAP command performs no validity checking of the X.500 names you specify.
Rules for specifying the user name as a distinguished name (DN):
- Specify the user name value in its canonical form, as it is defined within the registry, with any special characters preceded by the backslash (\) escape character. You must specify the RDNs in their correct sequence.
  For example, for users of WebSphere Application Server applications, the canonical form of the user name must match the value returned by the WSCredential interface method called getUniqueSecurityName().
- Typically, special characters do not appear in user names stored within a registry. However, if you need to specify a user name value that includes certain characters, including LDAP special characters, they must be preceded by the backslash (\) escape character.
  These characters include the plus sign (+), semicolon (;), comma (,), quotation mark ("), backslash (\), less than symbol (<), greater than symbol (>), and the equal sign (=).
  
  Exception: Do not escape the equal sign (=), semicolon (;), or comma (,) when you specify them as delimiters of an RDN.
- Do not specify a blank character immediately preceding or following the equal sign (=) when using the equal sign as a delimiter of an attribute type or an RDN.
Normalization of the X.500 distinguished name (DN): When you specify the user name as a DN, the name is normalized before it is used to find the matching user ID that is associated with the distributed identity filter. For details about how the DN is normalized, see the description of the USERDIDFILTER operand of the MAP function.

REGISTRY(NAME('distributed-identity-registry-name' | '*'))

Specifies the registry that contains the distributed-identity user name. RACF uses the registry name as part of the distributed identity filter to map a distributed identity to a RACF user ID.

The REGISTRY operand is required for the MAP and QUERY functions and ignored for other RACMAP functions.

The maximum length for a registry name is 255 bytes.

Examples:

REGISTRY(NAME('ldaps://us.richradioham.com'))
REGISTRY(NAME('ldap://12.34.56.78:389'))

The registry name can contain blank and mixed-case characters. Any leading or trailing blank or null characters are removed from the value before it is stored in the IDIDMAP profile.

You cannot specify the name value as a hexadecimal character string.

Restriction for names containing multibyte characters: Because RACF converts the name value you specify from EBCDIC to UTF-8 format prior to storing it in the RACF database, if your value contains multibyte characters, the resulting UTF-8 value might be longer than 255 bytes. If this occurs, the command fails and message IRRW213I is issued.

For information about LDAP URLs, see z/OS IBM Tivoli Directory Server Administration and Use for z/OS.

For users of WebSphere Application Server applications: The registry name must match the value returned by the WSCredential interface method called getRealmName().

The RACMAP command performs no validity checking of the registry names you specify.

Examples


Example 1	Operation	The security administrator wants to add a distributed identity filter that specifies the distributed user's name using all RDNs of the user's X.500 distinguished name.
	Known	The security administrator has the SPECIAL attribute.
	Command	`RACMAP ID(RLCOOK) MAP USERDIDFILTER(NAME('UID=BobC,CN=Bob Cook,OU=Accounting,O=BobsMart,C=US')) REGISTRY(NAME('ldaps://us.bobsmarturl.com')) WITHLABEL('Accounting boss')`
	Defaults	None.
	Output	None. For a listing of the output of the RACMAP LISTMAP command for this filter, see Figure 1.

Example 2	Operation	The security administrator wants to add a distributed identity filter that specifies the distributed user's name using selected RDNs of the user's X.500 distinguished name.
	Known	The security administrator has the SPECIAL attribute.
	Command	`RACMAP ID(ACCTUSER) MAP USERDIDFILTER(NAME('OU=Accounting,O=BobsMart,C=US')) REGISTRY(NAME('ldaps://us.bobsmarturl.com')) WITHLABEL('Accounting office workers')`
	Defaults	None.
	Output	None. For a listing of the output of the RACMAP LISTMAP command for this filter, see Figure 2.

Example 3	Operation	The security administrator wants to add a distributed identity filter that specifies the distributed user's name as a non-LDAP user name.
	Known	The security administrator has the SPECIAL attribute.
	Command	`RACMAP ID(DENICE) MAP USERDIDFILTER(NAME('DENICE')) REGISTRY(NAME('Registry01')) WITHLABEL('Filter for Denice from Registry01')`
	Defaults	None.
	Output	None. For a listing of the RACMAP LISTMAP command for this filter, see Figure 3.

Example 4	Operation	The security administrator wants to delete the distributed identity filter labeled `Filter for Denice from Registry01` for the RACF user ID `DENICE`.
	Known	The security administrator has the SPECIAL attribute.
	Command	`RACMAP ID(DENICE) DELMAP(LABEL('Filter for Denice from Registry01'))`
	Defaults	None.
	Output	None.

Example 5	Operation	User GUSKI wants to list a distributed identity filter and knows that RLCOOK is the RACF user ID that is associated with it.
	Known	User GUSKI has UPDATE access to the IRR.IDIDMAP.LISTMAP resource in the FACILITY class.
	Command	`RACMAP ID(RLCOOK) LISTMAP`
	Defaults	None.
	Output	See Figure 1.

Example 6	Operation	User GUSKI wants to find out the RACF user ID associated with the distributed identity filter for the user name `OU=Accounting,O=BobsMart,C=US` in registry `ldaps://us.bobsmarturl.com`.
	Known	User GUSKI has READ access to the IRR.IDIDMAP.QUERY resource in the FACILITY class.
	Command	`RACMAP QUERY USERDIDFILTER(NAME('OU=Accounting,O=BobsMart,C=US')) REGISTRY(NAME('ldaps://us.bobsmarturl.com'))`
	Defaults	None.
	Output	`RACMAP QUERY result. RACF user ID: ACCTUSER`
	Note	For a listing of the output of the RACMAP LISTMAP command for this filter, see Figure 2.

Figure 1. Example 1: Output for the RACMAP LISTMAP command

RACMAP ID(RLCOOK) LISTMAP 
Mapping information for user RLCOOK:                          
 Label: Accounting boss                                       
 Distributed Identity User Name Filter:                       
   >UID=BobC,CN=Bob Cook,OU=Accounting,O=BobsMart,C=US<       
 Registry name:                                               
   >ldaps://us.bobsmarturl.com<

Figure 2. Example 2: Output for the RACMAP LISTMAP command

RACMAP ID(ACCTUSER) LISTMAP 
Mapping information for user ACCTUSER:                        
 Label: Accounting office workers                             
 Distributed Identity User Name Filter:                       
   >OU=Accounting,O=BobsMart,C=US<                            
 Registry name:                                               
   >ldaps://us.bobsmarturl.com<

Figure 3. Example 3: Output for the RACMAP LISTMAP command

RACMAP ID(DENICE) LISTMAP 
Mapping information for user DENICE:                          
 Label: Filter for Denice from Registry01                     
 Distributed Identity User Name Filter:                       
   >DENICE<                                                   
 Registry name:                                               
   >Registry01<