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 |
- 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.
- If RACMAP commands are being propagated using automatic direction of application updates, then an equivalent IRR.IDIDMAP.PROFILE.CODEPAGE profile must be defined in the FACILITY class on all systems to which the RACMAP commands are being propagated. All of these systems must have the support for IRR.IDIDMAP.PROFILE.CODEPAGE.
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.
IRR.IDIDMAP.function | ||
---|---|---|
RACMAP function | Access level | Purpose |
MAP | READ | Create a filter for your own RACF user ID. |
UPDATE | Create a filter for another RACF user ID. | |
DELMAP | READ | Delete a filter for your own RACF user ID. |
UPDATE | Delete a filter for another RACF user ID. | |
LISTMAP | READ | List a filter for your own RACF user ID. |
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.
SETROPTS CLASSACT(IDIDMAP) RACLIST(IDIDMAP)
If the IDIDMAP class is already active and RACLISTed, refresh the class to activate your changes.
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:
|
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.
RACF converts the name that you specified from EBCDIC to UTF-8 prior to storing it in the RACF database.
If the IRR.IDIDMAP.PROFILE.CODEPAGE profile exists in the FACILITY class and contains a valid code page that is supported by RACF, then that code page is used to convert from EBCDIC to UTF-8. By default, code page IBM-1047 is used fro the conversion.
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 calledgetUniqueSecurityName()
. - 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. - Specify the user name value in its canonical form, as it is defined within the registry, with
any special characters preceded by the backslash (
- 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.
RACF converts the name that you specified from EBCDIC to UTF-8 prior to storing it in the RACF database.
If the IRR.IDIDMAP.PROFILE.CODEPAGE profile exists in the FACILITY class and contains a valid code page that is supported by RACF, then that code page is used to convert from EBCDIC to UTF-8. By default, code page IBM-1047 is used fro the conversion.
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 theds.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 calledgetRealmName()
.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.
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'))
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 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 calledgetUniqueSecurityName()
. - 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.
- Specify the user name value in its canonical form, as it is defined
within the registry, with any special characters preceded by the backslash
(
- As a simple character string, such as a user ID defined in a non-LDAP
registry.
- 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.
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.
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 theds.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 calledgetRealmName()
.The RACMAP command performs no validity checking of the registry names you specify.
Examples
|
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<
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<
RACMAP ID(DENICE) LISTMAP
Mapping information for user DENICE:
Label: Filter for Denice from Registry01
Distributed Identity User Name Filter:
>DENICE<
Registry name:
>Registry01<