Data Access in OneFS - Part 2: Introduction to OneFS Access Tokens
Fri, 01 Jul 2022 14:15:16 -0000
|Read Time: 0 minutes
Recap
In the previous blog, we introduced the OneFS file permission basics, including:
1. OneFS file permission is only in one of the following states:
- POSIX mode bits - authoritative with a synthetic ACL
- OneFS ACL - authoritative with approximate POSIX mode bits
2. No matter the OneFS file permission state, the on-disk identity for a file is always a UID, a GID, or an SID. The name of a user or group is for display only.
3. When OneFS receives a user access request, it generates an access token for the user and compares the token to the file permissions based on UID/GID/SID.
Therefore, in this blog, we will explain what UID/GID/SID is, and will explain what a OneFS access token is. Now, let’s start by looking at UID/GID/SIDs.
UID/GID and SID
In our daily life, we are usually familiar with a username or a group name, which stands for a user or a group. In a NAS system, we use UID, GID, and SID to identify a user or a group, then the NAS system will resolve the UID, GID, and SID into a related username or group name.
The UID/GID is usually used in a UNIX environment to identify users/groups with a positive integer assigned. The UID/GID is usually provided by the local operating system and LDAP server.
The SID is usually used in a Windows environment to identify users/groups. The SID is usually provided by the local operating system and Active Directory (AD). The SID is written in the format:
(SID)-(revision level)-(identifier-authority)-(subauthority1)-(subauthority2)-(etc)
for example:
S-1-5-21-1004336348-1177238915-682003330-512
For more information about SIDs, see the Microsoft article: What Are Security Identifiers?.
OneFS access token
In OneFS, information about users and groups is managed and stored in different authentication providers, including UID/GID and SID information, and user group membership information. OneFS can add multiple types of authentication provider, including:
- Active Directory (AD)
- Lightweight Directory Access Protocol (LDAP) servers
- NIS
- File provider
- Local provider
OneFS retrieves a user’s identity (UID/GID/SID) and group memberships from the above authentication providers. Assuming that we have a user named Joe, OneFS tries to resolve Joe’s UID/GID and group memberships from LDAP, NIS, file provider, and Local provider. Meanwhile, it also tries to resolve Joe’s SID and group memberships from AD, file provider, or local provider.
- If neither UID/GID nor SID can be found in any of the authentication providers, the user does not exist. User access may be denied or be mapped to the ‘nobody’ user, depending on your protocol.
- If only a UID/GID can be found or only a SID can be found, OneFS generates a fake UID or SID for the user.
It is not always the case that OneFS needs to resolve a user from username to UID/GID/SID. It is also possible that OneFS needs to resolve a user in reverse: that is, resolve a UID to its related username. This usually occurs when using NFSv3. When OneFS gets all UID/GID/SID information for a user, it will maintain the identity relationship in a local database, which records the UID <--> SID and GID <-->SID mapping, also known as the ID mapping function in OneFS.
Now, you should have an overall idea about how OneFS maintains the important UID/GID/SID information, and how to retrieve this information as needed.
Next, let’s see how OneFS can determine whether different usernames in different authentication types are actually the same real user. For example: how can we tell if the Joe in AD and the joe_f in LDAP is same guy or not? If they are the same, OneFS needs to ensure that they have the same access to the same file, even with different protocols.
That is the magic of the OneFS user mapping function. The default user mapping rule maps users together that have the same usernames in different authentication providers. For example, the Joe in AD and the Joe in LDAP will be considered the same user. You must create user mapping rules if a real user has different names in different authentication providers. The user mapping rule can have different operators, to provide more flexible management between different usernames in different authentication providers. The operators could be Append, Insert, Replace, Remove Groups, Join. See OneFS user mapping operators for more details. We just need to remember that the user mapping is just a function to determine if the user information in an authentication provider should be used when generating an access token.
Although it is easy to confuse user mapping with ID mapping, user mapping is the process of identifying users across authentication providers for the purpose of token generation. After the token is generated, the mappings of SID<-->UID are placed in the ID mapping database.
Finally, OneFS must choose an authoritative identity (that is, an On-Disk Identity) from the collected/generated UID/GID/SID for the user, which will be stored on disk and is used when the file is created or when ownership of file changes, impacting the file permissions.
In a single protocol environment, determining the On-Disk Identity is simple because Windows uses SIDs and Linux uses UIDs. However, in a multi-protocol environment, only one identity is stored, and the challenge is determining which one is stored. By default, the policy configured for on-disk identity is Native mode. Native mode is the best option for most environments. OneFS selects the real value between the SID and UID/GID. If both the SID and UID/GID are real values, OneFS selects UID/GID. Please note that this blog series is based on the default policy setting.
Now you should have an overall understanding of user mapping, ID mapping, and on-disk identity. These are the key concepts when understanding user access tokens and doing troubleshooting. Finally, let’s see what an access token contains.
You can view a user’s access token by using the command isi auth mapping token <username> in OneFS. Here is an example of Joe’s access token:
vonefs-aima-1# isi auth mapping token Joe User Name: Joe UID: 2001 SID: S-1-5-21-1137111906-3057660394-507681705-1002 On Disk: 2001 ZID: 1 Zone: System Privileges: - Primary Group Name: Market GID: 2003 SID: S-1-5-21-1137111906-3057660394-507681705-1006 On Disk: 2003 Supplemental Identities Name: Authenticated Users SID: S-1-5-11 Below
From the above output, we can see that an access token contains the following information:
- User’s username, UID, SID, and final on-disk identity
- Access zone ID and name
- OneFS RBAC privileges
- Primary group name, GID, SID, and final on-disk identity
- Supplemental group names, GID or SID.
Still, remember that we have a file created and owned by Joe in the previous blog? Here are the file permissions:
vonefs-aima-1# ls -le acl-file.txt -rwxrwxr-x + 1 Joe Market 69 May 28 01:08 acl-file.txt OWNER: user:Joe GROUP: group:Market 0: user:Joe allow file_gen_all 1: group:Market allow file_gen_read,file_gen_execute 2: user:Bob allow file_gen_all 3: everyone allow file_gen_read,file_gen_execute
The ls -le command here shows the user’s username only. And we already emphasized that the on-disk identity is always UID/GID or SID, so let’s use the ls -len command to show the on-disk identities. In the following output, we see that Joe’s on-disk identity is his UID 2001, and his GID 2003. When Joe wants to access the file, OneFS compares Joe’s access token with the file permissions below, finds that Joe’s UID is 2001 in his token, and grants him access to the file.
vonefs-aima-1# ls -len acl-file.txt -rwxrwxr-x + 1 2001 2003 69 May 28 01:08 acl-file.txt OWNER: user:2001 GROUP: group:2003 0: user:2001 allow file_gen_all 1: group:2003 allow file_gen_read,file_gen_execute 2: user:2002 allow file_gen_all 3: SID:S-1-1-0 allow file_gen_read,file_gen_execute
The above Joe is a OneFS local user from a local provider. Next, we will see what the access token looks like if a user’s SID is from AD and UID/GID is from LDAP.
Let’s assume that user John has an account named John_AD in AD, and also has an account named John_LDAP in LDAP server. This means that OneFS has to ensure that the two usernames have consistent access permissions on a file. To achieve that, we need to create a user mapping rule to join them together, so that the final access token will contain the SID information in AD and UID/GID information in LDAP. The access token for John_AD looks like this:
vonefs-aima-1# isi auth mapping token vlab\\John_AD User Name: VLAB\john_ad UID: 1000019 SID: S-1-5-21-2529895029-2434557131-462378659-1110 On Disk: S-1-5-21-2529895029-2434557131-462378659-1110 ZID: 1 Zone: System Privileges: - Primary Group Name: VLAB\domain users GID: 1000041 SID: S-1-5-21-2529895029-2434557131-462378659-513 On Disk: S-1-5-21-2529895029-2434557131-462378659-513 Supplemental Identities Name: Users GID: 1545 SID: S-1-5-32-545 Name: Authenticated Users SID: S-1-5-11 Name: John_LDAP UID: 19421 SID: S-1-22-1-19421 Name: ldap_users GID: 32084 SID: S-1-22-2-32084
Assume that a file that is owned and only accessible by John_LDAP has the file permissions shown in the following output. As the John_AD and John_LDAP is joined together with a user mapping rule, the John_LDAP identity (UID) is also in the John_AD access token, so John_AD can also access the file.
vonefs-aima-1# ls -le john_ldap.txt -rwx------ 1 John_LDAP ldap_users 19 Jun 15 07:36 john_ldap.txt OWNER: user:John_LDAP GROUP: group:ldap_users SYNTHETIC ACL 0: user:John_LDAP allow file_gen_read,file_gen_write,file_gen_execute,std_write_dac 1: group:ldap_users allow std_read_dac,std_synchronize,file_read_attr
You should now have an understanding of OneFS access tokens, and how they are used to determine a user’s authorized operation on data, through file permission checking.
In my next blog, we will see what will happen for different protocols when accessing OneFS data.
Resources
Author: Lieven Lin