Merge pull request #294881 from b-ahibbard/ldap

Ldap

Author: Court72

articles/azure-netapp-files/TOC.yml

@@ -51,8 +51,16 @@
         href: understand-guidelines-active-directory-domain-service-site.md
       - name: Understand DNS 
         href: domain-name-system-concept.md
-      - name: Understand the use of LDAP
-        href: lightweight-directory-access-protocol.md
+      - name: Understand LDAP
+        items:
+        - name: Understand LDAP basics
+          href: lightweight-directory-access-protocol.md
+        - name: Understand name mapping using LDAP
+          href: lightweight-directory-access-protocol-name-mapping.md
+        - name: Understand the allow local NFS users with LDAP option
+          href: lightweight-directory-access-protocol-local-users.md
+        - name: Understand LDAP schemas
+          href: lightweight-directory-access-protocol-schemas.md
       - name: Understand NFS group memberships and supplemental groups
         href: network-file-system-group-memberships.md
       - name: Understand file locking

articles/azure-netapp-files/lightweight-directory-access-protocol-local-users.md

@@ -0,0 +1,47 @@
+---
+title: Understand the allow local NFS users with LDAP option with LDAP in Azure NetApp Files
+description: This article helps you understand the allow local NFS users option in the lightweight directory access protocol (LDAP).
+services: azure-netapp-files
+author: whyistheinternetbroken
+ms.service: azure-netapp-files
+ms.topic: conceptual
+ms.date: 02/18/2025
+ms.author: anfdocs
+---
+
+# Understand the allow local NFS users with LDAP option Understand name mapping using LDAP in Azure NetApp Files
+
+When a user attempts to access an Azure NetApp Files volume via NFS, the request comes in a numeric ID. By default, Azure NetApp Files supports extended group memberships for NFS users (to go beyond the standard 16 group limit). As a result, Azure NetApp files attempts to take that numeric ID and look it up in [lightweight directory access protocol (LDAP)](lightweight-directory-access-protocol.md) in an attempt to resolve the group memberships for the user rather than passing the group memberships in an RPC packet. Due to this behavior, if that numeric ID cannot be resolved to a user in LDAP, the lookup fails and access is denied. This denial occurs even if the requesting user has permission to access the volume or data structure.
+
+The Allow local NFS users with LDAP option in Active Directory connections is intended to disable those LDAP lookups for NFS requests by disabling the extended group functionality. It doesn't provide "local user creation/management" within Azure NetApp Files.
+
+When "Allow local NFS users with LDAP" option is enabled, numeric IDs are passed to Azure NetApp Files, and no LDAP lookup occurs. This creates varying behavior for different scenarios, as covered below.
+
+## NFSv3 with UNIX security style volumes
+
+Numeric IDs don't need to be translated to user names. The "Allow local NFS users with LDAP" option doesn't affect access to the volume. It can affect how user/group ownership (name translation) is displayed on the NFS client. For instance, if a numeric ID of 1001 is user1 in LDAP, but is user2 on the NFS client’s local passwd file, the client displays "user2" as the owner of the file when the numeric ID is 1001.
+
+## NFSv4.1 with UNIX security style volumes
+
+Numeric IDs don't need to be translated to user names. By default, NFSv4.1 uses name strings ([email protected]) for its authentication. However, Azure NetApp Files supports the use of numeric IDs with NFSV4.1, which means that NFSv4.1 requests arrive to the NFS server with a numeric ID. If no numeric ID to user name translation exists in local files or name services like LDAP for the Azure NetApp Files volume, then the numeric is presented to the client. If a numeric ID translates to a user name, then the name string is used. If the name string doesn't match, the client squashes the name to the anonymous user specified in the client’s idmapd.conf file. Enabling the "Allow local NFS users with LDAP" option doesn't affect NFSv4.1 access. Access falls back to standard NFSv3 behavior unless Azure NetApp Files can resolve a numeric ID to a user name in its local NFS user database. Azure NetApp Files has a set of default UNIX users that can be problematic for some clients and squash to a "nobody" user if domain ID strings don't match.
+
+* Local users include: root (0), pcuser (65534), nobody (65535).
+* Local groups include: root (0), daemon (1), pcuser (65534), nobody (65535).
+  
+Most commonly, root may show incorrectly in NFSv4.1 client mounts when the NFSv4.1 domain ID is misconfigured. For more information on the NFSv4.1 ID domain, see [Configuring NFSv4.1 ID domain for Azure NetApp Files](https://www.youtube.com/watch?v=UfaJTYWSVAY). 
+
+NFSv4.1 ACLs can be configured using either a name string or a numeric ID. If numeric IDs are used, no name translation is required. If a name string is used, then name translation would be required for proper ACL resolution. When using NFSv4.1 ACLs, enabling "Allow local NFS users with LDAP" may cause incorrect NFSv4.1 ACL behavior depending on the ACL configuration.
+
+## NFS (NFSv3 and NFSv4.1) with NTFS security style volumes in dual protocol configurations
+
+UNIX security style volumes leverage UNIX style permissions (mode bits and NFSv4.1 ACLs). For those types of volumes, NFS leverages only UNIX-style authentication leveraging a numeric ID or a name string, depending on the scenarios listed above.
+
+NTFS security style volumes, however, use NTFS style permissions. These permissions are assigned using Windows users and groups. When an NFS user attempts to access a volume with an NTFS style permission, a UNIX-to-Windows name mapping must occur to ensure proper access controls. In this scenario, the NFS numeric ID is still passed to the Azure NetApp Files NFS volume, but there is a requirement for the numeric ID to be translated to a UNIX user name so that it can then be mapped to a Windows user name for initial authentication. For instance, if numeric ID 1001 attempts to access an NFS mount with NTFS security style permissions that allow access to Windows user "user1," then 1001 would need to be resolved in LDAP to the "user1" user name to gain expected access. If no user with the numeric ID of "1001" exists in LDAP, or if LDAP is misconfigured, then the UNIX to Windows name mapping completes the attempt with [email protected]. In most cases, users with that name don't exist. As a result, authentication fails, and access is denied. Similarly, if the numeric ID 1001 resolves to the wrong user name (such as user2) then the NFS request maps to the incorrect Windows user (in this scenario, user1 has the access granted to user2).
+
+Enabling "Allow local NFS users with LDAP" disables all LDAP translations of numeric IDs to user names. This action effectively breaks access to NTFS security style volumes. As such, use of this option with NTFS security style volumes is discouraged.
+
+## Next steps 
+
+- [Understand LDAP basics](lightweight-directory-access-protocol.md)
+- [Understand name mapping using LDAP](lightweight-directory-access-protocol-name-mapping.md)
+- [Understand LDAP schemas](lightweight-directory-access-protocol-schemas.md)

articles/azure-netapp-files/lightweight-directory-access-protocol-name-mapping.md

@@ -0,0 +1,51 @@
+---
+title:  Understand name mapping using LDAP in Azure NetApp Files
+description: This article helps you understand how Azure NetApp Files uses name mapping with lightweight directory access protocol (LDAP).
+services: azure-netapp-files
+author: whyistheinternetbroken
+ms.service: azure-netapp-files
+ms.topic: conceptual
+ms.date: 02/18/2025
+ms.author: anfdocs
+---
+
+# Understand name mapping using LDAP in Azure NetApp Files
+
+Name mapping rules with [lightweight directory access protocol (LDAP)](lightweight-directory-access-protocol.md) can be broken down into two main types: *symmetric* and *asymmetric*.
+
+* *Symmetric* name mapping is implicit name mapping between UNIX and Windows users who use the same user name. For example, Windows user `CONTOSO\user1` maps to UNIX user `user1`.  
+* *Asymmetric* name mapping is name mapping between UNIX and Windows users who use **different** user names. For example, Windows user `CONTOSO\user1` maps to UNIX user `user2`.
+
+By default, Azure NetApp Files uses symmetric name mapping rules. If asymmetric name mapping rules are required, consider configuring the LDAP user objects to use them.
+
+## Custom name mapping using LDAP
+
+LDAP can be a name mapping resource, if the LDAP schema attributes on the LDAP server have been populated. For example, to map UNIX users to corresponding Windows user names that don't match one-to-one (that is, *asymmetric*), you can specify a different value for `uid` in the user object than what is configured for the Windows user name.
+
+In the following example, a user has a Windows name of `asymmetric` and needs to map to a UNIX identity of `UNIXuser`. To achieve that in Azure NetApp Files, open an instance of the [Active Directory Users and Computers MMC](/troubleshoot/windows-server/system-management-components/remote-server-administration-tools). Then, find the desired user and open the properties box. (Doing so requires [enabling the Attribute Editor](http://directoryadmin.blogspot.com/2019/02/attribute-editor-tab-missing-in-active.html)). Navigate to the Attribute Editor tab and find the UID field, then populate the UID field with the desired UNIX user name `UNIXuser` and click **Add** and **OK** to confirm.
+
+:::image type="content" source="./media/lightweight-directory-access-protocol-name-mapping/asymmetric-properties.png" alt-text="Screenshot that shows the Asymmetric Properties window and Multi-valued String Editor window." lightbox="./media/lightweight-directory-access-protocol-name-mapping/asymmetric-properties.png":::
+
+After this action is done, files written from Windows SMB shares by the Windows user `asymmetric` are owned by `UNIXuser` from the NFS side.
+
+The following example shows Windows SMB owner `asymmetric`:
+
+:::image type="content" source="./media/lightweight-directory-access-protocol-name-mapping/windows-owner-asymmetric.png" alt-text="Screenshot that shows Windows SMB owner named Asymmetric." lightbox="./media/lightweight-directory-access-protocol-name-mapping/windows-owner-asymmetric.png":::
+
+The following example shows NFS owner `UNIXuser` (mapped from Windows user `asymmetric` using LDAP):
+
+```
+root@ubuntu:~# su UNIXuser
+UNIXuser@ubuntu:/root$ cd /mnt
+UNIXuser@ubuntu:/mnt$ ls -la
+total 8
+drwxrwxrwx  2 root     root   4096 Jul  3 20:09 .
+drwxr-xr-x 21 root     root   4096 Jul  3 20:12 ..
+-rwxrwxrwx  1 UNIXuser group1   19 Jul  3 20:10 asymmetric-user-file.txt
+```
+
+## Next steps 
+
+- [Understand LDAP basics](lightweight-directory-access-protocol.md)
+- [Understand allow local NFS users with LDAP option](lightweight-directory-access-protocol-local-users.md)
+- [Understand LDAP schemas](lightweight-directory-access-protocol-schemas.md)

articles/azure-netapp-files/lightweight-directory-access-protocol-schemas.md

@@ -0,0 +1,94 @@
+---
+title: Understand LDAP schemas in Azure NetApp Files
+description: This article helps you understand schemas in the lightweight directory access protocol (LDAP).
+services: azure-netapp-files
+author: whyistheinternetbroken
+ms.service: azure-netapp-files
+ms.topic: conceptual
+ms.date: 02/18/2025
+ms.author: anfdocs
+---
+
+# Understand LDAP schemas in Azure NetApp Files
+
+[Lightweight directory access protocol (LDAP)](lightweight-directory-access-protocol.md) schemas are how LDAP servers organize and collect information. LDAP server schemas generally follow the same standards, but different LDAP server providers might have variations on how schemas are presented. 
+
+When Azure NetApp Files queries LDAP, schemas are used to help accelerate name lookups because they enable the use of specific attributes to find information about a user, such as the UID. The schema attributes must exist in the LDAP server for Azure NetApp Files to be able to find the entry. Otherwise, LDAP queries might return no data and authentication requests might fail.
+
+For example, if a UID number (such as root=0) must be queried by Azure NetApp Files, then the schema attribute RFC 2307 `uidNumber Attribute` is used. If no UID number `0` exists in LDAP in the `uidNumber` field, then the lookup request fails.
+
+The schema type currently used by Azure NetApp Files is a form of schema based on RFC 2307bis and can't be modified.
+
+[RFC 2307bis](https://tools.ietf.org/html/draft-howard-rfc2307bis-02) is an extension of RFC 2307 and adds support for `posixGroup`, which enables dynamic lookups for auxiliary groups by using the `uniqueMember` attribute, rather than by using the `memberUid` attribute in the LDAP schema. Instead of using just the name of the user, this attribute contains the full distinguished name (DN) of another object in the LDAP database. Therefore, groups can have other groups as members, which allows nesting of groups. Support for RFC 2307bis also adds support for the object class `groupOfUniqueNames`.
+
+This RFC extension fits nicely into how Microsoft Active Directory manages users and groups through the usual management tools. This is because when you add a Windows user to a group (and if that group has a valid numeric GID) using the standard Windows management methods, LDAP lookups will pull the necessary supplemental group information from the usual Windows attribute and find the numeric GIDs automatically.
+
+When Azure NetApp Files volumes need to perform LDAP lookups for NFS user identities, a series of attributes defined by an LDAP schema based on RFC-2307bis. The following table shows the attributes used by LDAP lookups, which are the defaults defined in Microsoft Active Directory when UNIX attributes are used. For proper functionality, ensure these attributes are properly populated on user and group accounts in LDAP.
+
+| UNIX attribute | LDAP Schema Value | 
+| - | - |
+| UNIX user name | uid* |
+| UNIX user numeric ID | uidNumber* |
+| UNIX group name | cn* |
+| UNIX group numeric ID | gidNumber* |
+| UNIX group membership | member** |
+| UNIX user object class | User** |
+| UNIX home directory | unixHomeDirectory |
+| UNIX display name | gecos |
+| UNIX user password | unixUserPassword |
+| UNIX login shell | LoginShell |
+| Windows account used for name mapping | sAMAccountName** |
+| UNIX group object class | Group** |
+| UNIX member UID | memberUid*** |
+| UNIX group of unique names object class| Group** |
+
+
+\* Required attribute for proper LDAP functionality
+
+\** Populated in Active Directory by default
+
+\*** Not required
+
+## Understand LDAP attribute indexing
+
+Active Directory LDAP provides an [indexing method for attributes](/windows/win32/adschema/attributes-indexed) that helps speed up lookup requests. This is particularly useful in large directory environments, where an LDAP search can potentially exceed the 10-second time-out value for lookups in Azure NetApp Files. If a search exceeds its time-out value, the LDAP lookup fails, and access won't work properly because the service cannot verify the user or group identity requesting access.
+
+By default, Microsoft Active Directory LDAP will index the following UNIX attributes used by Azure NetApp Files for LDAP lookups:
+
+- [Common Name (CN)](/windows/win32/adschema/a-cn)
+- [uidNumber](/windows/win32/adschema/a-uidnumber)
+- [gidNumber](/windows/win32/adschema/a-gidnumber)
+
+The uid attribute is not indexed by default. As a result, LDAP queries for the UID take more time than queries for indexed attributes. 
+
+For instance, in the following test of a query in an Active Directory environment with more than 20,000 users and groups, a search for a user with the indexed attribute CN took roughly 0.015 seconds, while a search for the same user with the UID attribute (which isn’t indexed by default) took closer to 0.6 seconds—40 times slower.
+
+In smaller environments, this doesn't cause issues. But in larger environments (or environments where the Active Directory environment is on premises or has high network latency), the difference can be drastic enough to cause access issues for users accessing Azure NetApp Files volumes. As a result, it's a best practice to configure the UID attribute in LDAP to be indexed by Active Directory.
+
+## Configuring the UID attribute to be indexed by Active Directory
+
+Attributes are indexed via [the `searchFlags` value](/openspecs/windows_protocols/ms-adts/7c1cdf82-1ecc-4834-827e-d26ff95fb207) for the attribute object, which is configurable via [ADSI Edit](/windows/win32/adsi/about-adsi) in the Schema naming context. Access to ADSI Edit should be approached with caution and requires at minimum [Schema Admin](/services-hub/unified/health/remediation-steps-ad/remove-all-members-from-the-schema-admins-group-unless-you-are-actively-changing-the-schema) privileges. 
+
+:::image type="content" source="./media/lightweight-directory-access-protocol-schemas/connection-settings.png" alt-text="Screenshot of connection settings menu." lightbox="./media/lightweight-directory-access-protocol-schemas/connection-settings.png":::
+
+By default, the uid attribute object’s `searchFlags` are set to 0x8 (PRESERVE_ON_DELETE). This default setting ensures that even if the object in Active Directory is deleted, the attribute value remains stored in the directory as a historical record of the user’s attribute.
+
+:::image type="content" source="./media/lightweight-directory-access-protocol-schemas/search-flag-no-index.png" alt-text="Screenshot of uid properties menu." lightbox="./media/lightweight-directory-access-protocol-schemas/search-flag-no-index.png":::
+
+In comparison, an attribute that is indexed in Active Directory for LDAP searches would have the value of 0x1 (or some combination including that value), such as the uidNumber:
+
+:::image type="content" source="./media/lightweight-directory-access-protocol-schemas/number-properties.png" alt-text="Screenshot of UiDNumber properties menu." lightbox="./media/lightweight-directory-access-protocol-schemas/number-properties.png":::
+
+Because of this, queries for uidNumber return faster than queries for uid. For consistency and performance, you can adjust the `searchFlags` value for uid to 9 by adding 0x1 along with the existing value of 0x8, which is (INDEX | PRESERVE_ON_DELETE). This addition maintains the default behavior while adding attribute indexing to the directory.
+
+:::image type="content" source="./media/lightweight-directory-access-protocol-schemas/integer-attribute-editor.png" alt-text="Screenshot of integer attribute editor." lightbox="./media/lightweight-directory-access-protocol-schemas/integer-attribute-editor.png":::
+
+:::image type="content" source="./media/lightweight-directory-access-protocol-schemas/search-flag-indexed.png" alt-text="Screenshot of uid properties menu with indexing added." lightbox="./media/lightweight-directory-access-protocol-schemas/search-flag-indexed.png":::
+
+With indexing, searches for user attributes with uid are as fast as searches for other indexed attributes.
+
+## Next steps
+
+- [Understand LDAP basics](lightweight-directory-access-protocol.md)
+- [Understand name mapping using LDAP](lightweight-directory-access-protocol-name-mapping.md)
+- [Understand allow local NFS users with LDAP option](lightweight-directory-access-protocol-local-users.md)