SupportConsoleDevelopersStart a trialContact

Chapter 8. LDAP authentication setup for Red Hat Quay

You can configure Lightweight Directory Access Protocol (LDAP) authentication for Red Hat Quay in your config.yaml file. LDAP can create users on first login and can map selected users as restricted users or superusers.

8.1. Considerations when enabling LDAP
Copy link

Before you enable LDAP for Red Hat Quay, review how existing local usernames interact with directory accounts and how FEATURE_USER_CREATION affects first login.

Existing Red Hat Quay deployments

Conflicts between usernames can arise when you enable LDAP for an existing Red Hat Quay deployment that already has users configured. For example, one user, alice, was manually created in Red Hat Quay prior to enabling LDAP. If the username alice also exists in the LDAP directory, Red Hat Quay automatically creates a new user, alice-1, when alice logs in for the first time using LDAP. Red Hat Quay then automatically maps the LDAP credentials to the alice account. For consistency reasons, this might be erroneous for your Red Hat Quay deployment. Remove any potentially conflicting local account names from Red Hat Quay prior to enabling LDAP.

Manual user creation and LDAP authentication

When Red Hat Quay is configured for LDAP, LDAP-authenticated users are automatically created in the Red Hat Quay 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 fails, 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, a user can still create an account from the Red Hat Quay login screen, even if an equivalent user exists in LDAP.

8.2. Configuring LDAP for Red Hat Quay
Copy link

To configure LDAP authentication for Red Hat Quay, you can update your config.yaml file with the required LDAP fields and restart the registry.

Procedure

  1. Update your config.yaml file directly to include the following relevant information: 

    # ...
AUTHENTICATION_TYPE: LDAP
# ...
LDAP_ADMIN_DN: uid=<name>,ou=Users,o=<organization_id>,dc=<example_domain_component>,dc=com
LDAP_ADMIN_PASSWD: ABC123
LDAP_ALLOW_INSECURE_FALLBACK: false
LDAP_BASE_DN:
  - dc=example
  - dc=com
LDAP_EMAIL_ATTR: mail
LDAP_UID_ATTR: uid
LDAP_URI: ldap://<example_url>.com
LDAP_USER_FILTER: (memberof=cn=developers,ou=Users,dc=<domain_name>,dc=com)
LDAP_USER_RDN:
  - ou=people
LDAP_SECONDARY_USER_RDNS:
    - ou=<example_organization_unit_one>
    - ou=<example_organization_unit_two>
    - ou=<example_organization_unit_three>
    - ou=<example_organization_unit_four>
FEATURE_LDAP_CACHING: true
LDAP_CACHE_TTL: 10
# ...

    where:

    AUTHENTICATION_TYPE
    Specifies the authentication type. This field is required and must be set to LDAP.
    LDAP_ADMIN_DN
    Specifies the admin DN for LDAP authentication. This field is required.
    LDAP_ADMIN_PASSWD
    Specifies the admin password for LDAP authentication. This field is required.
    LDAP_ALLOW_INSECURE_FALLBACK
    Specifies whether to allow SSL/TLS insecure fallback for LDAP authentication. This field is required.
    LDAP_BASE_DN
    Specifies the base DN for LDAP authentication. This field is required.
    LDAP_EMAIL_ATTR
    Specifies the email attribute for LDAP authentication. This field is required.
    LDAP_UID_ATTR
    Specifies the UID attribute for LDAP authentication. This field is required.
    LDAP_URI
    Specifies the LDAP URI. This field is required.
    LDAP_USER_FILTER
    Specifies the user filter for LDAP authentication. This field is required.
    LDAP_USER_RDN
    Specifies the user RDN for LDAP authentication. This field is required.
    LDAP_SECONDARY_USER_RDNS
    Optional. Specifies secondary user relative DNs when user objects are located in multiple organizational units.
    FEATURE_LDAP_CACHING
    Optional. Specifies whether to enable in-memory caching for LDAP permission check results (superuser, restricted user). Caching reduces LDAP server load. Defaults to false.
    LDAP_CACHE_TTL
    Specifies the time-to-live, in seconds, for cached LDAP permission results. Defaults to 60.
  2. After you have added all required LDAP fields, save the changes and restart your Red Hat Quay deployment.

To mark selected LDAP users as restricted in Red Hat Quay, you can set FEATURE_RESTRICTED_USERS and LDAP_RESTRICTED_USER_FILTER in your config.yaml file and restart the registry.

The LDAP_RESTRICTED_USER_FILTER configuration field is a subset of the LDAP_USER_FILTER configuration field. When configured, this option allows Red Hat Quay administrators to configure LDAP users as restricted users when Red Hat Quay uses LDAP as its authentication provider.

Prerequisites

  • Your Red Hat Quay deployment uses LDAP as its authentication provider.
  • You have configured the LDAP_USER_FILTER field in your config.yaml file.

Procedure

  1. In your deployment’s config.yaml file, add the LDAP_RESTRICTED_USER_FILTER parameter and specify the group of restricted users, for example, members: 

    # ...
AUTHENTICATION_TYPE: LDAP
# ...
FEATURE_RESTRICTED_USERS: true
# ...
LDAP_ADMIN_DN: uid=<name>,ou=Users,o=<organization_id>,dc=<example_domain_component>,dc=com
LDAP_ADMIN_PASSWD: ABC123
LDAP_ALLOW_INSECURE_FALLBACK: false
LDAP_BASE_DN:
    - o=<organization_id>
    - dc=<example_domain_component>
    - dc=com
LDAP_EMAIL_ATTR: mail
LDAP_UID_ATTR: uid
LDAP_URI: ldap://<example_url>.com
LDAP_USER_FILTER: (memberof=cn=developers,ou=Users,o=<example_organization_unit>,dc=<example_domain_component>,dc=com)
LDAP_RESTRICTED_USER_FILTER: (<filterField>=<value>)
LDAP_USER_RDN:
    - ou=<example_organization_unit>
    - o=<organization_id>
    - dc=<example_domain_component>
    - dc=com
FEATURE_LDAP_CACHING: true
LDAP_CACHE_TTL: 10
# ...

    where:

    FEATURE_RESTRICTED_USERS
    Specifies whether restricted users are enabled. Must be set to true when configuring an LDAP restricted user.
    LDAP_RESTRICTED_USER_FILTER
    Specifies the filter that configures selected users as restricted users.
  2. Start, or restart, your Red Hat Quay deployment.

Results

  • After enabling the LDAP_RESTRICTED_USER_FILTER feature, your LDAP Red Hat Quay users are restricted from reading and writing content, and creating organizations.

To grant selected LDAP users superuser privileges in Red Hat Quay, you can set LDAP_SUPERUSER_FILTER in your config.yaml file and restart the registry.

Prerequisites

  • Your Red Hat Quay deployment uses LDAP as its authentication provider.
  • You have configured the LDAP_USER_FILTER field in your config.yaml file.

Procedure

  1. In your deployment’s config.yaml file, add the LDAP_SUPERUSER_FILTER parameter and add the group of users you want configured as superusers, for example, root: 

    # ...
AUTHENTICATION_TYPE: LDAP
# ...
LDAP_ADMIN_DN: uid=<name>,ou=Users,o=<organization_id>,dc=<example_domain_component>,dc=com
LDAP_ADMIN_PASSWD: ABC123
LDAP_ALLOW_INSECURE_FALLBACK: false
LDAP_BASE_DN:
    - o=<organization_id>
    - dc=<example_domain_component>
    - dc=com
LDAP_EMAIL_ATTR: mail
LDAP_UID_ATTR: uid
LDAP_URI: ldap://<example_url>.com
LDAP_USER_FILTER: (memberof=cn=developers,ou=Users,o=<example_organization_unit>,dc=<example_domain_component>,dc=com)
LDAP_SUPERUSER_FILTER: (<filterField>=<value>)
LDAP_USER_RDN:
    - ou=<example_organization_unit>
    - o=<organization_id>
    - dc=<example_domain_component>
    - dc=com
FEATURE_LDAP_CACHING: true
LDAP_CACHE_TTL: 10
# ...

    where:

    LDAP_SUPERUSER_FILTER
    Specifies the filter that configures selected users as superusers.
  2. Start, or restart, your Red Hat Quay deployment.

Results

  • After enabling the LDAP_SUPERUSER_FILTER feature, your LDAP Red Hat Quay users have superuser privileges. The following options are available to superusers:

    • Manage users
    • Manage organizations
    • Manage service keys
    • View the change log
    • Query the usage logs
    • Create globally visible user messages

8.5. Common LDAP configuration issues
Copy link

Invalid LDAP settings in Red Hat Quay can return errors such as invalid credentials, failed superuser verification, or an inability to find the logged-in user.

The following errors might be returned with an invalid configuration.

  • Invalid credentials. If you receive this error, the Administrator DN or Administrator DN password values are incorrect. Ensure that you are providing accurate Administrator DN and password values.

  • Verification of superuser %USERNAME% failed. This error is returned for the following reasons:

    • The username has not been found.
    • The user does not exist in the remote authentication system.
    • LDAP authorization is configured improperly.

  • Cannot find the current logged in user. When configuring LDAP for Red Hat Quay, situations can occur where the LDAP connection is established successfully using the username and password provided in the Administrator DN fields. However, if the current logged-in user cannot be found within the specified User Relative DN path using the UID Attribute or Mail Attribute fields, two potential reasons typically apply:

    • The current logged in user does not exist in the User Relative DN path.

    • The Administrator DN does not have rights to search or read the specified LDAP path.

      To fix this issue, ensure that the logged in user is included in the User Relative DN path, or provide the correct permissions to the Administrator DN account.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top