LDAP 인증
본문
LDAP
Traefik Hub 기능
이 미들웨어는 Traefik Hub에서만 사용할 수 있어요. Traefik Hub의 고급 기능에 대해 더 알아보세요.
LDAP 인증 미들웨어는 인증을 외부 LDAP 서버에 위임해서 애플리케이션을 보호합니다.
LDAP 미들웨어는 각 요청의 Authorization 헤더에서 사용자 자격 증명을 찾아요. 자격 증명은 base64(username:password) 형식으로 인코딩돼야 합니다.
구성 예시
기본 사용법
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-ldap-auth
namespace: apps
spec:
plugin:
ldap:
url: ldap://ldap.example.org:636
baseDN: dc=example,dc=org
바인드(bind)가 필요한 기본 사용법
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-ldap-auth
namespace: apps
spec:
plugin:
ldap:
url: ldap://ldap.example.org:636
baseDN: dc=example,dc=org
bindDN: cn=binding_user,dc=example,dc=org
bindPassword: "urn:k8s:secret:my-secret:bindpassword"
검색, 바인드 & WWW-Authenticate 헤더 활성화
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-ldap-auth
namespace: apps
spec:
plugin:
ldap:
url: ldap://ldap.example.org:636
baseDN: dc=example,dc=org
searchFilter: (&(objectClass=inetOrgPerson)(gidNumber=500)(uid=%s))
forwardUsername: true
forwardUsernameHeader: Custom-Username-Header-Name
wwwAuthenticateHeader: true
wwwAuthenticateHeaderRealm: traefikee
구성 옵션
| Field | Description | Default | Required |
| url | LDAP 서버 URL. ldaps 또는 ldap 프로토콜 중 하나여야 하고 포트로 끝나야 해요(예: ldaps://ldap.example.org:636). | "" | Yes |
| startTLS | LDAP 서버와 연결을 초기화할 때 StartTLS 요청을 활성화해요. | false | No |
| certificateAuthority | 연결이 TLS를 사용하지만 인증서가 커스텀 인증 기관(Certificate Authority)에 의해 서명된 경우, LDAP 서버와 연결을 맺는 데 사용하는 PEM 인코딩 인증서. | "" | No |
| insecureSkipVerify | 그렇지 않으면 안전하지 않은 것으로 간주되는 서버 TLS 연결에서도 진행하고 운영할 수 있게 허용해요. | false | No |
| bindDN | 검색 모드로 실행할 때 LDAP 서버에 인증하기 위해 바인드할 도메인 이름. 검색 모드에서 이 값을 비워 두면 바인드가 익명으로 이뤄지는데, 이는 기대되는 동작이 아닌 경우가 대부분이에요. 바인드 모드로 실행할 때는 사용되지 않습니다. | "" | No |
| bindPassword | 검색 모드에서 LDAP 서버에 인증하기 위해 사용하는 bindDN의 비밀번호. 자세한 내용은 여기 | "" | No |
| connPool | LDAP 서버에 대한 연결 풀(성능에 미치는 영향을 최소화). | None | No |
| connPool.size | 풀이 관리하는 연결 수는 size 속성으로 커스텀할 수 있어요. | 10 | No |
| connPool.burst | 풀이 이미 가득 찼을 때 열리는 임시 연결. 연결 수가 size + burst를 초과하면 Too Many Connections 오류가 반환됩니다. | 5 | No |
| connPool.ttl | 풀링된 연결도 여전히 짧게 살아있도록 설계되어, 기본적으로 약 1분 후에 닫힙니다. 이 동작은 ttl 속성으로 수정할 수 있어요. | 60s | No |
| baseDN | 바인드 및 검색 쿼리에 사용할 기본 도메인 이름. | "" | Yes |
| attribute | 사용자를 바인드하는 데 사용하는 속성. 바인드 쿼리는 =, 패턴을 사용하는데, 여기서 사용자 이름은 요청 헤더에서 추출됩니다. | cn | Yes |
| forwardUsername | forwardUsernameHeader 옵션으로 정의된 특정 헤더에 사용자 이름을 전달해요. | "" | No |
| forwardUsernameHeader | 사용자 이름을 전달할 때 담을 헤더의 이름. forwardUsername 옵션이 false로 설정되면 사용되지 않습니다. | Username | Yes |
| forwardAuthorization | 미들웨어가 요청을 승인한 뒤 요청의 authorization 헤더를 전달할지 활성화해요. | false | Yes |
| searchFilter | 비어 있지 않으면 미들웨어는 검색 모드로 실행되며, 주어진 쿼리로 검색 결과를 필터링합니다. 필터 쿼리는 요청의 Authorization 헤더에서 제공된 사용자 이름으로 대체되는 %s 자리 표시자를 사용할 수 있어요(예: (&(objectClass=inetOrgPerson)(gidNumber=500)(uid=%s))). | "" | No |
| wwwAuthenticateHeader | 401 Unauthorized 응답에 WWW-Authenticate 헤더를 설정할 수 있게 해요. 자세한 내용은 WWW-Authenticate 헤더 문서를 참고하세요. WWW-Authenticate 헤더의 realm 지시문은 wwwAuthenticateHeaderRealm 옵션으로 커스텀할 수 있어요. | false | No |
| wwwAuthenticateHeaderRealm | WWW-Authenticate 헤더에 설정할 realm 이름. wwwAuthenticateHeader 옵션이 true로 설정되지 않으면 효과가 없어요. | "" | No |
bindPassword
bindPassword를 설정할 때, Middleware와 같은 네임스페이스의 Kubernetes secret을 다음 URN 형식으로 참조할 수 있어요:
urn:k8s:secret:[secretName]:[key]
바인드 모드 vs 검색 모드
구성에 필터가 지정되지 않으면 미들웨어는 기본 바인드 모드로 실행됩니다. 즉, 요청 헤더에 제공된 자격 증명으로 LDAP 서버에 바인드 요청을 시도한다는 뜻이에요. 바인드가 성공하면 미들웨어가 요청을 전달하고, 그렇지 않으면 401 Unauthorized 상태 코드를 반환합니다.
미들웨어 구성에 필터 쿼리가 지정되고, 참조된 Authentication Source(인증 소스)에 bindDN과 bindPassword가 있으면, 미들웨어는 검색 모드로 실행됩니다. 이 모드에서는 바인드를 시도하기 전에 주어진 필터로 LDAP 서버에 검색 쿼리를 보냅니다. 이 검색 결과가 레코드 1개만 반환하면 그 레코드로 바인드 요청을 시도하고, 그렇지 않으면 401 Unauthorized 상태 코드로 중단합니다.
Traefik OSS를 프로덕션에서 사용하시나요?
직장에서 Traefik을 사용한다면, 엔터프라이즈급 API 게이트웨이 기능이나 Traefik OSS 상용 지원을 추가하는 것을 고려해 보세요.
-
API Gateway 데모 영상 보기
-
24/7/365 OSS 지원 요청
Traefik OSS에 API 게이트웨이 기능을 추가하는 것은 빠르고 매끄러워요. 기존 구성을 교체하거나(rip and replace) 버릴 필요 없이 그대로 유지됩니다. 짧은 영상으로 직접 확인해 보세요.