BobLDAP 커스텀 리소스 및 bobctl add-ldap 명령을 사용하여 IBM Bob 온프레미스에 대한 LDAP 또는 Active Directory 페더레이션을 구성합니다.

Bob 온프레미스는 bobctl 유틸리티를 통해 LDAP 또는 Active Directory 환경을 Keycloak과 통합하며, 이 유틸리티는 디렉터리를 Keycloak 사용자 페더레이션 공급자로 구성합니다. 이 통합은 일반적으로 설치 중에 설정되지만 진행 중인 사용자 관리 활동의 일환으로 배포 후에도 구성, 업데이트 또는 유지 관리할 수 있습니다.

시작하기 전에

LDAP 페더레이션을 구성하기 전에 다음 요구 사항이 충족되어 있는지 확인합니다:

OpenShift Container Platform(OCP) 클러스터가 적절한 포트에서 LDAP 서버에 대한 네트워크 연결을 보유하고 있습니다:

ldap://의 경우 389
ldaps://의 경우 636

디렉터리에 대한 읽기 접근 권한을 가진 서비스 계정(바인드 DN)을 사용할 수 있거나 LDAP 서버가 익명 바인드를 허용하도록 구성되어 있습니다.

개인 또는 내부 서명 인증 기관(CA)이 있는 ldaps://를 사용하는 경우 PEM 형식의 LDAP 서버 CA 인증서를 가져옵니다.

bobctl 명령줄 유틸리티가 설치되어 있고 oc가 구성되어 대상 클러스터에 대해 인증되어 있습니다.

구성 파일 참조

LDAP 공급자를 등록하기 전에 제공된 템플릿에서 LDAP 구성 파일을 생성합니다.

cp config-ldap-template.yaml my-ldap.yaml

구성 파일에는 Bob이 LDAP 디렉터리에 연결하고, 인증하고, 사용자를 동기화하는 방법을 정의하는 필수 및 선택적 매개변수가 포함되어 있습니다.

필수 필드

필드	설명
`name`	LDAP 공급자의 고유하고 설명적인 식별자. 구성된 각 공급자는 고유한 이름을 가져야 합니다.
`vendor`	통합할 LDAP 디렉터리 유형을 지정합니다. 지원 값: `other`(OpenLDAP 및 LDAPv3 호환), `ad`(Microsoft Active Directory), `rhds`(Red Hat Directory Server), `tivoli`(IBM Security Directory Server), `edirectory`(NetIQ eDirectory).
`connectionUrl`	프로토콜(`ldap://` 또는 `ldaps://`), 호스트명, 포트 번호를 포함하는 LDAP 서버의 전체 URL.
`usersDn`	사용자 계정이 저장되고 사용자 항목이 검색 및 가져오기되는 디렉터리 위치.
`usernameLDAPAttribute`	사용자가 인증할 때 사용자 이름으로 제공하는 디렉터리 속성.
`rdnLDAPAttribute`	디렉터리 구조 내에서 항목을 식별하는 데 사용되는 디렉터리 속성. 대부분의 구성에서 `usernameLDAPAttribute`와 동일합니다.
`uuidLDAPAttribute`	각 사용자 계정을 영구적으로 식별하는 데 사용되는 고유하고 안정적이며 변경되지 않는 디렉터리 속성.
`userObjectClasses`	어떤 디렉터리 항목이 사용자 계정으로 인식되고 처리되는지 정의하는 LDAP 개체 클래스의 쉼표로 구분된 목록.
`domains`	디렉터리와 연결된 하나 이상의 이메일 도메인. 인증 중에 구성된 도메인과 일치하는 이메일 주소를 가진 사용자는 자격 증명 유효성 검사를 위해 이 LDAP 공급자로 자동 라우팅됩니다.

중요:

domains 매개변수는 온프레미스 배포에서 도메인 기반 라우팅을 구성하는 데 지원되는 유일한 방법입니다. Bob 관리 사용자 인터페이스를 통해 도메인을 구성하지 마세요. 이는 지원되지 않으며 인증 오류를 일으킬 수 있습니다.

선택적 필드

필드	설명
`adminEmails`	관리자 권한을 부여할 사용자의 이메일 주소. Bob이 이 사용자들에게 자동으로 관리자 접근 권한을 할당합니다.
`bindDn`	디렉터리에 인증하고 연결하는 데 사용되는 서비스 계정의 DN. 디렉터리가 익명 바인드 접근을 허용하는 경우 생략할 수 있습니다.
`bindPasswordSecret`	바인드 계정 비밀번호를 저장하는 Secret을 참조합니다. 이 Secret은 `bobctl` 명령과 함께 `--bind-password` 옵션이 제공될 때 자동으로 생성됩니다.
`useTruststoreSpi`	LDAP CA 인증서가 서버 유효성 검사에 사용되는 시기를 지정합니다. 값: `always`(기본값, 개인 또는 내부 발급 CA 인증서의 경우), `ldapsOnly`(공개적으로 신뢰할 수 있는 CA 인증서의 경우), `never`(보안되지 않은 `ldap://`를 통해 연결하는 경우).
`ldapsCACertSecret`	PEM 형식의 LDAP 서버 CA 인증서가 포함된 Secret을 참조합니다. 이 Secret은 `--ca-cert-file`이 제공될 때 자동으로 생성됩니다.
`searchScope`	디렉터리 검색의 깊이를 결정합니다. `2`는 모든 자식 컨테이너 및 하위 트리를 검색합니다(기본값). `1`은 직접 자식 항목으로만 검색을 제한합니다.
`customUserSearchFilter`	서비스 계정을 제외하거나 특정 사용자 유형으로 검색을 제한하는 등 모든 사용자 검색 작업에 적용되는 추가 필터.
`userSync.enabled`	`true`로 설정하면 공급자가 처음 구성될 때 모든 사용자를 가져오고 이후 디렉터리 변경 사항은 5분마다 동기화됩니다. 대부분의 배포에 권장됩니다.
`userAttributeMappings`	디렉터리 속성이 `email`, `firstName`, `lastName`과 같은 Bob 사용자 프로필 필드에 매핑되는 방식을 정의합니다.
`priority`	여러 공급자가 구성된 경우 공급자가 평가되는 순서를 결정합니다. 값이 낮은 공급자가 먼저 확인됩니다. 기본값은 `0`입니다.
`groupMapper`	LDAP 그룹을 Keycloak으로 동기화합니다. LDAP 그룹 동기화 구성을 참조하세요.

사용자 동기화 동작

userSync.enabled가 true로 설정된 경우 Bob은 LDAP 공급자가 등록될 때 모든 사용자의 일회성 가져오기를 수행합니다. 초기 가져오기가 완료된 후 진행 중인 사용자 라이프사이클 동기화는 SCIM을 통해 자동으로 처리됩니다.

팁:

대규모 LDAP 디렉터리의 경우 userSync.enabled를 false로 설정하고 사용자가 처음 로그인할 때 프로비저닝되도록 허용하는 것을 고려하세요. 이 접근 방식은 LDAP 공급자 등록에 필요한 시간을 단축할 수 있습니다.

LDAP 그룹 동기화 구성

선택적 groupMapper 구성을 사용하여 LDAP 그룹을 Keycloak과 동기화합니다. 그룹 동기화를 사용하면 LDAP 디렉터리에 정의된 사용자와 그룹 멤버십을 Keycloak을 통해 가져오고 관리할 수 있습니다.

groupsDn 매개변수는 필수입니다. 다른 모든 매개변수는 선택적이며 LDAP 디렉터리 스키마 및 그룹 구조에 맞게 사용자 정의할 수 있습니다.

제한 사항:

bob-admins 및 bob-users 그룹은 플랫폼 관리 그룹으로 LDAP 그룹 동기화에서 자동으로 제외됩니다.

매개변수	기본값	설명
`groupsDn`	필수	LDAP 그룹 항목이 포함된 기본 고유 이름(DN).
`name`	`groups`	Keycloak에서 그룹 매퍼의 표시 이름.
`groupNameLdapAttribute`	`cn`	Keycloak이 그룹 이름으로 사용하는 LDAP 속성.
`groupObjectClasses`	`groupOfNames`	그룹 항목을 식별하는 LDAP 개체 클래스.
`membershipLdapAttribute`	`member`	멤버 정보를 포함하는 그룹 항목의 속성.
`membershipAttributeType`	`DN`	멤버 값의 형식. 지원 값: `DN`(고유 이름) 및 `UID`(사용자 ID).
`userRolesRetrieveStrategy`	`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	그룹 멤버십을 결정하는 데 사용되는 방법.
`memberOfLdapAttribute`	`memberOf`	`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`를 사용할 때 그룹 멤버십 정보를 포함하는 사용자 속성.
`customGroupSearchFilter`	없음	그룹을 검색할 때 사용되는 추가 LDAP 필터. 필터는 괄호로 묶어야 합니다(예: `(cn=dept-*)`).
`mode`	`LDAP_ONLY`	동기화 모드. 지원 값: `LDAP_ONLY` 및 `READ_ONLY`.
`groupsPath`	`/`	동기화된 그룹이 생성되는 Keycloak 그룹 계층 구조의 위치.

그룹 멤버십 조회 전략

userRolesRetrieveStrategy 매개변수는 Keycloak이 사용자의 그룹 멤버십을 식별하는 방법을 제어합니다.

전략	설명
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`	사용자에 대한 참조를 포함하는 그룹 항목을 검색하여 그룹 멤버십을 가져옵니다.
`GET_GROUPS_FROM_USER_MEMBEROF_ATTRIBUTE`	사용자의 `memberOf` 속성에서 그룹 멤버십을 가져옵니다.
`LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY`	LDAP 디렉터리에서 지원하는 중첩 그룹을 포함하여 재귀적으로 그룹 멤버십을 가져옵니다.

팁:

LDAP 디렉터리가 memberOf 속성을 통해 사용자 항목에 그룹 멤버십 정보를 저장하거나 재귀적 검색이 필요한 중첩 그룹 구조를 사용하지 않는 한 LOAD_GROUPS_BY_MEMBER_ATTRIBUTE를 사용합니다.

구성 예시

name: corp-ldap

vendor: other
connectionUrl: ldaps://ldap.corp.example.com:636
usersDn: ou=People,dc=corp,dc=example,dc=com
usernameLDAPAttribute: uid
rdnLDAPAttribute: uid
uuidLDAPAttribute: entryUUID
userObjectClasses: inetOrgPerson,organizationalPerson,person

domains:
  - corp.example.com

bindDn: cn=bob-svc,ou=ServiceAccounts,dc=corp,dc=example,dc=com

useTruststoreSpi: always

userSync:
  enabled: true

userAttributeMappings:
  - ldapAttribute: mail
    userModelAttribute: email
  - ldapAttribute: givenName
    userModelAttribute: firstName
  - ldapAttribute: sn
    userModelAttribute: lastName

# Optional: synchronize LDAP groups into Keycloak
groupMapper:
  groupsDn: ou=Groups,dc=corp,dc=example,dc=com
  groupObjectClasses: groupOfNames
  membershipLdapAttribute: member

./bobctl add-ldap --config corp-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt

적용 전 LDAP 구성 유효성 검사

클러스터에 LDAP 구성을 적용하기 전에 --dry-run 옵션을 사용하여 구성을 유효성 검사하고 생성될 리소스를 미리 봅니다. 드라이 런을 실행하면 클러스터에 변경 사항이 적용되기 전에 일반적인 구성 문제를 식별하는 데 도움이 됩니다.

./bobctl add-ldap --config my-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt \
  --dry-run

드라이 런은 다음 확인을 수행합니다:

구성 파일에 모든 필수 구성 매개변수가 있는지 유효성 검사합니다.

--ca-cert-file이 사용되는 경우 지정된 CA 인증서 파일을 로컬에서 사용할 수 있는지 확인합니다.

생성 또는 업데이트될 BobLDAP 커스텀 리소스의 미리 보기를 표시합니다.

구성의 일부로 생성될 Kubernetes Secret을 표시합니다.

클러스터에서 리소스를 생성, 수정 또는 삭제하지 않고 종료합니다.

참고:

드라이 런 작업은 LDAP 서버에 대한 네트워크 연결을 유효성 검사하거나, 제공된 자격 증명을 디렉터리에 대해 인증하거나, 클러스터에서 참조된 Secret의 존재를 확인하지 않습니다. 이러한 유효성 검사는 구성이 적용된 후에만 수행되며 LDAPReachable 및 LDAPAuthenticated 상태 조건에 반영됩니다.

구성 적용

LDAP 구성 파일을 생성하고 유효성 검사한 후 add-ldap 명령을 실행하여 구성을 클러스터에 적용합니다.

./bobctl add-ldap --config my-ldap.yaml \
  --bind-password '<bind-password>' \
  --ca-cert-file /path/to/ca.crt

플래그	필수 여부	설명
`--config <file>`	예	LDAP 구성 파일 경로를 지정합니다.
`--bind-password <password>`	아니오	클러스터에 `bindPasswordSecret`을 생성합니다. 디렉터리가 익명 바인드 접근을 허용하는 경우 필요하지 않습니다.
`--ca-cert-file <path>`	아니오	로컬 PEM 파일에서 `ldapsCACertSecret`을 생성합니다. 공개적으로 신뢰할 수 있는 CA 또는 보안되지 않은 `ldap://` 연결을 사용하는 경우 생략할 수 있습니다.
`--dry-run`	아니오	구성을 유효성 검사하고 클러스터에 변경 사항을 적용하지 않고 생성 또는 업데이트될 리소스의 미리 보기를 표시합니다.

명령이 실행되면 bobctl은 오퍼레이터가 구성을 조정할 때까지 기다리고 BobLDAP 커스텀 리소스가 보고하는 상태 조건을 확인하여 LDAP 공급자를 유효성 검사합니다.

확인	확인 내용
`Ready`	공급자가 성공적으로 생성 및 등록되었습니다.
`LDAPReachable`	클러스터에서 LDAP 서버에 접근할 수 있습니다.
`LDAPAuthenticated`	구성된 바인드 자격 증명이 유효합니다.
`UserSyncSucceeded`	초기 사용자 가져오기가 성공적으로 완료되었습니다. 이 조건은 `userSync.enabled`가 `true`로 설정된 경우에만 평가됩니다.

기본 유효성 검사 타임아웃은 600초(10분)입니다. 대규모 디렉터리가 있는 환경에서는 초기 사용자 동기화를 완료하는 데 몇 분이 걸릴 수 있습니다. 타임아웃을 늘리려면 BOB_LDAP_WAIT_TIMEOUT 환경 변수를 설정합니다:

BOB_LDAP_WAIT_TIMEOUT=900 ./bobctl add-ldap --config my-ldap.yaml

여러 LDAP 공급자 구성

여러 LDAP 또는 Active Directory 소스의 사용자를 통합하려면 각 디렉터리에 대한 별도의 구성 파일을 생성하고 각 구성의 name 필드에 고유한 값을 할당합니다.

./bobctl add-ldap --config ldap-corp.yaml
./bobctl add-ldap --config ldap-subsidiary.yaml

LDAP 리소스 상태 검사

구성된 LDAP 공급자의 상태를 보려면:

oc get bobldap -n <instance-namespace>

특정 공급자의 세부 구성 및 상태 정보를 보려면:

oc get bobldap <name> -n <instance-namespace> -o yaml

통합 확인

bobctl add-ldap가 성공적으로 완료되면 LDAP 통합이 올바르게 작동하는지 확인합니다.

BobLDAP 커스텀 리소스의 상태를 확인합니다:

oc get bobldap <name> -n <instance-namespace> -o yaml

다음 상태 조건이 True로 설정되어 있는지 확인합니다:

조건	목적
`Ready`	LDAP 공급자가 성공적으로 등록되었음을 확인합니다.
`LDAPReachable`	클러스터가 LDAP 서버와 통신할 수 있음을 확인합니다.
`LDAPAuthenticated`	구성된 바인드 자격 증명이 유효함을 확인합니다.
`UserSyncSucceeded`	모든 사용자를 성공적으로 가져왔음을 확인합니다. `userSync.enabled: true`인 경우에만 표시됩니다.

조건이 False인 경우 진단 세부 정보를 위해 해당 message 필드를 검토합니다.

페더레이션된 LDAP 디렉터리의 자격 증명을 사용하여 로그인하여 사용자 인증이 작동하는지 확인합니다.

Bob URL을 엽니다:

https://bob.<namespace>.<ingress-domain>

성공적인 로그인은 연결, 인증, 도메인 라우팅, SCIM 프로비저닝 및 역할 매핑이 올바르게 작동함을 확인합니다.

사용자가 처음 로그인한 후 Bob에서 사용자 레코드를 사용할 수 있는지 확인합니다.

Bob 관리 UI를 엽니다:

https://bob.<namespace>.<ingress-domain>/admin

Bob 관리자로 로그인하고 테스트 사용자가 사용자 목록에 나타나는지 확인합니다.

groupMapper가 LDAP 그룹을 Bob 관리자에 매핑하도록 구성된 경우:

매핑된 관리자 그룹에 속하는 사용자 계정으로 로그인합니다.
사용자가 Bob 관리 UI에 접근할 수 있는지 확인합니다.
관리자 수준 기능을 사용할 수 있는지 확인합니다.

userSync.enabled: true인 경우 LDAP 공급자가 등록된 후 자동으로 사용자를 가져옵니다. 테스트 사용자는 초기 로그인 없이 Bob에 나타나야 합니다.

몇 분 후에도 사용자가 나타나지 않으면 프로비저닝 오류에 대한 bob-admin 로그를 검토합니다:

oc logs -n <instance-namespace> -l app=bob-admin --tail=100

보고된 SCIM 관련 오류를 검토하고 동기화 프로세스를 다시 시도하기 전에 오류를 해결합니다.

LDAP 통합

이 페이지에서