키클로크는 오픈소스 싱글사인온(SSO) 및 ID 관리 솔루션으로, 다양한 클라이언트 애플리케이션과 원활하게 통합할 수 있는 기능을 제공합니다. 이 튜토리얼에서는 편리하고 안전한 사용자 인증을 위해 SAML(보안 어설션 마크업 언어) 클라이언트와 Keycloak을 통합하는 프로세스를 살펴봅니다.

Keycloak은 Couchbase에서 테스트하거나 검증하지 않았다는 점에 유의해야 합니다. Couchbase는 Microsoft Azure AD, Okta, Ping Identity, CyberArk, Google Workspace 및 OneLogin에 대한 지침과 지원을 제공합니다. 

일반적인 SAML 공급업체(이 경우 Keycloak)를 사용하여 SAML 인증을 통합하는 방법을 보여드리겠습니다. 모든 SAML 공급업체를 사용할 수 있지만, 최적의 호환성과 원활한 통합 환경을 위해 지원되는 서비스 중 하나를 사용하는 것을 적극 권장합니다.

전제 조건

    • 키클로크 인스턴스를 실행하고 있다고 가정합니다.
    • 조직 관리자로서 Capella에 액세스할 수 있습니다.
    • 테넌트에 대해 SSO가 사용 설정되었습니다.

1단계: 키클로크 설정

키클로크를 ID 공급자로 배포하는 방법을 설명하는 것은 이 튜토리얼의 범위를 벗어납니다. 이미 작동하는 Keycloak 인스턴스가 있고 이를 활용할 준비가 되어 있다고 가정합니다.

만들기 영역create a keycloak realm

Keycloak에서 새 영역을 만들어 SAML 클라이언트의 구성을 관리합니다. 이 예제에서는 이 영역을 "acme"이라고 부릅니다.

영역이 생성되면 공개 키를 저장해야 합니다. 가장 쉬운 방법은 SAML 메타데이터 엔드포인트를 여는 것입니다. 

SAML 구성 가져오기

왼쪽의 영역 설정을 클릭하세요. 그러면 영역 설정 페이지가 열립니다. 이 페이지 하단에는 두 개의 메타데이터 엔드포인트가 있습니다. 

get the SAML configuration

를 클릭해야 합니다. SAML 2.0 ID 공급자 메타데이터 링크를 클릭합니다. XML에는 Capella SSO 구성을 만들 때 필요한 SAML 메타데이터가 포함되어 있습니다. 

SAML HTTP-POST 바인딩:

X.509 인증서:

다음 단계에서 필요하므로 이 내용을 메모해 두세요.

2단계: 카펠라에서 영역 만들기

Create a realm in Capella

이 단계에서는 Capella 영역을 만들 것입니다. 이를 설정하려면 1단계에서 저장한 인증서를 복사하여 SAML 서명 인증서 필드. 또한 HTTP_POST 바인딩 URL을 로그인 엔드포인트 URL 필드에 입력합니다.

서명 알고리즘과 다이제스트 알고리즘은 기본값으로 왼쪽에 있어야 합니다.

Capella SAML Signing Certificate field

SAML 프로토콜 바인딩 필드가 HTTP-POST로 설정되어 있는지 확인합니다:

SAML protocol binding

이제 영역을 만들 준비가 되었습니다. 

3단계: Keycloak SAML 클라이언트 만들기

카펠라 영역 정보 표시

이 시점에서 카펠라 영역을 만들었습니다. 이제 Keycloak에서 SAML 클라이언트를 만들 준비가 되었습니다.

먼저, 카펠라 영역에 대한 정보가 필요합니다. 카펠라에서 새로 만든 영역 이름을 클릭하면 영역 정보가 표시됩니다.

Display Capella realm information

클라이언트 생성 과정에서 이 화면의 몇 가지 정보를 Keycloak에 복사해야 합니다. 다음 필드를 메모해 두세요.

    • 영역 이름
    • 엔티티 ID
    • 콜백 URL
    • 서명 인증서

Keycloak SAML 클라이언트 만들기

Keycloak 관리 콘솔을 열고 앞서 만든 영역을 선택합니다. 탐색의 왼쪽에 있는 클라이언트.

Create the Keycloak SAML client

이 화면에서 클라이언트를 만듭니다:

복사 엔티티ID 를 복사하여 키클로크의 클라이언트 ID 필드에 붙여넣습니다. 원하는 이름을 사용할 수 있습니다. 이름 필드에 입력합니다. 

준비가 완료되면 다음 버튼을 클릭합니다. 이 화면에서 스크린샷에 표시된 대로 홈 URL과 리디렉션 URI를 입력해야 합니다:

키클라우드에서 새 SAML 클라이언트가 생성됩니다. 저장 버튼을 클릭합니다.

Keycloak SAML 클라이언트 구성하기

생성한 SAML 클라이언트를 열고 다음을 클릭해야 합니다. 고급 탭을 클릭합니다. 그러면 다음과 같은 화면이 나타납니다:

Configure the Keycloak SAML client

이 화면에서는 다음 항목만 입력하면 됩니다. 어설션 소비자 서비스 POST 바인딩 URL. Capella의 영역 페이지에서 콜백 URL을 복사하여 이 필드에 입력해야 합니다.

Assertion Consumer Service POST Binding URL

클라이언트 서명 가져오기

기본적으로 고객 서명 필요 를 사용하도록 설정합니다. 이 경우 Keycloak은 SAML 요청의 유효성을 검사합니다. 이를 위해서는 Capella의 SAML 공개키를 저장하고 Keycloak으로 가져와야 합니다. 

먼저 Capella에서 인증서를 저장해야 합니다. Capella에서 SSO 설정 페이지를 엽니다. 

다음과 같이 표시된 URL을 엽니다. 서명 인증서 https://couchbase-capella.us.auth0.com/pem?cert=connection 을 클릭합니다. 그러면 다운로드가 트리거됩니다. 파일 이름은 couchbase-capella.pem입니다. 이 인증서는 Keycloak으로 전송되는 SAML 어설션의 서명을 확인하는 데 사용됩니다. 이 인증서는 Couchbase 데이터베이스의 보안 인증서와 동일하지 않습니다.

이제 Keycloak에 다시 로그인하여 이전에 만든 클라이언트를 열어야 합니다. 클라이언트의 키 탭을 클릭합니다. 

    • 를 클릭합니다. 의 가져오기 키 버튼.
    • 인증서 PEM에서 아카이브 형식 드롭다운. 
    • 찾아보기를 클릭하여 파일을 선택하고 Capella에서 방금 저장한 파일을 찾습니다.

    • 가져오기를 클릭하여 Capella의 인증서를 Keycloak에 로드합니다.

4단계: SAML 매퍼 구성하기

이제 SAML 클라이언트가 준비되었습니다. 다음 단계에서는 사용자가 로그인할 때 Capella가 어설션에서 사용자 세부 정보를 읽을 수 있도록 필요한 SAML 매퍼를 구성할 것입니다.

방금 생성한 SAML 클라이언트를 열고 클라이언트 범위 탭을 클릭합니다:

클라이언트 ID와 대시 및 전용의 이름을 딴 클라이언트 범위가 표시되어야 합니다. 사용자 지정 매퍼를 추가하려면 해당 링크를 클릭해야 합니다.

해당 버튼을 클릭하면 다음 화면이 표시됩니다:

성 매퍼 추가

    • 추가를 클릭합니다. 새 매퍼 구성 버튼
    • 매퍼 목록에서 사용자 속성을 선택합니다.

Map a built in user property

    • 다음 값을 사용하여 양식을 작성합니다:
      이름: X500 성
      속성: 성
      친근한 이름: 성
      SAML 속성 이름: 가족_이름
      SAML 속성 이름 형식:  지정되지 않음

클릭 저장. 확인 메시지가 표시되면 다음을 클릭해야 합니다. 전용 범위 링크를 클릭하여 다음 매퍼를 추가합니다.

이제 다음 매퍼를 추가할 준비가 되었습니다.

첫이름 매퍼 추가

    • 를 클릭하고 매퍼 추가  버튼을 클릭하고 구성별. 
    • 매퍼 목록에서 사용자 속성을 선택합니다.

    • 다음 값을 사용하여 양식을 작성합니다:
      이름: X500 주어진 이름
      속성: 이름
      친근한 이름: 주어진 이름
      SAML 속성 이름: 주어진_이름
      SAML 속성 이름 형식:  지정되지 않음

클릭 저장. 확인 메시지(매핑이 성공적으로 생성됨)가 표시되면 매핑이 성공적으로 생성되었습니다. 전용 범위 링크를 클릭하여 다음 매퍼를 추가합니다.

이제 최종 매퍼를 추가할 준비가 되었습니다.

이메일 매퍼 추가

    • 를 클릭하고 매퍼 추가  버튼을 클릭하고 구성별. 
    • 매퍼 목록에서 사용자 속성을 선택합니다.

    • 다음 값을 사용하여 양식을 작성합니다:
      이름: X500 이메일
      속성이메일
      친근한 이름이메일
      SAML 속성 이름이메일
      SAML 속성 이름 형식:  지정되지 않음

클릭 저장. 확인 메시지가 표시되면 다음을 클릭해야 합니다. 전용 범위 링크를 클릭하여 매퍼의 전체 목록을 확인하세요. 이 시점에서 세 가지가 모두 표시되어야 합니다.

5단계: 통합 테스트

테스트를 시작하려면 영역에 사용자가 한 명 이상 있어야 합니다. 기존 사용자를 사용하거나 연동 테스트 전용 사용자를 만들 수 있습니다. 또한 테스트를 시작하기 전에 Capella에서 로그아웃했는지 확인하세요.

    • 사용을 클릭합니다. 싱글 사인온
    • Capella SSO 영역 이름 입력

테넌트 이름을 입력하면 키클로크로 이동합니다. 로그인하려면 테스트 사용자 및 자격 증명을 사용해야 합니다. 로그인 절차가 끝나면 Capella에 로그인됩니다. 

참고: Capella는 JIT 사용자 프로비저닝을 사용합니다. Capella는 ID 공급자를 통해 사용자가 처음 로그인할 때 자동으로 사용자를 생성합니다.

결론

SAML 클라이언트를 Keycloak과 통합하면 Keycloak의 강력한 ID 관리 기능을 활용하여 Capella에서 원활한 싱글 사인온 기능을 사용할 수 있습니다. 이 블로그에 제공된 단계별 가이드를 따르면 이제 Capella와 Keycloak을 성공적으로 통합하여 안전한 사용자 인증과 간소화된 사용자 경험을 보장하는 데 필요한 지식과 도구를 갖추게 될 것입니다.

작성자

게시자 이스트반 오르반

이스트반 오르반은 Couchbase의 수석 제품 관리자로 영국에 거주하고 있습니다. Istvan은 풀스택 소프트웨어 엔지니어, 팀 리더, Devops 엔지니어로서 다양한 경험을 보유하고 있습니다. 그의 주요 관심 분야는 보안과 싱글 사인온입니다. Istvan은 20년 경력의 전문가로서 여러 대규모 프로젝트를 이끌었습니다.

모든 게시물

댓글 남기기