How Ceph RGW checks directory users for S3 access
If you want directory users to reach S3 buckets on Ceph RGW without creating a local RGW account for each person, the LDAP method is built for that case. RGW takes an LDAP token supplied as the S3 access key, extracts the credentials from it, searches the directory for the user with a service account, and then binds as that user with the password from the token. A successful bind causes RGW to create a radosgw user for that identity. The check happens against the directory on every authentication attempt, so disabling or changing the account in the directory is what controls access.
The token is the part to plan around. It is base64-encoded JSON that carries the username and password in clear text, passed as the S3 access key with an empty secret. Anyone who captures that token captures a working directory password, so the Ceph documentation recommends ldaps:// for the LDAP endpoint and warns against reusing local RGW user names for LDAP users. Before go-live, confirm with your security team that clients will only send tokens over TLS, that RGW endpoints are HTTPS, and that the token is treated as a credential in client configuration, logs and shell history.
Active Directory is not a separate connector in this design. RGW talks to it through the same LDAP interface it uses for OpenLDAP or any other directory, so the directory side is an LDAP bind and search question. Confirm with your directory team which domain controllers offer LDAPS, which service account will perform the searches, and how that account is protected. The authentication rules themselves, including the bind account, search filters and group restriction, are covered in the sections that follow.
What the directory and the RGW cluster must provide first
Most RGW LDAP failures trace back to prerequisites rather than to the RGW settings themselves. The cards below cover the Ceph release, the directory endpoint and certificate, the bind account, the directory layout, and the RGW endpoint, and each one should be confirmed before any configuration starts.
Ceph release line
Plan the build on a release that is still maintained. Tentacle (20.2.x) and Squid (19.2.x) are the actively maintained releases on the Ceph releases page, and both receive periodic backports and security fixes. Confirm the exact point release you will run, and check its estimated end of life before you commit, since an RGW authentication design often outlives a single release.
Directory endpoint and TLS certificate
Identify the LDAP or AD domain controllers that RGW will query and the names they present. The LDAP docs recommend ldaps://, so the certificate must be issued for the exact host name in the URI and must be trusted by every RGW host. Ask who owns the certificate authority and how renewal is handled, because an expired certificate stops all S3 logins at once.
Read-only bind account
RGW uses a service account to search for the user and then binds with the user's own password. That account needs read access to the user objects and the attributes used in the search filter, and nothing more. Ask the directory team for a dedicated account with a password policy, a named owner and a rotation procedure, and avoid reusing an administrator account.
Group and OU layout
Map which users may use S3 before writing the search filter. Confirm the organizational unit or group that holds them, whether nested group membership must be resolved, and which attribute names are populated for every account. Inconsistent attributes across OUs are a common cause of users who authenticate in one site and fail in another.
Directory platform choice
Active Directory is a Windows Server role, so its licensing and lifecycle belong to your Microsoft agreement. Windows Server 2025 is licensed per core with a 16-core minimum per server, and Client Access Licenses apply to users or devices that access the server. Confirm pricing and lifecycle dates with your Microsoft contract. If the directory is Linux-hosted, OpenLDAP is an option, with 2.7.1 as the feature release and 2.6.15 as the long term support release.
RGW endpoint and DNS
Decide the public or internal host name clients will use for the RGW endpoint and confirm that it resolves consistently from every network that needs it. RGW must also reach the directory on the ports you have agreed, and any firewall between the two needs an explicit rule. Record the RGW host names, the load balancer if one exists, and which hosts can resolve the LDAP name.
Configuring RGW LDAP authentication step by step
This sequence takes RGW from an unconfigured gateway to one that authenticates approved directory users for S3 access through LDAP tokens over ldaps. Each step closes with a check you can run from an RGW host, so problems surface before users depend on the setup. Confirm option names and syntax against the documentation for your Ceph release before applying them.
Create a read-only directory service account
The directory team creates a dedicated bind account that can read user entries under the search base and nothing else. It should have no write rights and no membership in administrative groups. RGW uses this account to locate the user who presents a token before it checks that user's password. Store the account's distinguished name and password in your secrets manager, and record who owns the account. Done when an ldapsearch run with this account returns the expected test user entry and an attempt to modify an entry is refused.
Enable ldaps and trust the directory CA
Confirm that the domain controllers or OpenLDAP servers accept LDAP over TLS on the ldaps port, with a certificate issued by an authority your RGW hosts can validate. Install the CA certificate in the system trust store on every RGW host. The LDAP token is base64-encoded JSON, not encrypted, so it carries the user's password in clear text and must never travel over plain LDAP. Do not work around certificate errors by skipping verification. Done when a verified TLS handshake to the directory host completes from each RGW host.
Define the base DN and search filter
Set the search base to the smallest container that holds the users who should reach S3. Write a search filter that matches only the login attribute your directory uses, such as sAMAccountName in Active Directory or uid in OpenLDAP. A broad base such as the domain root lets more accounts match and makes later group checks harder to reason about. Run the search as the service account from an RGW host. Done when it returns exactly one entry for a known test user and no entry for a misspelled name.
Restrict authentication to an approved group
Add a group condition to the search filter so that only members of the approved group are found at lookup. Active Directory deployments commonly match on memberOf, and OpenLDAP deployments use their own group schema. Confirm the exact syntax against the RGW LDAP documentation and your directory schema, and test how nested group membership behaves in your environment. Done when the same ldapsearch returns the test user inside the group and returns nothing for a test user outside it.
Set RGW LDAP options in cluster configuration
Apply the LDAP options with ceph config set for the RGW section, or through your cephadm service specification, then restart or redeploy RGW so the daemons read them. The options cover enabling LDAP authentication for S3, the ldaps URI, the bind account and its secret, the search base and the search filter. Keep the bind secret out of plain configuration files where your platform allows. Confirm each key name in the Ceph RGW LDAP authentication documentation for your release. Done when the RGW daemons restart cleanly and their logs show no LDAP configuration errors.
Test a token-based S3 request
Build the LDAP access token by encoding a JSON object containing the test user's directory username and password as base64. Use that string as the S3 access key with an empty secret key, and send a list-buckets request to the RGW endpoint over HTTPS with an S3 client. A successful bind creates a radosgw user, so check afterward that the user appears in the RGW user listing. Done when the request returns a bucket listing and the new user is visible on the cluster.
Verify refusal for users outside the group
Repeat the request with a valid directory user who is not in the approved group, then with a correct username and a wrong password. Both attempts should be refused. Also try a local RGW user name that matches a directory user name, because the documentation warns against reusing local names for LDAP users. Check that the RGW logs do not echo the token. Done when every negative test is refused and the positive test from the previous step still succeeds.
Choosing the directory source: OpenLDAP, Active Directory or a federation layer
Many organizations already have users in Active Directory Domain Services, and RGW can authenticate against it over LDAP. Microsoft describes AD DS as the store for users and other objects, replicated to every domain controller in a domain, so the directory your RGW binds to is usually one of several replicas. Most on-premises applications reach AD through LDAP, which is the path RGW uses.
- Certificates: Use
ldaps://against a domain controller whose certificate chains to an internal CA that every RGW host trusts. Confirm the CA certificate is installed where RadosGW runs, not only on your workstations. - Service account: Create a dedicated, low-privilege bind account for RGW with read access only to the search base. Do not reuse an administrator or a personal account.
- Replication: Point RGW at a domain controller close to the gateways, and confirm which site and replica answer queries during an outage.
- Scope: Restrict searches with a filter on a group the storage team controls, so every directory user does not become an object storage user.
- Licensing and ownership: Windows Server licensing is a separate cost for any server you add, and the directory team usually owns the domain controllers.
Confirm with your Active Directory team which domain controllers RGW may query and how changes to the bind account are approved.
OpenLDAP is an open-source directory server that runs on Linux. Its slapd daemon implements LDAPv3 and supports strong authentication through SASL and certificate authentication through TLS, so it fits RGW's LDAP method directly. Because you operate it yourself, the certificate, service account and replication decisions sit with your platform team rather than a separate directory group. OpenLDAP 2.7 is the current feature release, and 2.6.15 is the long term support release, so confirm which line your organization standardizes on before building.
- Certificates: Issue the slapd server certificate from your internal CA and enable TLS, then test
ldaps://from each RGW host before configuring the gateway. - Service account: Create a read-only bind entry with an access control rule that limits it to the user subtree and the attributes RGW searches.
- Replication: slapd supports single-provider, multiple-consumer replication and multi-provider replication. Multi-provider replication avoids a single point of failure but requires more careful conflict handling.
- Backend: The MDB backend is the main database. Plan backups of the directory separately from RGW data.
- Ownership: The team must patch and monitor the directory, which is a recurring operational cost.
Confirm the OpenLDAP version, the replication topology and the backup and restore procedure with your directory owner before go-live.
Some organizations keep identities in a system that does not speak LDAP, such as a cloud identity service, a SaaS directory or a legacy store. A federation or identity broker can sit between that source and RGW, but RGW's LDAP method still needs an LDAP endpoint to bind against. Microsoft notes that Active Directory needs a federation system such as AD FS for SaaS applications, which shows that federation solves a different problem from LDAP bind. Microsoft also describes Entra ID as the cloud evolution of AD DS, and existing organizations usually sync identities to it with Entra Connect.
- Right tool check: If the broker cannot expose an LDAP interface with a searchable user tree, the RGW LDAP method does not fit and you should evaluate STS or another token design.
- Certificates: Every hop, including the broker's LDAP endpoint, needs a certificate the gateways trust.
- Service account: The bind account lives in the broker or the synced directory, so confirm who can change its password and how rotation is audited.
- Replication: Sync latency between the cloud source and the LDAP-facing copy determines how quickly disabled users lose access.
- Added components: Each broker adds a service to patch, monitor and recover.
Confirm with your identity team whether an LDAP-facing copy exists, how fast deprovisioning reaches it, and whether a federation product is needed at all.
Mapping directory attributes and groups to RGW users and buckets
This table compares what each element of an LDAP-backed RGW login controls: the identity it creates, who is allowed in, and what the user can do afterward. Read it as a chain, because a login decides only who gets a radosgw user, while bucket policy decides what that user may touch. The main takeaway is that a tight search filter and group check are necessary but do not replace bucket-level permissions.
| Element | What it decides | Where it goes wrong |
|---|---|---|
| Login attribute in the search filter | Which directory attribute matches the username the user presents, such as the account name, that is then used to find the entry | A broad filter matches more entries than intended, or an attribute that is not unique in the directory maps two people to one identity |
| Radosgw user identity | A successful bind creates a radosgw user named from the directory identity, which then owns usage and appears in RGW admin tooling | A local RGW user with the same name already exists, so the directory account can collide with it or be mistaken for it |
| Bind account and search base | The service account searches the directory for the user entry before the user's own password is tested | An over-privileged bind account can read far more of the directory than RGW needs, and its password must be protected like any service secret |
| Group membership restriction | Only users in the approved group pass the search filter, so membership is the gate for who may sign in at all | Nested or stale group membership grants access to people who should have left, so confirm how your directory expands nested groups |
| Bucket policy and ACLs | After login, these decide which buckets and actions each RGW user can use, independent of the LDAP token | Teams assume group membership limits data access and leave buckets open to every authenticated user |
| Token contents | The token carries the username and password in base64-encoded clear text and serves as the S3 access key | Tokens written to logs, scripts or shared config expose the directory password, so treat each token as a password |
Why the token must be treated as a password
With RGW LDAP authentication, the access key a user presents is effectively their directory password in encoded form. Each control below limits where that token can travel, who can see it, and how long a leaked credential stays useful.
Token equals the password
The LDAP token is base64-encoded JSON that carries the user's credentials in clear text, sent as the S3 access key with an empty secret. Base64 is an encoding, not encryption, so anyone who captures or decodes the token holds the password. Treat every copy of it, including client config files, shell history and CI variables, as sensitive material.
Use ldaps:// only
Bind requests carry the user's password, so the connection to the directory must be encrypted end to end. Configure the LDAP URI as ldaps:// and confirm that plain ldap:// is not reachable from RGW hosts. Check this on the RGW side, because a client that is set to ldaps does not protect a server-side setting that falls back to plaintext.
Validate certificates on RGW
TLS only protects the bind if RGW verifies the directory server's certificate. Install the internal CA chain on every RGW host and confirm that the trust store used by the radosgw process, not just the operating system shell, accepts the directory certificate. Test with a certificate issued by a CA the RGW hosts do not trust and confirm that binds fail.
Restrict the RGW endpoint
Any host that can reach the RGW endpoint can attempt LDAP-token logins, and any network path that carries the token is a capture point. Limit the S3 endpoint to the client networks that need it, place load balancers and proxies that terminate TLS inside managed segments, and keep the path between RGW and the directory on a dedicated network where possible.
Least-privilege bind account
The service account RGW uses to search the directory should only read the attributes and subtree needed to find users in the permitted group. Avoid domain admin or broad read rights. Ask the directory team to confirm the account cannot write, reset passwords or enumerate beyond the search base, because a compromised bind account exposes every user it can search.
Keep tokens out of logs
Proxies, load balancers, client debug output and RGW request logs can all record the Authorization header or the decoded token. Review logging levels on each tier, mask or drop authorization headers where the platform allows it, and search existing logs for the token prefix before retention rules keep them for months. Treat any log that contains a token as a credential exposure.
Rotate the service account credential
Plan a rotation schedule for the bind account password and record where it is stored in the RGW configuration. Rotation must be coordinated, because a changed password breaks every RGW instance at once. Confirm with the directory team how user password changes and account lockouts propagate, and test the rotation in a non-production realm before the production change window.
When a different access method is the safer choice
The main reason to look at another option is the token itself. RGW's LDAP scheme carries the user's credentials in a base64-encoded JSON token that is used as the S3 access key, and the credentials inside are in clear text. Base64 is an encoding, not encryption, so anyone who can read the token, from a client configuration file, a shell history, a log line or a proxy trace, can recover the user's directory password. Transport protection through ldaps:// reduces exposure on the wire, but it does not change what the token holds. Before choosing LDAP, ask your security team whether a credential-bearing access key is acceptable for your data classification, and whether they would accept client-side controls such as restricted token distribution and rotation of directory passwords as compensating measures.
RGW documents several other ways to authenticate or authorize requests. Keystone integration suits deployments that already run OpenStack identity. The gateway also documents multi-factor authentication, Open Policy Agent integration, and AWS STS, IAM and SNS APIs, which can issue temporary credentials instead of passing a directory password with every request. Whether each of these is available, and in which release, must be confirmed against the Ceph release you plan to run, because the feature set differs by version. The Ceph Dashboard's SAML 2.0 and OAuth2 single sign-on options are a separate question. They govern who signs in to the management interface, not how S3 clients authenticate to buckets, so they do not replace LDAP for object access.
Treat the choice as a decision record, not a default. Confirm the Ceph release, the authentication methods that release supports for your gateway configuration, whether temporary credentials can be issued to directory users, and how your security team classifies the data in the buckets. If LDAP remains the answer, document the bind account's scope, the token handling rules for users and the rotation process for the bind credentials. The Ceph RGW LDAP authentication documentation is the place to start the version check, and your directory team should confirm the bind account and search filters before any token is issued.
Common LDAP login failures on RGW and how to isolate them
This table pairs each common LDAP login failure on RGW with its likely cause and the check that confirms it. Work through the rows from the transport layer inward (certificates, bind, search, group filter, naming, token handling) so you isolate one layer at a time.
| Failure | Likely cause | Fix and check |
|---|---|---|
| Certificate verification error on ldaps | RGW does not trust the CA that signed the directory server certificate, or the certificate name does not match the host in the LDAP URI | Confirm the CA chain is available to the RGW hosts, test the TLS handshake from an RGW host with openssl against the same host name, then correct the URI or trust store |
| Service account bind refused | Wrong bind DN or password, a locked or expired service account, or a bind DN written in a format the directory does not accept | Bind with the same DN and password from a directory client on an RGW host, check account status and password expiry, and confirm the bind account has read access to the search base |
| Search returns no user | Base DN points at the wrong container, or the user filter does not match the attribute holding the login name | Run the same base DN and filter with an LDAP search tool, compare the returned attributes with the user name in the token, and correct the base DN or filter before changing RGW settings |
| User outside the group still authenticates | The group restriction is missing from the filter, or the filter checks a group attribute the directory does not populate for that user | Search with the group filter as the bind account for a known excluded user, confirm it returns no entry, and check nested group handling in your directory before trusting the restriction |
| Local and LDAP user name collision | An RGW user with the same name already exists locally, so the LDAP identity maps onto an account you did not intend to share | List existing radosgw users, rename or retire conflicting local accounts, and adopt a naming prefix or domain-qualified convention for directory users as the docs advise against reusing local names |
| Token rejected after a password change | The token embeds the old password in clear text, so every client holding it keeps sending the previous credential | Issue new tokens to each client after the change, revoke or remove stored copies of old tokens from scripts and config files, and check the directory account is not locked by repeated failed binds |
| Token accepted over plain LDAP | The URI uses ldap:// rather than ldaps://, so the password inside the token crosses the network without encryption | Change the URI to ldaps://, confirm the port and certificate, and capture traffic on a test host to verify no bind or token data travels unencrypted |
Questions buyers ask before connecting RGW to Active Directory
Can our team connect RGW to Active Directory without a partner?
Yes, if you have engineers comfortable with Ceph, directory services and TLS, and a lab where you can test before touching production. RGW's LDAP authentication is configured through rgw settings and a service account, and the Ceph documentation describes the token flow in Ceph RGW LDAP authentication. The difficult parts are rarely the Ceph settings themselves. They are getting the directory team to provide a suitable bind account, confirming the certificate chain for ldaps, and agreeing who may use the access tokens. Teams without a directory specialist often underestimate that coordination.
What makes the effort for an RGW and Active Directory integration larger or smaller?
Four factors drive most of the effort:
- The directory layout: how many domains, forests and organizational units hold the users who need bucket access.
- The certificate chain: whether ldaps uses a certificate from an internal CA that RGW hosts can already trust.
- The number of groups: a single allowed group is simple, while many groups with different bucket rights need a documented filter and testing for each.
- The security review: token handling, network paths to domain controllers and the change approval process in your organization.
Each factor adds testing and sign-off time, so ask a partner to price them separately.
How long does an RGW LDAP or Active Directory integration take?
The duration depends on scope, not on a fixed template. A single directory, one bind account, one group filter and a test cluster that already runs RGW is a much smaller job than multiple domains, several groups and a production change window with a formal review. No duration figure is supplied for this work, so ask any provider for a written plan that lists each phase, the dependencies on your directory and network teams, and the points where your team must approve changes before the work continues.
What must our organization provide before the work starts?
Plan to provide the following before the engagement begins:
- Directory administrator access, or a named contact who can create the bind account and read the attributes used in the search filter.
- Test accounts in each group that should and should not receive access.
- The CA certificate that signed the domain controller certificates, so RGW can verify ldaps connections.
- A change window on the Ceph cluster and on the directory side, with rollback steps agreed in advance.
Ask the provider to confirm this list in writing, since missing items are the most common cause of delay.
Does RGW connect directly to Active Directory, or do we need OpenLDAP?
RGW's LDAP authentication connects to an LDAP directory, and Active Directory exposes an LDAP interface, so the integration is not blocked by using AD directly. Microsoft notes that most on-premises apps authenticate against Active Directory with LDAP, Windows-integrated authentication or header-based authentication, as described in Compare Active Directory to Microsoft Entra ID. Confirm the exact search base, filter attributes and bind behavior against your domain before committing, because AD attribute names and group membership checks can differ from a generic LDAP schema. If the directory team prefers a separate identity source, OpenLDAP is an option, with its current releases described on the OpenLDAP website.
Does our Windows Server licensing affect whether we should use Active Directory for RGW?
Licensing is a separate decision from RGW itself, but it can change the cost of the directory side. Microsoft's Windows Server 2025 pricing page says licenses are per core with a minimum of 16 cores per server and 8 per processor, and both Standard and Datacenter need a Client Access License for each user or device that accesses the server. The same page lists a suggested price of 1,176 US dollars for Standard and 6,771 US dollars for Datacenter for 16 core licenses, and notes that prices vary by region. If you already run Active Directory domain controllers, the incremental cost for RGW may be small, but check your current agreement and Client Access License count with your Microsoft reseller before deciding.
What is the main security risk of LDAP tokens in RGW?
The main risk is that the access token carries the user's credentials. The Ceph documentation describes the token as base64-encoded JSON containing the credentials in clear text, used as the S3 access key with an empty secret. Anyone who captures or stores that token can act as the user until the password changes, so the Ceph docs recommend ldaps:// and advise against reusing local user names for LDAP users. Ask your security team to review where tokens are generated, how clients store them, and how quickly you can revoke access when someone leaves.
Official documentation for the RGW LDAP method
Before you change any RGW setting, read the Ceph Object Gateway LDAP authentication documentation in full, because it defines the token format, the bind and search flow and the configuration keys that your deployment will depend on. Treat it as the authoritative reference for the rgw_ldap_uri, rgw_ldap_binddn, rgw_ldap_searchdn, rgw_ldap_dnattr and rgw_s3_auth_use_ldap settings and for the radosgw-token workflow, and confirm each key against the release you run in production. The Ceph RGW LDAP authentication documentation is the place to start, and it is the first read for anyone signing off the design.
The Ceph documentation describes how RGW uses LDAP but does not describe your directory. Your directory team should confirm the account structure, the group membership that will gate access, and whether the service account used for searches has read-only rights. If the directory is Microsoft Active Directory, the Active Directory Domain Services overview explains the object model, replication and query behavior that affect search filters. Confirm which domain controllers RGW will reach and whether they serve LDAPS with a certificate your RGW hosts trust.
If the directory is OpenLDAP, use the OpenLDAP 2.6 Administrator's Guide introduction to check how slapd handles LDAPv3 bind authentication, TLS and access control on the directory side. Also confirm which OpenLDAP line you operate, since the project lists 2.7.1 as the feature release and 2.6.15 as the long term support release. Before go-live, test a bind with a non-privileged user, verify that a user outside the permitted group cannot obtain S3 access, and review the token handling guidance in the Ceph documentation with your security team.
How DeployOpen works on this
DeployOpen plans and builds Ceph RGW directory authentication inside your own infrastructure, so bucket access follows the groups your directory already manages. We scope the work in writing first, then build, test, document and hand over the integration, with ongoing support available as a retainer.
How we scope
- Inventory which directory you run, whether OpenLDAP or Active Directory, and which groups should receive bucket access.
- Confirm the RGW release in your cluster and the LDAP endpoints, certificates and service account your environment can provide.
- Agree the written scope, deliverables and timeline with you before any configuration work starts, as engagements are fixed-scope.
How we build
- Configure the RGW LDAP settings, bind account, search filter and group restriction to match your directory layout.
- Enable ldaps:// with certificate validation and test the connection path from every RGW host before users sign in.
- Test token handling, bucket access by group, denial for users outside scope and the separation from local RGW user names.
How we hand over
- Document the configuration, filter logic, group mapping and the clear-text token exposure with the controls you chose around it.
- Walk your operations and security teams through onboarding and offboarding steps, including how removed users lose access.
- Provide a test script and checklist your team can rerun after RGW or directory changes.
How we support
- Review the integration when you upgrade Ceph or change directory servers, certificates or group structures.
- Keep the service account, certificate renewal and filter changes under documented change control.
- Offer ongoing support, upgrades and continuous testing as a retainer, quoted from the agreed scope.
