Chapter 11. LDAP Authentication Setup for Red Hat Quay
The Lightweight Directory Access Protocol (LDAP) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services over an Internet Protocol (IP) network. Red Hat Quay supports using LDAP as an identity provider.
11.1. Considerations prior to enabling LDAP
11.1.1. Existing Quay deployments
Conflicts between user names can arise when you enable LDAP for an existing Quay deployment that already has users configured. Consider the scenario where a particular user, alice, was manually created in Quay prior to enabling LDAP. If the user name alice also exists in the LDAP directory, Quay will create a new user alice-1 when alice logs in for the first time using LDAP, and will map the LDAP credentials to this account. This might not be want you want, for consistency reasons, and it is recommended that you remove any potentially conflicting local account names from Quay prior to enabling LDAP.
11.1.2. Manual User Creation and LDAP authentication
When Quay is configured for LDAP, LDAP-authenticated users are automatically created in Quay’s database on first log in, if the configuration option FEATURE_USER_CREATION is set to true. If this option is set to false, the automatic user creation for LDAP users will fail and the user is not allowed to log in. In this scenario, the superuser needs to create the desired user account first. Conversely, if FEATURE_USER_CREATION is set to true, this also means that a user can still create an account from the Quay login screen, even if there is an equivalent user in LDAP.
11.2. Set Up LDAP Configuration
In the config tool, locate the Authentication section and select “LDAP” from the drop-down menu. Update LDAP configuration fields as required.
- Here is an example of the resulting entry in the config.yaml file:
AUTHENTICATION_TYPE: LDAP
11.2.1. Full LDAP URI
- The full LDAP URI, including the ldap:// or ldaps:// prefix.
- A URI beginning with ldaps:// will make use of the provided SSL certificate(s) for TLS setup.
- Here is an example of the resulting entry in the config.yaml file:
LDAP_URI: ldaps://ldap.example.org
11.2.2. Team Synchronization
- If enabled, organization administrators who are also superusers can set teams to have their membership synchronized with a backing group in LDAP.
- The resynchronization duration is the period at which a team must be re-synchronized. Must be expressed in a duration string form: 30m, 1h, 1d.
- Optionally allow non-superusers to enable and manage team syncing under organizations in which they are administrators.
- Here is an example of the resulting entries in the config.yaml file:
FEATURE_TEAM_SYNCING: true TEAM_RESYNC_STALE_TIME: 60m FEATURE_NONSUPERUSER_TEAM_SYNCING_SETUP: true
11.2.3. Base and Relative Distinguished Names
- A Distinguished Name path which forms the base path for looking up all LDAP records. Example: dc=my,dc=domain,dc=com
- Optional list of Distinguished Name path(s) which form the secondary base path(s) for looking up all user LDAP records, relative to the Base DN defined above. These path(s) will be tried if the user is not found via the primary relative DN.
- User Relative DN is relative to BaseDN. Example: ou=NYC not ou=NYC,dc=example,dc=org
- Multiple “Secondary User Relative DNs” may be entered if there are multiple Organizational Units where User objects are located at. Simply type in the Organizational Units and click on Add button to add multiple RDNs. Example: ou=Users,ou=NYC and ou=Users,ou=SFO
- The "User Relative DN" searches with subtree scope. For example, if your Organization has Organizational Units NYC and SFO under the Users OU (ou=SFO,ou=Users and ou=NYC,ou=Users), Red Hat Quay can authenticate users from both the NYC and SFO Organizational Units if the User Relative DN is set to Users (ou=Users).
- Here is an example of the resulting entries in the config.yaml file:
LDAP_BASE_DN: - dc=example - dc=com LDAP_USER_RDN: - ou=users LDAP_SECONDARY_USER_RDNS: - ou=bots - ou=external
11.2.4. Additional User Filters
- If specified, the additional filter used for all user lookup queries. Note that all Distinguished Names used in the filter must be full paths; the Base DN is not added automatically here. Must be wrapped in parens. Example: (&(someFirstField=someValue)(someOtherField=someOtherValue))
- Here is an example of the resulting entry in the config.yaml file:
LDAP_USER_FILTER: (memberof=cn=developers,ou=groups,dc=example,dc=com)
11.2.5. Administrator DN
- The Distinguished Name and password for the administrator account. This account must be able to login and view the records for all user accounts. Example: uid=admin,ou=employees,dc=my,dc=domain,dc=com
- The password will be stored in plaintext inside the config.yaml, so setting up a dedicated account or using a password hash is highly recommended.
- Here is an example of the resulting entries in the config.yaml file:
LDAP_ADMIN_DN: cn=admin,dc=example,dc=com LDAP_ADMIN_PASSWD: changeme
11.2.6. UID and Mail attributes
- The UID attribute is the name of the property field in LDAP user record to use as the username. Typically "uid".
- The Mail attribute is the name of the property field in LDAP user record that stores user e-mail address(es). Typically "mail".
- Either of these may be used during login.
- The logged in username must exist in User Relative DN.
- sAMAccountName is the UID attribute for against Microsoft Active Directory setups.
- Here is an example of the resulting entries in the config.yaml file:
LDAP_UID_ATTR: uid LDAP_EMAIL_ATTR: mail
11.2.7. Validation
Once the configuration is completed, click on “Save Configuration Changes” button to validate the configuration.
All validation must succeed before proceeding, or additional configuration may be performed by selecting the "Continue Editing" button.
11.3. Common Issues
Invalid credentials
Administrator DN or Administrator DN Password values are incorrect
Verification of superuser %USERNAME% failed: Username not found The user either does not exist in the remote authentication system OR LDAP auth is misconfigured.
Red Hat Quay can connect to the LDAP server via Username/Password specified in the Administrator DN fields however cannot find the current logged in user with the UID Attribute or Mail Attribute fields in the User Relative DN Path. Either current logged in user does not exist in User Relative DN Path, or Administrator DN user do not have rights to search/read this LDAP path.
11.4. Configure an LDAP user as superuser
Once LDAP is configured, you can log in to your Red Hat Quay instance with a valid LDAP username and password. You are prompted to confirm your Red Hat Quay username as shown in the following figure:
To attach superuser privilege to an LDAP user, modify the config.yaml file with the username. For example:
SUPER_USERS: - testadmin
Restart the Red Hat Quay container with the updated config.yaml file. The next time you log in, the user will have superuser privileges.
