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

bobctl configure-idp를 사용하여 LDAP 또는 Active Directory 환경을 Keycloak에 사용자 페더레이션 공급자로 연결합니다. 설치 중 또는 배포 후 언제든지 이 설정을 완료할 수 있습니다.

시작하기 전에

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

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

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

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

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

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

구성 파일 참조

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

cp config-idp-template.yaml my-idp.yaml

구성 파일에는 전체 배포에 적용되는 최상위 필드와 각 항목이 하나의 LDAP 페더레이션 공급자를 설명하는 선택적 ldaps 목록의 두 섹션이 있습니다.

최상위 필드

필드	필수 여부	설명
`domains`	예	Bob이 로그인 시 허용하는 이메일 도메인 목록. 도메인을 제거하면 해당 도메인이 등록 해제되어 해당 도메인의 사용자가 로그인할 수 없게 됩니다.
`adminEmails`	아니오	Bob 관리자 권한을 부여할 사용자 이메일 목록. 오퍼레이터가 Keycloak `bob-admins` 그룹과 Bob 관리자 데이터베이스를 원자적으로 업데이트합니다.
`ldaps`	아니오	LDAP 페더레이션 공급자 구성 목록. 직접 Keycloak 사용자만 사용하는 배포에서는 완전히 생략합니다.

필수 필드 (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 필드는 온프레미스 배포에서 도메인 기반 라우팅을 구성하는 유일한 방법입니다. Bob 관리 사용자 인터페이스를 통해 도메인을 구성하지 마세요. 이는 올바른 방법이 아니며 인증 오류를 일으킬 수 있습니다.

선택적 필드 (LDAP 공급자 항목별)

필드	설명
`bindDn`	디렉터리에 인증하고 연결하는 데 사용되는 서비스 계정의 DN. 디렉터리가 익명 바인드 접근을 허용하는 경우 생략할 수 있습니다.
`bindPasswordSecret`	바인드 계정 비밀번호가 포함된 기존 Secret의 이름. `bobctl configure-idp` 실행 전에 인스턴스 네임스페이스에 생성되어 있어야 합니다.
`useTruststoreSpi`	LDAP CA 인증서가 서버 유효성 검사에 사용되는 시기를 지정합니다. 값: `always`(기본값, 개인 또는 내부 발급 CA 인증서의 경우), `ldapsOnly`(공개적으로 신뢰할 수 있는 CA 인증서의 경우), `never`(보안되지 않은 `ldap://`를 통해 연결하는 경우).
`ldapsCACertSecret`	PEM 형식의 LDAP 서버 CA 인증서가 포함된 기존 Secret의 이름. `bobctl configure-idp` 실행 전에 인스턴스 네임스페이스에 생성되어 있어야 합니다.
`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를 사용합니다.

구성 예시

# Bob이 로그인 시 허용해야 하는 이메일 도메인
domains:
  - corp.example.com

# Bob 관리자 권한을 부여할 사용자
adminEmails:
  - alice@corp.example.com

# LDAP 페더레이션 공급자
ldaps:
  - 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

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

    useTruststoreSpi: always
    ldapsCACertSecret: corp-ldap-ca

    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 configure-idp --config my-idp.yaml

적용 전 IDP 구성 유효성 검사

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

./bobctl configure-idp --config my-idp.yaml --dry-run

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

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

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

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

참고:

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

구성 적용

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

./bobctl configure-idp --config my-idp.yaml

플래그	필수 여부	설명
`--config <file>`	예	IDP 구성 파일 경로를 지정합니다.
`--dry-run`	아니오	구성을 유효성 검사하고 클러스터에 변경 사항을 적용하지 않고 생성 또는 업데이트될 리소스의 미리 보기를 표시합니다.

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

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

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

BOB_IDP_WAIT_TIMEOUT=900 ./bobctl configure-idp --config my-idp.yaml

여러 LDAP 공급자 구성

여러 LDAP 또는 Active Directory 소스의 사용자를 통합하려면 IDP 구성 파일의 ldaps 목록에 각 디렉터리를 별도의 항목으로 추가하고 configure-idp를 다시 실행합니다.

./bobctl configure-idp --config my-idp.yaml

IDP 리소스 상태 검사

IDP 구성 상태를 보려면:

oc get bobidp -n <instance-namespace>

세부 구성 및 상태 정보를 보려면:

oc get bobidp bob-idp -n <instance-namespace> -o yaml

통합 확인

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

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

oc get bobidp bob-idp -n <instance-namespace> -o yaml

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

조건	목적
`Ready`	구성이 성공적으로 적용되었음을 확인합니다.
`LDAPRegistered`	LDAP 공급자가 Keycloak에 등록되었음을 확인합니다.
`LDAPReachable`	클러스터가 LDAP 서버와 통신할 수 있음을 확인합니다.
`LDAPAuthenticated`	구성된 바인드 자격 증명이 유효함을 확인합니다.
`LDAPUserSyncSucceeded`	모든 사용자를 성공적으로 가져왔음을 확인합니다. `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 통합

이 페이지에서