kayx23 commented on code in PR #13794: URL: https://github.com/apache/apisix/pull/13794#discussion_r3734049766
########## docs/en/latest/plugins/ldap-auth-advanced.md: ########## @@ -0,0 +1,283 @@ +--- +title: ldap-auth-advanced +keywords: + - Apache APISIX + - API Gateway + - Plugin + - LDAP Authentication + - ldap-auth-advanced +description: The ldap-auth-advanced Plugin authenticates users against an LDAP directory using search-then-bind, so users do not need to be enumerated in APISIX. +--- + +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/ldap-auth-advanced"; /> +</head> + +## Description + +The `ldap-auth-advanced` Plugin adds LDAP authentication to a Route or a Service. Unlike [`ldap-auth`](./ldap-auth.md), which binds with a DN assembled from the Consumer configuration, this Plugin *searches* the directory for the user first, then binds as the entry it found. Users therefore do not need to be enumerated in APISIX. Review Comment: This is only true when `consumer_required` is `false`. With the default (`true`), `rewrite()` calls `find_consumer()` and rejects an authenticated LDAP user unless a Consumer with the same `user_dn` exists. Could we qualify this sentence (and the corresponding Chinese text), for example: “When `consumer_required` is disabled, users do not need to be enumerated in APISIX”? ########## docs/en/latest/plugins/ldap-auth-advanced.md: ########## @@ -0,0 +1,283 @@ +--- +title: ldap-auth-advanced +keywords: + - Apache APISIX + - API Gateway + - Plugin + - LDAP Authentication + - ldap-auth-advanced +description: The ldap-auth-advanced Plugin authenticates users against an LDAP directory using search-then-bind, so users do not need to be enumerated in APISIX. +--- + +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/ldap-auth-advanced"; /> +</head> + +## Description + +The `ldap-auth-advanced` Plugin adds LDAP authentication to a Route or a Service. Unlike [`ldap-auth`](./ldap-auth.md), which binds with a DN assembled from the Consumer configuration, this Plugin *searches* the directory for the user first, then binds as the entry it found. Users therefore do not need to be enumerated in APISIX. + +On each request the Plugin: + +1. Reads the credentials from the `Proxy-Authorization` header, falling back to `Authorization`. +2. Searches `base_dn` for the entry whose `attribute` matches the supplied username, then binds as that entry with the supplied password. +3. Attaches a matching [Consumer](../terminology/consumer.md), unless `consumer_required` is `false`. + +The credential header uses the scheme word given by `header_type`, which defaults to `ldap` rather than `basic`, so the default expects `Authorization: ldap <base64(username:password)>`. Set `header_type` to `basic` to accept ordinary [basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) instead. + +The Plugin distinguishes two failure modes, so an outage is never reported as a rejected credential: + +| Status | Cause | +|--------|-------| +| `401` | Missing, malformed, or rejected credentials; a username matching more than one entry; or `consumer_required` is `true` and no Consumer matches. Returned with a `WWW-Authenticate` header. | +| `500` | The directory is unreachable or the `bind_dn` credentials were rejected. | Review Comment: This `500` row is not exhaustive. The implementation also returns `500` for LDAP search failures and for user-bind failures other than `invalidCredentials` (for example `busy` or `unavailable`), as well as transport/TLS/protocol errors. Could we broaden this to something like “LDAP transport, TLS, protocol, or server-side failures; or rejected `bind_dn` credentials” and mirror the change in Chinese? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
