Multiprotocol Concept Series Part 2: Access Tokens, User Mapping, and ID Mapping

Multiprotocol Concept Series Part 2: Access Tokens, User Mapping, and ID Mapping

Note: This topic is part of the OneFS 7.2 Documentation - Isilon Info Hub.

This article is the second in a series covering basic multiprotocol concepts in OneFS. This article expands on access tokens, user mapping, and ID mapping. It also briefly describes directory services and on-disk identity. Another article describes on-disk identity in more depth. See Multiprotocol Concept Series Part 1: Overview for a high-level introduction to multiprotocol data access concepts.

The Multiprotocol Story

The multiprotocol story starts with directory services, moves into user mapping, then ID mapping, and then to generating access tokens and assessing access permissions. The user either gains or is denied access to files and directories consistently, symmetrically, no matter how they access the Isilon cluster.

Multiprotocol data access uses the familiar Isilon feature Authentication, Identity Management, and Authorization (AIMA). The ideas at the heart of AIMA - directory services, user mapping, and ID mapping – also determine how OneFS creates an access token (unified access token) and what goes in it. The following diagram shows the relationship among the elements of AIMA and the Isilon multiprotocol story.

Directory services

Directory services provide centralized management and control of user access, authentication, and user and group membership on a network. The Isilon cluster can be joined to multiple types of directory services, including:
  • Active Directory (AD)
  • Lightweight Directory Access Protocol (LDAP) servers
  • NIS
  • File Provider
While there are also local users and groups, best practice is to use directory services to take advantage of the centralized management and control that they provide.

Directory services are also known as authentication providers.

User mapping, ID mapping, and on-disk identity

OneFS must have the user’s authoritative identity to generate a unified access token. Any single user can have different identities on different directory services. To determine the user’s authoritative identity, OneFS uses:
  • The user mapping service (user mapper). The user mapper defines how different users in different authentication providers relate to each other. The user mapper uses mapping rules that you, as system administrator, set up. For example, bob in AD is equal to bob in LDAP. These users should be considered the same user and have the same access to data. Not all user mapping is this straightforward.
  • ID mapping. All identities in Isilon are required have both an SID and a UID/GID. How these relate to each other is defined by ID mapping.
  • The on-disk identity, the authoritative identifier that is stored on disk.

Access tokens

OneFS uses the directory services, user mapper and ID mapping to generate a unified access token to represent a user’s persona to the Isilon cluster.

This will help define the on-disk identity for the user and will be reflected in the access token. If the user mappings are in place, here’s what happens when a user with accounts in multiple directory services accesses the Isilon cluster over the network:
  1. The user mapper gets the user’s access privileges and group memberships from all the directory services (the user’s identities; SID, UID and group memberships, AD SIDs and/or LDAP GIDs) and combines them into a single access token. That token represents all the user’s identities, including:
  • User name.
  • User identities (SIDs and UIDs).
  • Security identifier for Windows accounts (SIDs).
  • Primary group all the user’s Windows group memberships (SIDs).
  • All the user’s LDAP group memberships (GIDs).
  • Any additional group membership from any other providers. At this point, the token is ready to use to identify the user and to control access. This token represents the entire identity of the user to the cluster at access time.
  1. OneFS assesses the token directly against file and directory permissions.
  2. If the token has the relevant memberships and file permissions, the user gains access. Otherwise, the user is denied access.
If users have the same identity for each authentication provider (AD bob = LDAP bob), user mapping is simple and implicit. But if they do not, explicit user mapping rules must be set up.

How to examine an access token

You can look at access tokens on the cluster. For example, you can examine all the identities that represent a particular user, or verify that directory services are working correctly.

To dump the contents of an access token, use the command isi auth mapping token. The format is:
isi auth mapping token -–user=<user> --zone=<zone>
For example, the following shows a sample access token for the FOO domain administrator user. The command is:
isi auth mapping token -–user=foo\\administrator –-zone=system

(To see a larger version, click the screen capture.)

Looking at the token’s contents, you see the user’s identities (UID, SID, and on-disk identity), primary group memberships, and additional (Supplemental) identities. Access tokens also list the Isilon RBAC privileges assigned to the user (if any). For more detail about the token contents, see the next article in this series, On-disk Identity.

User mapping

User mapping is the first step of the AIMA authentication cycle and the first step in how OneFS builds a unified access token.

Suppose that you have an AD account and an LDAP account. OneFS must determine whether they are the same account and, if they are the same, make sure that you have the same access to the same file from both systems. The OneFS user mapping service maps those accounts together and makes sure that the token that is generated is equivalent regardless of whether the user is accessing Isilon using their LDAP or AD credentials, whether the user names are the same on both sides or completely different.

How the accounts are managed and created in different directory services defines the level and complexity of user mapping, as well as how you implement user mapping. If your accounts have the same user name, it is straight-forward to match them up. You can use user mapping rules to associate two accounts even if they have completely different names or refer to different people. If your accounts have different user names, you can use basic formulas or rules to create the user mapping rules.

If the user names are completely different with no commonality among them – say, jamal in AD and boketto in LDAP -- you need to create an individual mapping rule. If you have 100,000 users, that can get tedious very quickly. Some implementations use systems that sit in front of multiple directory providers and join those providers together, then present them as a single unified user. Another approach is to use RFC2307 to extend the AD schema. This approach adds UNIX attributes such as UIDs and GIDs to the AD schema so that you can query those entities directly in AD. Implementation of RFC2307 is beyond the scope of this article.

The simplest user mapping case

Here is the simplest case: the user name is the same in AD and LDAP, so you can map the AD user name to the LDAP user name. The mapping is on a per-zone basis, wildcard to wildcard. The rule looks like this:

isi zone zones view –zone=system
[info snipped]
User Mapping Rules: DOMAIN\* &= * [ ]

This rule says to map username to username: bsmith to bsmith, russ to russ, jchan to jchan, and so on.

Depending on your requirements, you can use mapping rules to perform tasks such as assigning a UNIX identity to an AD user, merging several identities into a single token, or selecting a primary group from a number of choices in AD or LDAP.

For information about creating mapping rules, see the Isilon OneFS User Mapping white paper.

ID mapping

ID mapping is how the Isilon cluster records how user identities map to each other. The Isilon ID map database is a file on the Isilon cluster that records the access zones, the UID, and the equivalent SID, the reciprocal SID to UID mapping, and some flags that tell the Isilon cluster which of those identities to use for on-disk identity.

OneFS is based on BSD UNIX. Because of this, OneFS requires each identity to have both a UID and an SID for its internal operation. Where these identities come from depends on whether you are using a single directory service or multiple directory services.

If you are only using AD, OneFS can only get real SIDs. In that case, because OneFS is based on UNIX, OneFS has to create a series of internal UIDs and GIDs to put into a user’s access token. The same is true if you only use LDAP. OneFS can get UIDs and GIDs from LDAP, but the cluster still needs equivalent SIDs so again it creates an internally generated SID to complete the token.

This is where ID mapping ties into user mapping. If user mapping is in place and the user exists both in LDAP and in AD, OneFS can use user mapping to map those users together and ID mapping to map equivalent user SIDs, UIDs and GID identities. After the users are mapped together, OneFS writes a persistent version of that ID map into the Isilon ID map database. If user mapping is set up correctly, the map is bidirectional. A UID/GID equates to a specific SID, and the SID equates to a specific UID or GID. There are two entries for every kind of identity UID or GID to the equivalent SID, and for every SID back to the equivalent UID or GID.

As a system administrator, you can dump the ID mapping database, open it, and even edit it. Be sure to back it up before you manipulate it or make changes to it.

To dump the entire ID mapping database:
isi auth mapping dump

To check the ID mapping for a specific SID or UID:
isi auth mapping dump | grep <SID/UID>

Token creation and user mapping rules

This example shows token creation for a common multiprotocol environment: an Isilon cluster joined to LDAP and to AD with user IDs that are the same in both directory services. User Bob Smith has the same login across providers: bob.

  1. Bob accesses the cluster from NFS.
  2. OneFS goes out to LDAP, looks up user bob in LDAP, and generates all the LDAP identities. All the LDAP identities go into the access token.
  3. OneFS next goes out to AD, looks up user bob in AD, comes back and appends all the additional AD credentials to the access token.
  4. OneFS now has a complete access token to represent the identities from AD and LDAP as a single identity.
Access token creation works this way for all supported protocols. For example, if a user accesses the cluster from SMB, OneFS looks up the user in LDAP, builds the LDAP half of the token, then looks up the user in AD and builds the other half of the access token.

If the user mapping is correct and the ID mapping is valid, when a user accesses a file from user accounts from two different directory services, the two tokens will be identical. When the token is evaluated against the file permissions, the permissions are the same no matter the protocol or account used to access the file. The key point is: symmetrical permissions, symmetrical access.


Here are some highlights:
  • Multiprotocol data access relies upon valid directory services, user mapping, and ID mapping.
  • The user mapping service defines how different users in different authentication providers relate to each other. The user mapper uses mapping rules that you set up.
  • ID mapping is how the user’s UID and the equivalent SID relate to each other (and how the user’s SID and equivalent UID relate to each other), and which of those identities to use for on-disk identity. The ID map is a database that you can dump to a file and examine with the command: isi auth mapping dump.
  • On-disk identity is the authoritative identifier that is stored on disk, either the users' UIDs/GIDs or SIDs.
  • OneFS combines user mapping, ID mapping, and on-disk identity to generate a unified access token for each user and assure consistent, symmetrical access to files on the Isilon cluster.


More information

Other articles in this series describe how OneFS stores file and share permissions, POSIX permissions, access control list (ACL) policies, and how to check permissions. The following common multiprotocol commands are also covered in more detail:
  • -ls –le/ls -led
  • -ls –len/ls -lend
  • -chmod/chown

Article ID: SLN319202

Last Date Modified: 02/24/2020 03:57 PM

Rate this article

Easy to understand
Was this article helpful?
0/3000 characters
Please provide ratings (1-5 stars).
Please provide ratings (1-5 stars).
Please provide ratings (1-5 stars).
Please select whether the article was helpful or not.
Comments cannot contain these special characters: <>()\
characters left.