토큰 인증 관리

토큰 인증 관리 (Token authentication admin)

Pulsar는 JSON Web Tokens (RFC-7519) 기반 보안 토큰으로 클라이언트를 인증하는 것을 지원해요. 이번에는 관리자 관점에서 토큰 인증을 설정하고 권한을 부여하는 방법을 정리해 볼게요.

출처: 문서

본문

토큰 인증 개요 (Token Authentication Overview)

토큰은 Pulsar 클라이언트를 식별하고 어떤 "주체(principal)"(또는 "역할(role)")과 연결하는 데 사용되며, 그 주체는 특정 작업(예: 토픽에서 게시·소비)을 할 권한을 부여받아요.

사용자는 보통 관리자(또는 자동화 서비스)로부터 토큰 문자열을 받아요.

서명된 JWT의 압축 표현은 다음과 같은 문자열이에요.

eyJhbG...62SY

애플리케이션은 클라이언트 인스턴스를 만들 때 토큰을 지정해요. 대안으로 "토큰 공급자(token supplier)", 즉 클라이언트 라이브러리가 토큰이 필요할 때 반환하는 함수를 전달할 수도 있어요.

항상 TLS 전송 암호화를 사용하세요 (Always use TLS transport encryption)

토큰을 보내는 것은 유선상으로 비밀번호를 보내는 것과 같아요. Pulsar 서비스와 통신할 때는 항상 TLS 암호화를 사용하는 것을 강력히 권장해요. TLS를 사용한 전송 암호화 문서를 참고해요.

비밀 키 vs 공개/개인 키 (Secret vs Public/Private keys)

JWT는 토큰을 생성·검증하기 위해 두 종류의 키를 지원해요.

  • 대칭(Symmetric):
    • 토큰 생성과 검증에 모두 사용되는 단일 Secret 키가 있어요
  • 비대칭(Asymmetric): 키 쌍이 있어요.
    • Private 키는 토큰을 생성하는 데 사용
    • Public 키는 토큰을 검증하는 데 사용

비밀 키 (Secret key)

비밀 키를 사용할 때 관리자가 키를 만들고 이를 사용해 클라이언트 토큰을 생성해요. 이 키는 브로커에도 구성되어 클라이언트를 검증할 수 있게 해요.

비밀 키 생성 (Creating a secret key)

출력 파일은 pulsar 설치 디렉터리의 루트에 생성돼요. 출력 파일의 절대 경로도 제공할 수 있어요.

bin/pulsar tokens create-secret-key --output my-secret.key

base64로 인코딩된 개인 키를 생성하려면

bin/pulsar tokens create-secret-key --output  /opt/my-secret.key --base64

공개/개인 키 (Public/Private keys)

공개/개인 방식을 사용하려면 키 쌍을 만들어야 해요. Pulsar는 여기에 나와 있는 Java JWT 라이브러리가 지원하는 모든 알고리즘을 지원해요.

키 쌍 생성 (Creating a key pair)

출력 파일은 pulsar 설치 디렉터리의 루트에 생성돼요. 출력 파일의 절대 경로도 제공할 수 있어요.

bin/pulsar tokens create-key-pair --output-private-key my-private.key --output-public-key my-public.key
  • my-private.key는 안전한 위치에 저장되고 관리자만 새 토큰을 생성하는 데 사용해요.
  • my-public.key는 모든 Pulsar 브로커에 배포돼요. 이 파일은 보안 우려 없이 공개적으로 공유할 수 있어요.

토큰 생성 (Generating tokens)

토큰은 사용자와 연결된 자격 증명이에요. 연결은 "주체" 또는 "역할"을 통해 이루어져요. JWT 토큰의 경우 이 필드는 보통 subject라고 불리지만 정확히 같은 개념이에요.

생성된 토큰은 subject 필드를 가져야 해요.

bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \
         --subject test-user

이 명령은 토큰 문자열을 stdout에 출력해요.

유사하게 "private" 키를 전달해 토큰을 만들 수도 있어요.

bin/pulsar tokens create --private-key file:///path/to/my-private.key \
         --subject test-user

마지막으로 사전 정의된 TTL로 토큰을 만들 수도 있어요. 그 시간이 지나면 토큰이 자동으로 무효화돼요.

bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \
         --subject test-user \
         --expiry-time 1y

권한 부여 (Authorization)

토큰 자체에는 연결된 권한이 없어요. 그것은 권한 부여 엔진이 결정해요. 토큰이 생성되면 이 토큰에 특정 작업을 할 권한을 부여할 수 있어요. 예:

bin/pulsar-admin namespaces grant-permission my-tenant/my-namespace \
         --role test-user \
         --actions produce,consume

토큰 인증 활성화 (Enabling Token Authentication ...)

... 브로커에서 (... on Brokers)

브로커가 클라이언트를 인증하도록 구성하려면 broker.conf에 다음을 넣어요.

# Configuration to enable authentication and authorization
authenticationEnabled=true
authorizationEnabled=true
authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
# If using secret key (Note: key files must be DER-encoded)
tokenSecretKey=file:///path/to/secret.key
# The key can also be passed inline:
# tokenSecretKey=data:;base64,FLFyW0oLJ2Fi22KKCm21J18mbAdztfSHN/lAT5ucEKU=
# If using public/private (Note: key files must be DER-encoded)
# tokenPublicKey=file:///path/to/public.key

... 프록시에서 (... on Proxies)

프록시가 클라이언트를 인증하도록 구성하려면 proxy.conf에 다음을 넣어요.

프록시는 브로커와 통신할 때 자신의 토큰을 가지게 돼요. 이 키 쌍의 역할 토큰은 브로커의 proxyRoles에 구성해야 해요. 자세한 내용은 권한 부여 가이드를 참고해요.

# For clients connecting to the proxy
authenticationEnabled=true
authorizationEnabled=true
authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
tokenSecretKey=file:///path/to/secret.key
# For the proxy to connect to brokers
brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
brokerClientAuthenticationParameters={"token":"eyJhbG...SxXw"}
# Or, alternatively, read token from file
# brokerClientAuthenticationParameters=file:///path/to/proxy-token.txt

더 알아보기 (Learn more)