시작하기 전에
다음 항목이 필요합니다.- Enterprise 플랜을 사용하는 조직과 ClickHouse 버전 26.4 이상을 실행 중인 서비스
-
JWT provider를 추가하기 위해 해당 서비스에 대한
control-plane:service:manage권한(permission)이 있는 ClickHouse Cloud 역할(예: 관리자 또는 서비스 관리자) - 최소 Cloud Application Administrator 역할이 있는 Microsoft Entra admin center 액세스 권한
- 개별 사용자가 아닌 그룹을 앱 역할에 할당하려는 경우 Microsoft Entra ID P1 또는 P2
-
설정 테스트용 Azure CLI(
az) 및clickhouse-client -
Entra ID를 통해 부여할 ClickHouse 역할(Roles) 목록. 각 역할은 같은 이름의 Entra ID 앱 역할로 생성됩니다. 이 가이드에서는 다음 두 가지 역할을 사용합니다.
작동 방식
- Entra ID에 ClickHouse Cloud 서비스를 나타내는 애플리케이션을 등록하고, ClickHouse 역할마다 앱 역할(app role)을 하나씩 정의합니다.
- Entra ID 사용자, 그룹, 애플리케이션을 해당 앱 역할에 할당합니다.
- 사용자는 Azure CLI 또는
clickhouse-client --login으로 로그인하거나, 애플리케이션은 클라이언트 자격 증명 부여(client credentials grant) 방식을 사용합니다. 그러면 Entra ID는 v2.0 액세스 토큰을 발급합니다. 이 토큰의aud클레임에는 애플리케이션(클라이언트) ID가,roles클레임에는 호출자에게 할당된 앱 역할 목록이 담깁니다. - ClickHouse Cloud는 Entra ID 공개 키로 토큰 시그니처를 검증하고
iss및aud클레임을 확인한 다음,roles클레임에 지정된 ClickHouse 역할의 권한을 가진 임시 사용자를 생성합니다. 이때 권한은default사용자의 권한을 넘지 않도록 제한됩니다.
Entra ID에 ClickHouse 등록하기
1
앱 등록 만들기
Microsoft Entra 관리 센터에서 App registrations를 열고 New registration을 선택하세요.
- Name: 표시 이름을 입력합니다(예:
clickhouse-cloud-production). - Supported account types: 단일 테넌트를 선택합니다. 포털 버전에 따라 이 옵션은 Single tenant only 또는 Accounts in this organizational directory only로 표시됩니다.
- Redirect URI: 비워 둡니다. 사용자는 디바이스 코드 흐름(device code flow)으로 로그인하며, 이 방식은 리디렉션 URI를 사용하지 않습니다.
- Application (client) ID: 이후
<CLIENT_ID>로 표기합니다. 이 값은 토큰의aud클레임으로 사용됩니다. - Directory (tenant) ID: 이후
<TENANT_ID>로 표기합니다. 이 값은 발급자와 JWKS URL에 포함됩니다.
2
v2.0 액세스 토큰 요청
기본적으로 Entra ID는 v1.0 액세스 토큰을 발급하며, 이 토큰의 발급자는
https://sts.windows.net/<TENANT_ID>/입니다. 이 대신 v2.0 토큰을 받도록 애플리케이션을 구성하십시오. v2.0 토큰의 발급자는 https://login.microsoftonline.com/<TENANT_ID>/v2.0이며, aud 클레임은 항상 클라이언트 ID입니다.앱 등록에서 Manifest를 열고 액세스 토큰 버전을 2로 설정한 다음 Save를 선택하십시오. 속성 이름은 편집기에 표시되는 매니페스트 포맷에 따라 다릅니다.- Microsoft Graph 포맷:
api섹션의requestedAccessTokenVersion - Azure AD Graph 포맷: 아래 스크린샷과 같이 최상위 수준의
accessTokenAcceptedVersion
3
API 노출
Expose an API를 엽니다.
-
Application ID URI 옆의 Add를 선택하고 기본값
api://<CLIENT_ID>를 그대로 둔 채 저장합니다. 클라이언트는 이 URI를 사용하여 ClickHouse용 토큰을 요청합니다. 이 URI를 설정해도 v2.0 토큰의aud클레임은 변경되지 않으며, 클라이언트 ID로 유지됩니다. -
Add a scope를 선택하고 양식을 작성합니다. 사용자는 로그인할 때 이 범위를 요청합니다. 애플리케이션이 자체 자격으로 인증하는 경우에는 이 범위를 사용하지 않습니다.
5
앱 역할 생성
각 앱 역할은 하나의 ClickHouse 역할에 대응합니다. 앱 역할의 Value는 토큰의
roles 클레임에 표시되는 값이며, 대소문자까지 ClickHouse 역할 이름과 정확히 일치해야 합니다.App roles를 열고 ClickHouse 역할마다 Create app role을 선택하세요.다음 예시에서는 ClickHouse 역할 이름을 값으로 사용하는 앱 역할 3개를 정의합니다.
6
할당 필요
기본적으로 테넌트의 모든 사용자는 해당 애플리케이션의 토큰을 발급받을 수 있습니다. 앱 역할에 할당한 사용자, 그룹, 애플리케이션만 토큰을 발급받도록 제한하려면 Enterprise applications를 열고 앱 등록과 이름이 같은 애플리케이션을 선택합니다. 그런 다음 Properties를 열어 Assignment required?를 Yes로 설정하고 Save를 선택하십시오.
7
앱 역할에 사용자 및 그룹 할당
동일한 엔터프라이즈 애플리케이션에서 Users and groups를 열고 Add user/group을 선택하십시오. 사용자 또는 그룹을 선택하고 앱 역할을 선택한 다음 Assign을 선택하십시오. 각 사용자 또는 그룹마다 이 과정을 반복하십시오.직접 또는 그룹을 통해 여러 앱 역할을 할당받은 사용자는
roles 클레임에 해당 역할이 모두 포함됩니다.그룹에 앱 역할을 할당하려면 Microsoft Entra ID P1 또는 P2가 필요합니다. 중첩된 그룹은 지원되지 않으며, 할당된 그룹의 직접 멤버만 해당 앱 역할을 받습니다.
ClickHouse에서 대응하는 역할 생성
SQL 콘솔 등에서default 사용자로 서비스에 연결한 후, 각 앱 역할 값마다 대응하는 역할을 생성하십시오.
- 역할 이름은 case-sensitive(대소문자 구분)이며 앱 역할 값과 정확히 일치해야 합니다.
- ClickHouse는
roles클레임에 포함된 이름 중 서비스에 존재하는 역할과 일치하지 않는 이름을 무시합니다. - ClickHouse Cloud에서 JWT provider의 권한 상한은
default사용자입니다. ClickHouse는 역할에 부여된 권한 중default사용자에게 없는 권한을 모두 제외합니다.
Entra ID를 JWT provider로 추가
JWT provider 추가의 단계에 따라 다음 값을 입력하십시오.사용자로 연결하기
앱 등록에서 얻은 값과 서비스 호스트 이름을 셸 변수로 설정하십시오:Azure CLI 토큰 전달
Azure CLI로 로그인한 후 ClickHouse 애플리케이션용 액세스 토큰을 요청하고,--jwt 옵션을 사용하여 해당 토큰을 clickhouse-client에 전달하십시오:
--login을 사용하세요.
clickhouse-client로 로그인
clickhouse-client는 OAuth 2.0 디바이스 코드 흐름(device code flow)을 직접 수행하고, 세션 중에 토큰을 갱신할 수 있습니다:
offline_access를 제거하지 마십시오. 이 값이 있어야 Entra ID가 리프레시 토큰을 반환하며, 클라이언트는 이 토큰으로 액세스 토큰을 갱신합니다. 이 값이 없으면 액세스 토큰이 만료될 때마다 다시 로그인해야 합니다.
애플리케이션으로 연결
ETL 작업이나 백엔드 서비스와 같은 애플리케이션은 OAuth 2.0 클라이언트 자격 증명 부여(client credentials grant) 방식을 통해 자체 ID로 인증합니다. 애플리케이션에 부여하는 앱 역할은 Applications 멤버 유형을 허용해야 합니다.- App registrations에서 워크로드용 애플리케이션을 별도로 등록하십시오. Certificates & secrets에서 클라이언트 시크릿을 생성하거나 인증서를 업로드하십시오. 아래 명령어에서는 워크로드의 클라이언트 ID와 시크릿을 각각
<WORKLOAD_CLIENT_ID>및<WORKLOAD_CLIENT_SECRET>으로 표기합니다. - 워크로드의 앱 등록에서 API permissions를 열고 Add a permission을 선택하십시오. APIs my organization uses에서 ClickHouse 애플리케이션을 찾아 Application permissions를 선택한 후, 워크로드에 필요한 앱 역할을 선택하고 Add permissions를 클릭하십시오.
- Grant admin consent를 선택하여 워크로드에 앱 역할을 할당하십시오.
확인
연결한 후 다음과 같이 세션의 아이덴티티와 권한을 확인하십시오:
ClickHouse는 역할 자체를 임시 사용자에게 부여하지 않습니다. 대신 토큰에 지정된 역할의 권한을 수집하고, 이를
default 사용자의 권한과 교집합한 뒤 그 결과를 사용자에게 직접 부여합니다. 따라서 SHOW CURRENT ROLES는 행을 반환하지 않습니다.
사용자 토큰의 경우 Entra ID는 sub를 사용자와 애플리케이션 조합별로 고유한 불투명(opaque) 식별자로 설정합니다. 이 값은 사용자의 이메일 주소나 객체 ID와는 다릅니다.
권장 사항
개별 사용자 대신 그룹 할당
각 앱 역할에 Entra ID 그룹을 하나씩 할당한 다음, 그룹 멤버십을 변경하여 액세스 권한을 부여하거나 철회하십시오. 이렇게 하면 팀원이 합류하거나 떠나더라도 애플리케이션을 수정할 필요가 없습니다.환경별로 별도의 앱 등록 사용
토큰의aud 클레임에는 해당 앱 등록의 클라이언트 ID가 담겨 있습니다. 운영 환경과 스테이징 환경에 각각 별도의 앱 등록을 사용하면, 한 환경용으로 발급된 토큰으로는 다른 환경에 인증할 수 없습니다.
역할 변경은 다음 토큰부터 적용됩니다
Entra ID는 토큰을 발급할 때roles 클레임을 기록합니다. 따라서 사용자의 앱 역할 할당을 변경하면 해당 사용자가 새 토큰을 받은 시점부터 변경 사항이 적용됩니다. 이미 발급된 토큰은 만료될 때까지 기존 역할을 그대로 유지합니다. Azure CLI에서는 az logout과 az login을 실행하면 새 토큰을 즉시 받을 수 있습니다.
문제 해결
토큰이 거부되고 발급자가 https://sts.windows.net으로 시작하는 경우
토큰이 거부되고 발급자가 https://sts.windows.net으로 시작하는 경우
Entra ID가 v1.0 토큰을 발급한 것입니다. v2.0 액세스 토큰 요청에 설명된 대로 애플리케이션 매니페스트에서
requestedAccessTokenVersion을 2로 설정한 후 새 토큰을 요청하십시오.대상(audience) 불일치로 토큰이 거부되는 경우
대상(audience) 불일치로 토큰이 거부되는 경우
- ClickHouse Cloud에 구성한 provider의 Audience는
api://<CLIENT_ID>가 아니라 클라이언트 ID여야 합니다. - ClickHouse 애플리케이션용 토큰을 요청했는지 확인하십시오.
--resource를 지정하지 않으면az account get-access-token은 Azure Resource Manager용 토큰을 반환합니다.
Entra ID가 AADSTS65001을 반환하거나 동의를 요청하는 경우
Entra ID가 AADSTS65001을 반환하거나 동의를 요청하는 경우
클라이언트 애플리케이션이
access_as_application 범위에 대해 사전 승인되지 않았습니다. 사용자 로그인을 위한 클라이언트 애플리케이션 승인에 설명된 대로 Expose an API → Authorized client applications에 해당 클라이언트 ID를 추가하십시오.Entra ID가 AADSTS50105 또는 AADSTS501051을 반환하는 경우
Entra ID가 AADSTS50105 또는 AADSTS501051을 반환하는 경우
사용자 또는 애플리케이션이 ClickHouse 애플리케이션에 할당되지 않은 상태에서 Assignment required?가 Yes로 설정되어 있습니다. 사용자, 사용자가 속한 그룹 중 하나 또는 애플리케이션을 앱 역할에 할당하십시오. 그룹을 할당한 경우 사용자가 해당 그룹의 직접 멤버인지 확인하십시오.
인증은 성공하지만 쿼리가 ACCESS_DENIED로 실패하는 경우
인증은 성공하지만 쿼리가 ACCESS_DENIED로 실패하는 경우
임시 사용자에게 쿼리 실행에 필요한 권한이 없습니다. 다음 사항을 확인하십시오.
- provider의 Roles claim이
roles로 설정되어 있는지 확인합니다. - 토큰에
roles클레임이 포함되어 있는지 확인합니다. 호출자가 앱 역할 없이 애플리케이션에 할당되면 이 클레임이 누락됩니다. roles클레임의 각 값이 서비스에 존재하는 ClickHouse 역할과 대소문자까지 정확히 일치하는지 확인합니다.- 역할에 부여한 권한을
default사용자가 가지고 있는지 확인합니다.
클레임 매핑 정책을 구성한 후 토큰이 거부되는 경우
클레임 매핑 정책을 구성한 후 토큰이 거부되는 경우
애플리케이션에 클레임 매핑 정책이나 사용자 정의 서명 키를 구성하면 Entra ID는 테넌트의 JWKS에 없는 키로 토큰에 서명합니다. provider의 JWKS URL을
https://login.microsoftonline.com/<TENANT_ID>/discovery/v2.0/keys?appid=<CLIENT_ID>로 설정하십시오.