Oracle Cloud Infrastructure Documentation

Using LDAP for Authorization

Learn how to use LDAP for authorization with File Storage.

You can use Lightweight Directory Access Protocol (LDAP) as a network information service to provide authorization information to the File Storage service. Using LDAP to provide authorization information provides the following benefits:

  • Centralized management of UNIX users and groups.
  • Support for up to 256 UNIX groups. If you enable LDAP for secondary UNIX groups rather than using the group list provided within an NFS request's RPC header, you're not subject to the AUTH_SYS limitation of 16 groups.
  • LDAP infrastructure is a requirement for per user authentication when using Kerberos. LDAP isn't required for all Kerberos scenarios, such as when the export is squashing all.

Secondary Group Lookup

File Storage file systems authorize access using the NFS operation's UID/GID and list of secondary UNIX groups. By default, AUTH_SYS uses the group list provided within the NFS request's RPC header.

When LDAP authorization is enabled, File Storage uses the UNIX UID from the NFS request's RPC header to retrieve the list of secondary UNIX groups from the LDAP server for AUTH_SYS access. The existing GIDLIST in the RPC header is overwritten with the GIDLIST from the LDAP server. Retrieving secondary UNIX groups from an LDAP server allows the authorization request to use up to 256 groups.

If secondary group lookup using ID mapping is enabled, but not configured, incorrectly configured, or the LDAP service is unavailable, File Storage can't update the secondary group list used in the request. This can result in permissions errors.

NFS Request Scenarios for AUTH_SYS
LDAP for Group List Enabled? LDAP Response Export Squash Enabled? NFS Request
Any Any Yes (all)

If squashing all, proceeds with Squash UID and Squash GID set in the export's options.

No secondary group list.
Any Any Yes (root)

If squashing root, proceeds with Squash UID and Squash GID set in the export's options only if UID is 0.

No secondary group list.
No Not applicable No Proceeds with UID/GIDs from RPC header.
Yes UID match No Uses the secondary group list retrieved from the LDAP server.
Yes No UID match, or any LDAP error No Proceeds with UID/GIDs from RPC header. No secondary group list.
Important

To use LDAP for authorization, you must Enable LDAP for the mount target and at the export.

If you're using Kerberos authentication along with LDAP, behavior is slightly different. For more details, see LDAP Lookups and Anonymous Access.

Caching

File Storage uses an in-memory only, on-demand caching model to store authorization information to increase performance and reduce the load on your LDAP server.

When an NFS request is made, File Storage contacts your LDAP server for authorization information. File Storage caches the authorization information, whether positive or negative, for use in subsequent NFS operations.

You can configure how long File Storage caches this information when you configure a mount target for LDAP using the following options:

  • Cache Refresh Interval In Seconds: The amount of time that the mount target should allow an entry to persist in its cache before attempting to refresh the entry. Choose a value that balances security implications and an acceptable load on your LDAP server.
  • Cache Lifetime In Seconds: The maximum amount of time the mount target is allowed to use a cached entry. If cache entries can't be refreshed in a timely fashion because of load or failures in customer infrastructure, it is useful to use old entries until connectivity is restored. Set the value to the longest period of time that you're willing to have a stale entry in the LDAP cache, including cases of unavailability of the LDAP server for any reason.
  • Negative Cache Lifetime In Seconds: The amount of time that a mount target maintains information that a user is not found in the ID mapping configuration. If a user isn't found in the LDAP database, the mount target places an entry in the cache noting that the user doesn't exist. Choose a value that balances security implications and an acceptable load on your LDAP server.

Prerequisites

Requirements:

  • Customer-managed LDAP infrastructure, including an LDAP server that supports an RFC2307 posix schema. The LDAP servers can be based on OpenLDAP or Microsoft Active Directory. Customized configuration might be required for File Storage support of the LDAP directory.

  • A login account to the LDAP server that a File Storage mount target can use to look up RFC2307-compliant user and group information.

    • The LDAP server must have the following user attributes:
      • ObjectClass: posixAccount – This object class provides the following attributes for the user.
      • uidNumber – UNIX user ID.
      • gidNumber – UNIX group ID of the primary group of the user.
      • uid – The username for the user
    • The LDAP server must have the following group attributes:
      • ObjectClass: posixGroup – This object class provides the following attributes for the group.
      • gidNumber - UNIX group ID for the group
      • memberUid – The uid attribute of the users those are members of this group. This attribute can be added multiple times to have multiple users in the group.
    Tip

    You can test for LDAP schema support.
  • A DNS server to enable the mount target to look up hostnames, including the LDAP server.
This image shows the customer-managed and OCI-managed infrastructure needed for LDAP authorization.
  1. Communication with DNS service over TCP/UDP port 53.
  2. Communication with customer-managed LDAP service over the TCP port configured in the outbound connector. The default value is TCP port 636.
  3. Data encrypted at rest in File Storage.

LDAP Infrastructure

File Storage requires an outbound connector so that mount targets can communicate with an LDAP server on its LDAPS port. The outbound connector requires that you provide the fully qualified domain name (FQDN) of LDAP server, a bind username and password to LDAP server, and the search base for users and groups.

To allow File Storage to reach the LDAP server, ensure the following:

  • The LDAP server's firewall must allow inbound traffic from the File Storage mount target using TCP 636 (default).
  • Any security lists and NSGs in use must allow the mount target and LDAP server traffic.
  • DNS is configured for the mount target and clients to resolve hostname. DNS configuration options include:
    • Using OCI DNS with default resolution and hostnames in your VCN - This option doesn't offer the flexibility of custom DNS names. Hostnames end with oraclevcn.com with subdomains for VCN and subnet. See DNS in Your Virtual Cloud Network for more information.
    • Using OCI Private DNS with private zones - DNS zones for a custom domain are hosted in OCI DNS. With this option, there's no need to manage your own DNS server, because OCI fully manages DNS. You must manage the zones and records. See Private DNS for more information.
    • Using a customer-managed DNS server - When you create a VCN, don't select Use DNS hostnames in this VCN. Instead, configure the VCN to use your own DNS server using one of the following methods:
      1. Configure DHCP Options in the subnet to use a customer-managed DNS server.
      2. Use the VCN resolver with a forwarding endpoint and a forwarding rule so that DNS queries in the VCN are forwarded to a customer-managed DNS server.

File Storage doesn't support SSLv2, SSLv3, TLSv1, or TLSv1.1 for LDAPS authorization. File Storage supports the following OpenSSL cipher suites for LDAPS authorization:

  • DHE-DSS-AES128-GCM-SHA256
  • DHE-DSS-AES256-GCM-SHA384
  • DHE-RSA-AES128-GCM-SHA256
  • DHE-RSA-AES256-GCM-SHA384
  • ECDHE-ECDSA-AES128-GCM-SHA256
  • ECDHE-ECDSA-AES256-GCM-SHA384
  • ECDHE-RSA-AES128-GCM-SHA256
  • ECDHE-RSA-AES256-GCM-SHA384
  • TLS_AES_128_CCM_SHA256
  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384

Testing for LDAP Schema Support

You can use the following example queries to ensure that File Storage can look up RFC2307-compliant user and group information from an LDAP server with a supported configuration.

ldapsearch -b <user_searchbase> -H ldaps://<ldaps_server_fqdn>:<ldaps_port> -D <bind_DN> -W -s sub '(&(objectClass=posixAccount)(uid=<username>))' uidNumber gidNumber
Example Query Output
$ ldapsearch -b 'ou=Users,dc=nfs_kerberos,dc=fss_test,dc=com' -H 'ldaps://example.com:636' -D 'cn=admin,dc=fss_test,dc=com' -W -s sub '(&(objectClass=posixAccount)(uid=root))' uidNumber gidNumber
Enter LDAP Password:
# extended LDIF
#
# LDAPv3
# base <ou=Users,dc=nfs_kerberos,dc=fss_test,dc=com> with scope subtree
# filter: (&(objectClass=posixAccount)(uid=root))
# requesting: uidNumber gidNumber
#

# root, Users, nfs_kerberos.fss_test.com
dn: uid=root,ou=Users,dc=nfs_kerberos,dc=fss_test,dc=com
gidNumber: 0
uidNumber: 0

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1
ldapsearch -b <user_searchbase> -H ldaps://<ldaps_server_fqdn>:<ldaps_port> -D <bind_DN> -W -s sub '(&(objectClass=posixAccount)(uidNumber=<user_uid>))' uid gidNumber
Example Query Output
$ ldapsearch -b 'ou=Users,dc=nfs_kerberos,dc=fss_test,dc=com' -H 'ldaps://example.com:636' -D 'cn=admin,dc=fss_test,dc=com' -W -s sub '(&(objectClass=posixAccount)(uidNumber=0))' uid gidNumber
Enter LDAP Password:
# extended LDIF
#
# LDAPv3
# base <ou=Users,dc=nfs_kerberos,dc=fss_test,dc=com> with scope subtree
# filter: (&(objectClass=posixAccount)(uidNumber=0))
# requesting: uid gidNumber
#
# root, Users, nfs_kerberos.fss_test.com
dn: uid=root,ou=Users,dc=nfs_kerberos,dc=fss_test,dc=com
gidNumber: 0
uid: root
# search result
search: 2
result: 0 Success
# numResponses: 2
# numEntries: 1
ldapsearch -b <group_searchbase> -H ldaps://<ldaps_server_fqdn>:<ldaps_port> -D <bind_DN> -W -s sub '(&(objectClass=posixGroup)(memberuid=<username>))' gidNumber
Example Query Output
$ ldapsearch -b 'ou=Groups,dc=nfs_kerberos,dc=fss_test,dc=com' -H 'ldaps://example.com:636' -D 'cn=admin,dc=fss_test,dc=com' -W -s sub '(&(objectClass=posixGroup)(memberuid=root))' gidNumber
Enter LDAP Password:
# extended LDIF
#
# LDAPv3
# base <ou=Groups,dc=nfs_kerberos,dc=fss_test,dc=com> with scope subtree
# filter: (&(objectClass=posixGroup)(memberuid=root))
# requesting: gidNumber
#
# root, Groups, nfs_kerberos.fss_test.com
dn: cn=root,ou=Groups,dc=nfs_kerberos,dc=fss_test,dc=com
gidNumber: 0
# search result
search: 2
result: 0 Success
# numResponses: 2
# numEntries: 1
Tip

You can create alarms based off of File System Metrics that help you quickly discover and diagnose LDAP connectivity issues.

Monitoring and Alarms

Becoming aware of a problem quickly is important when using LDAP. If LDAP infrastructure isn't functioning correctly, NFS clients could lose access to File Storage file systems made available through its exports. To discover such problems, we recommend setting alarms on mount target metrics. Alarms can alert you to infrastructure problems within minutes.

Alarms built off of LDAP connection errors and LDAP request errors detect connectivity problems between mount targets, outbound connectors, and customer-managed LDAP infrastructure.

The following example query can be used to create an alarm for LDAP connectivity:

LdapConnectionErrors[1m]{resourceType = "outboundconnector", mtResourceName = "<mount_target_name>", errorType != "success"}.max() >= 1

For more information about monitoring metrics and using alarms, see Overview of Monitoring. For information about notifications for alarms, see Overview of Notifications.

Required IAM Policy

File Storage needs to access LDAP server password Vault secrets. Both the user configuring the mount target and the mount target itself need read access.

Important

These policies must be created before you can configure mount targets to use LDAP for authorization.

Policy to Manage Vault Secrets

Grant the user or group creating the Vault secret permissions. For more information, see Managing Vault Secrets.

Policy to Enable Mount Target Configuration

Grant the user or group configuring LDAP on a mount target permissions using a policy such as the following:

allow <user|group> to read secret-family in compartment <Compartment_ID> where any { target.secret.id = <LDAP_Password_Secret_ID> }

This allows the user to issue File Storage commands that read the Vault secrets and display parts of the secret for validation during configuration.

Policy to Allow a Mount Target to Retrieve Secrets

The File Storage service requires the ability to read the secrets. File Storage uses resource principals to grant a specific set of mount targets access to the Vault secret. This is a two step process, first the mount targets which need access must be put into a dynamic group, and then the dynamic group is granted access to read the secrets.

  1. Create a dynamic group for the mount targets with a policy such as the following:

    ALL { resource.type='mounttarget', resource.compartment.id = '<mount_target_compartment_id>' }
    Note

    If you have more than one rule in the dynamic group, ensure that you use Match any rules defined below option.

  2. Create an IAM policy that gives the dynamic group of mount targets read access to Vault secrets:

     allow dynamic-group <dynamic_group_name> to read secret-family in compartment <secret_compartment_name>