Managing Rule-Based Identity Mapping for Users and Groups (Task Map)

Windows systems and Solaris systems use different identity schemes to determine who is permitted to access systems and system objects. When the Solaris CIFS service is integrated into an existing Windows domain, the Solaris user IDs and group IDs must find equivalent Windows SIDs to use for authorization and file access. The Solaris CIFS service uses identity mapping software to perform these tasks.

By default, no rule-based mappings are configured. In this case, non-ephemeral Solaris UIDs and GIDs are mapped to local SIDs. Local SIDs are composed of the server's SID and an RID that is derived algorithmically from the UID or GID. Similarly, domain user and group SIDs are mapped to ephemerally, dynamically allocated UIDs and GIDs. A system administrator can also create a set of rule-based mappings to map users and groups by name. Such rule-based mapping requires that Windows uses Active Directory and that the specified users and groups must already exist.

The following table points to the tasks that you can use to manage rule-based identity mapping for the Solaris CIFS service in a Windows environment. These tasks use the idmap(1M) command to manage identity mapping.

Task	Description	For Instructions
Add a user mapping rule.	Use rules to create identity equivalents for Windows users and Solaris users based on the names in the naming services.	How to Add a User Mapping Rule
Add a group mapping rule.	Use rules to create identity equivalents for Windows groups and Solaris groups based on the names in the naming services.	How to Add a Group Mapping Rule
Import rule-based user mappings from the `usermap.cfg` file.	Use this procedure to add one or more user mappings from a `usermap.cfg` file that specifies rule-based mappings.	How to Import User Mappings From a Rule-Mapping File
List all of the mappings.	Use this procedure to review all mappings or to find particular mappings for users and groups.	How to Show Mappings
Show the mapping for a particular identity.	Use this procedure to view how a particular name or ID is mapped.	How to Show a Mapping for a Particular Identity
Show all the established mappings.	Use this procedure to view the mappings stored in the cache.	How to Show All Established Mappings
Remove a user mapping rule.	Use this procedure to remove a rule-based mapping when a user is no longer part of the naming service in your Windows domain.	How to Remove a User Mapping Rule
Remove a group mapping rule.	Use this procedure to remove a rule-based mapping when a group is no longer part of the naming service in your Windows domain.	How to Remove a Group Mapping Rule

For more information about user and group identities, see Mapping User and Group Identities.

Note - In a cluster configuration, changes made to user maps and to group maps on one server are immediately propagated to the other server.

How to Add a User Mapping Rule

The idmap command enables you to create rule-based mappings between Windows users and Solaris users. By default, the Solaris CIFS service uses ephemeral identity mapping.

Shell special characters, such as the double quote character ("), the asterisk character (*), and the backslash character (\), must be quoted when used as user names and domain names.

Become superuser, assume an equivalent role, obtain the solaris.admin.idmap.rules RBAC authorization, or use the “Idmap Service Management” RBAC profile.
Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services. To configure a role with the Primary Administrator profile, see Chapter 2, Working With the Solaris Management Console (Tasks), in System Administration Guide: Basic Administration.
Determine the user names that you want to map.
1. Determine the domain and name of the Windows user that you want to map to a Solaris user.
  The Windows user name must be specified by using one of the following formats:
  - winuser:username@domain-name
  - winuser:'domain-name\username'
2. Determine the name of the Solaris user that you want to map to the Windows user.
  The Solaris user name must be specified by using the format unixuser:username.
If username is the empty string (""), mapping is inhibited. Only directional mappings can have an empty string as their target identity. No mapping is created by the identity mapping service, and the nobody ID is used for access control. Note that a user name of "" should not be used to preclude logins by unmapped Windows users.
If username uses the wildcard (*), it matches all user names that are not matched by other mappings. Similarly, if username is the wildcard Windows name (*@*), it matches all user names in all domains that are not matched by other mappings.
Create the user mapping.
By default, identity mappings are bidirectional, which means that the Windows name is mapped to the Solaris name and the Solaris name is mapped to the Windows name. If you want the mapping to be unidirectional, specify the -d option.
If username uses the wildcard on both sides of the mapping, the user name is the same for both Windows and Solaris users. For example, if the rule is '*@example.com' == '*', the jp@example.com Windows user name would match this rule and map to the jp Solaris user name.

Caution - Be careful when creating rule-based mappings that use wildcards for the user names. Windows user names are case insensitive, while Solaris user names are case sensitive. Note that the case of Windows names that appear in idmap name rules and in idmap show commands is irrelevant.
Solaris environments typically use lowercase characters for user names, but uppercase characters are permitted. Therefore, using a wildcard to map Windows names to Solaris user names might not produce the expected results. Rule-based mapping rules that use the unixuser:* target map to the Solaris user name as follows:
- Map the canonical Windows name, which uses the found in the directory entry, to the matching Solaris user name.
- If no such Solaris user name exists, fold the case of the canonical Windows name to lower case and use it as the Solaris CIFS user name.
As a result of this differing treatment of case, user names that appear to be alike might not be recognized as matches. You must create rules to handle such pairings of strings that differ only in case. For example, to map Solaris user Kerry to Windows user kerry@example.com, you must create the following rule:
```
# idmap add winuser:'*@example.com' unixuser:'*'
# idmap add winuser:kerry@example.com unixuser:Kerry
```
- Create a bidirectional mapping between a Windows user name and a Solaris user name.
```
# idmap add winuser:username@domain-name unixuser:username
```
- Create a unidirectional mapping between a Windows user name and a Solaris user name.
```
# idmap add -d winuser:username@domain-name unixuser:username
```
- Create a unidirectional mapping between a Solaris user name and a Windows user name.
```
# idmap add -d unixuser:username winuser:username@domain-name
```

How to Add a Group Mapping Rule

The idmap command enables you to create rule-based mappings between Windows groups and Solaris groups. By default, the Solaris CIFS service uses ephemeral identity mapping.

You can also create diagonal mappings to maps between a Windows group and a Solaris user and between a Solaris group and a Windows user. These mappings are needed when Windows uses a group identity as a file owner or a user identity as a file group.

Shell special characters, such as the double quote character ("), the asterisk character (*), and the backslash character (\), must be quoted when used as group names and domain names.

Become superuser, assume an equivalent role, obtain the solaris.admin.idmap.rules RBAC authorization, or use the “Idmap Service Management” RBAC profile.
Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services. To configure a role with the Primary Administrator profile, see Chapter 2, Working With the Solaris Management Console (Tasks), in System Administration Guide: Basic Administration.
Determine the group names that you want to map.
1. Determine the domain and name of the Windows group that you want to map to a Solaris group.
  The Windows group name must be specified by using one of the following formats:
  - wingroup:group-name@domain-name
  - wingroup:'domain-name\group-name'
2. Determine the name of the Solaris user or group that you want to map to the Windows group.
  The Solaris group name must be specified by using the format unixgroup:group-name. The Solaris user name must be specified by using the format unixuser:username.
If group-name is the empty string (""), mapping is inhibited.
If group-name uses the wildcard (*), it matches all group names that are not matched by other mappings. Similarly, if group-name is the wildcard Windows name (*@*), it matches all group names in all domains that are not matched by other mappings.
Create the group mapping.
By default, identity mappings are bidirectional, which means that the Windows group name is mapped to the Solaris group name, and the Solaris group name is mapped to the Windows group name. If you want the mapping to be unidirectional, specify the -d option.
If group-name uses the wildcard on both sides of the mapping, the group name is the same for both Windows groups and Solaris groups. For example, if the rule is "*@example.com" == "*", the staff@example.com Windows group name would match this rule and map to the staff Solaris group name.

Caution - Be careful when creating rule-based mappings that use wildcards for the group names. Windows group names are case insensitive, while Solaris group names are case sensitive. Note that the case of Windows names that appear in idmap name rules and in idmap show commands is irrelevant.
Solaris environments typically use lowercase characters for group names, but uppercase characters are permitted. Therefore, using a wildcard to map Windows names to Solaris group names might not produce the expected results. Rule-based mapping rules that use the unixgroup:* target map to the Solaris group name as follows:
- Map the canonical Windows name, which uses the found in the directory entry, to the matching Solaris group name.
- If no such Solaris group name exists, fold the case of the canonical Windows name to lower case and use it as the Solaris CIFS group name.
As a result of this differing treatment of case, group names that appear to be alike might not be recognized as matches. You must create rules to handle such pairings of strings that differ only in case. For example, to map Solaris group Sales to Windows group sales@example.com, you must create the following rule:
```
# idmap add wingroup:'*@example.com' unixgroup:'*'
# idmap add wingroup:sales@example.com unixgroup:Sales
```
- Create a bidirectional mapping between a Windows group name and a Solaris group name.
```
# idmap add wingroup:group-name@domain-name unixgroup:group-name
```
- Create a unidirectional mapping between a Windows group name and a Solaris group name.
```
# idmap add -d wingroup:group-name@domain-name unixgroup:group-name
```
- Create a unidirectional mapping between a Solaris group name and a Windows group name.
```
# idmap add -d unixgroup:group-name wingroup:group-name@domain-name
```
- Create a diagonal mapping between a Windows group name and a Solaris user name.
```
# idmap add -d wingroup:group-name@domain-name unixuser:username
```
- Create a diagonal mapping between a Solaris group name and a Windows user name.
```
# idmap add -d unixgroup:group-name winuser:username@domain-name
```

How to Import User Mappings From a Rule-Mapping File

The idmap import command enables you to import a set of rule-based user mappings that are stored in a file.

The idmap supports these file formats:

The NetApp usermap.cfg rule-mapping format is as follows:
```
windows-username [direction] unix-username
```
windows-username is a Windows user name in either the domain-name\username or username@domain-name format.
unix-username is a Solaris user name.
direction is one of the following:
- == means a bidirectional mapping, which is the default.
- => or <= means a unidirectional mapping.
The IP qualifier is not supported.
The Samba smbusers rule-mapping format is as follows:
```
unixname = winname1 winname2 ...
```
The mappings are imported as unidirectional mappings from one or more Windows names to a Solaris name.
The format is based on the “username map” entry of the smb.conf man page, which is available on the samba.org web site. The use of an asterisk (*) for winname is supported. However, the @group directive and the chaining of mappings are not supported.
By default, if no mapping entries are in the smbusers file, Samba maps a winname to the equivalent unixname, if any. The following idmap command shows this mapping:
```
idmap add -d winuser:"*@*" unixuser:"*"
```

Become superuser, assume an equivalent role, obtain the solaris.admin.idmap.rules RBAC authorization, or use the “Idmap Service Management” RBAC profile.
Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services. To configure a role with the Primary Administrator profile, see Chapter 2, Working With the Solaris Management Console (Tasks), in System Administration Guide: Basic Administration.
Import the user mappings from standard input or from a file.
```
# idmap import [-F] [-f file] format
```
For example, suppose that you have a file called myusermaps that uses the usermap.cfg format to specify the following user name mappings:
```
# cat myusermaps
dana@example.com == dana
danab@example.com => dana
```
Use one of the following commands to add these mappings to the database:
- # cat myusermaps | idmap import usermap.cfg
- # idmap import -f myusermaps usermap.cfg

How to Show Mappings

The idmap list command enables you to view all of the rule-based identity mappings that you created for users and groups. You can also find particular mappings for users and groups.

List all of the mappings.

$ idmap list
add winuser:terry@example.com unixuser:terrym
add wingroup:members unixgroup:staff

To optionally list only the user mappings, type:

$ idmap list | grep user
add winuser:terry@example.com unixuser:terrym

To optionally list only the group mappings, type:

$ idmap list | grep group
add wingroup:members unixgroup:staff

How to Show a Mapping for a Particular Identity

The idmap show command enables you to view the particular name or ID for a name or ID that you specify.

Show the equivalent identity for a particular name or ID.
```
$ idmap show [-c] [-v] identity [target-type]
```
By default, the idmap show command only shows mappings that have already been established.
For example, to view the SID that is mapped to UID 50000, type:
```
$ idmap show uid:50000 sid
S-1-5-21-726303253-4128413635-1168184439
```
To view the Solaris user name for the Windows user name terry@example.com, type:
```
$ idmap show terry@example.com
terrym
```
If you specify the -c option, idmap show forces the evaluation of rule-based mapping configurations or the dynamic allocation of IDs. This command also shows mapping information when an error occurs to help diagnose mapping problems.
The -v option includes additional information about how the identity mapping was generated, which can help with troubleshooting. The following example shows that the mapping is ephemeral and was retrieved from the cache:
```
# idmap show -v sid:S-1-5-21-2949573101-2750415176-3223191819-884217
sid:S-1-5-21-2949573101-2750415176-3223191819-884217 -> uid:2175201213
Source: Cache
Method: Ephemeral
```
For name-based mappings, the idmap show -v command shows either the mapping rule or the directory distinguished name with the attribute and value that created the mapping.

How to Show All Established Mappings

The idmap dump command enables you to view all of the SID-to-UID and SID-to-GID mappings that are stored in the cache.

List all of the mappings in the cache.

By default, the idmap dump command only lists the mappings themselves. The -v option includes additional information about how the identity mapping was generated, which can help with troubleshooting.

$ idmap dump
sid:S-1-5-21-2949573101-2750415176-3223191800-2000    ==     uid:50000
sid:S-1-5-21-2949573101-2750415176-3223191800-2001    ==     uid:50001
sid:S-1-5-21-2949573101-2750415176-3223191800-2006    ==     uid:50010
sid:S-1-5-21-2949573101-2750415176-3223191900-3000    ==     uid:2147491840
sid:S-1-5-21-2949573101-2750415176-3223191900-3001    ==     gid:2147491342
sid:S-1-5-21-2949573101-2750415176-3223191700-4000    =>     uid:60001
sid:S-1-5-21-2949573101-2750415176-3223191700-4001    =>     gid:60001
sid:S-1-5-21-2949573101-2750415176-3223191800-5000    ==     gid:50000
sid:S-1-5-21-2949573101-2750415176-3223191800-5001    ==     gid:50001

To optionally list only the user mappings, type:

$ idmap dump | grep uid
sid:S-1-5-21-2949573101-2750415176-3223191800-2000    ==     uid:50000
sid:S-1-5-21-2949573101-2750415176-3223191800-2001    ==     uid:50001
sid:S-1-5-21-2949573101-2750415176-3223191800-2006    ==     uid:50010
sid:S-1-5-21-2949573101-2750415176-3223191900-3000    ==     uid:2147491840
sid:S-1-5-21-2949573101-2750415176-3223191700-4000    =>     uid:60001

To optionally list only the group mappings, type:

$ idmap dump | grep gid
sid:S-1-5-21-2949573101-2750415176-3223191900-3001    ==     gid:2147491342
sid:S-1-5-21-2949573101-2750415176-3223191700-4001    =>     gid:60001
sid:S-1-5-21-2949573101-2750415176-3223191800-5000    ==     gid:50000
sid:S-1-5-21-2949573101-2750415176-3223191800-5001    ==     gid:50001

How to Remove a User Mapping Rule

The idmap command enables you to remove a rule-based mapping that you created.

Become superuser, assume an equivalent role, obtain the solaris.admin.idmap.rules RBAC authorization, or use the “Idmap Service Management” RBAC profile.
Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services. To configure a role with the Primary Administrator profile, see Chapter 2, Working With the Solaris Management Console (Tasks), in System Administration Guide: Basic Administration.
Find the user mapping that you want to remove.
```
# idmap list
```
For example, to find all user mappings that map to the Solaris user pat, type:
```
# idmap list | grep pat
```
Remove one or more user mappings.
- Remove any rule-based mapping that involves the specified user name, username.
```
# idmap remove username
```
- Remove rule-based mappings between username1 and username2.
```
# idmap remove username1 username2
```
- Remove all rule-based mappings.
```
# idmap remove -a
```

How to Remove a Group Mapping Rule

The idmap command enables you to remove a rule-based mapping that you created.

Become superuser, assume an equivalent role, obtain the solaris.admin.idmap.rules RBAC authorization, or use the “Idmap Service Management” RBAC profile.
Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services. To configure a role with the Primary Administrator profile, see Chapter 2, Working With the Solaris Management Console (Tasks), in System Administration Guide: Basic Administration.
Find the group mapping that you want to remove.
```
# idmap list
```
For example, to find all unidirectional group mappings that map to the Solaris group staff, type:
```
# idmap list | grep staff
```
Remove one or more group mappings.
- Remove any rule-based mapping that involves the specified group name, group-name.
```
# idmap remove group-name
```
- Remove rule-based mappings between group-name1 and group-name2.
```
# idmap remove group-name1 group-name2
```
- Remove all rule-based mappings.
```
# idmap remove -a
```