Athenz 인증

Athenz 인증 (Authentication using Athenz)

Athenz는 역할 기반 인증/권한 부여 시스템이에요. Pulsar에서는 Athenz 역할 토큰(z-token이라고도 함)으로 클라이언트의 신원을 확인할 수 있어요. 이번에는 Pulsar에서 Athenz 인증을 설정하는 방법을 함께 살펴볼게요.

출처: 문서

본문

분산형 Athenz 시스템은 ZMS(Authorization Management System) 서버와 ZTS(Authorization Token System) 서버를 포함해요.

사전 준비 (Prerequisites)

시작하려면 provider(일부 인증/권한 부여 정책으로 다른 서비스에 일부 리소스를 제공)와 tenant(provider의 일부 리소스에 접근하도록 프로비저닝됨)를 위한 도메인을 만들어 Athenz 서비스 접근 제어를 설정해야 해요. 이 경우 provider는 Pulsar 서비스 자체에 해당하고, tenant는 Pulsar를 사용하는 각 애플리케이션(보통 Pulsar의 tenant)에 해당해요.

테넌트 도메인과 서비스 만들기 (Create a tenant domain and service)

테넌트 측에서 다음을 수행해요.

1. shopping 같은 도메인을 만들어요.
2. 개인/공개 키 쌍을 생성해요.
3. 공개 키로 도메인에 some_app 같은 서비스를 만들어요.

Pulsar 클라이언트가 브로커에 연결할 때 2단계에서 생성한 개인 키를 지정해야 한다는 점에 주의해요.

Athenz UI를 포함한 더 구체적인 단계는 Example Service Access Control Setup을 참고해요.

provider 도메인 만들기와 역할 멤버에 테넌트 서비스 추가 (Create a provider domain and add the tenant service to role members)

provider 측에서 다음을 해야 해요.

1. pulsar 같은 도메인을 만들어요.
2. 역할(role)을 만들어요.
3. 역할의 멤버에 테넌트 서비스를 추가해요.

2단계에서 action과 resource는 Pulsar에서 사용되지 않으므로 아무 값이나 지정할 수 있다는 점에 주의해요. 다시 말해 Pulsar는 Athenz 역할 토큰을 권한 부여가 아닌 인증에만 사용해요.

Athenz UI를 포함한 더 구체적인 단계는 Example Service Access Control Setup을 참고해요.

브로커/프록시에서 Athenz 인증 활성화 (Enable Athenz authentication on brokers/proxies)

브로커/프록시가 Athenz로 클라이언트를 인증하도록 구성하려면 conf/broker.conf와 conf/proxy.conf 파일에 다음 파라미터를 추가하고, Athenz 인증 제공자 클래스 이름과 쉼표로 구분된 provider 도메인 이름 목록을 제공해요. standalone Pulsar를 사용한다면 conf/standalone.conf 파일에 이 파라미터를 추가해야 해요.

# Add the Athenz auth provider
authenticationEnabled=true
authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderAthenz
athenzDomainNames=pulsar
# Authentication settings of the broker itself. Used when the broker connects to other brokers, or when the proxy connects to brokers, either in same or other clusters
brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationAthenz
brokerClientAuthenticationParameters={"tenantDomain":"shopping","tenantService":"some_app","providerDomain":"pulsar","privateKey":"file:///path/to/private.pem","keyId":"v1"}

Pulsar 클라이언트에서 Athenz 인증 구성 (Configure Athenz authentication in Pulsar clients)

Athenz를 인증 제공자로 사용하려면 해시에 네 개 파라미터의 값을 제공해야 해요.

• tenantDomain
• tenantService
• providerDomain
• privateKey

tip privateKey 파라미터는 다음 세 가지 패턴 형식을 지원해요.

• file:///path/to/file
• file:/path/to/file
• data:application/x-pem-file;base64,<base64-encoded value>

선택적인 keyId도 설정할 수 있어요. 다음은 예시예요.

• Java
• Python
• C++
• Node.js
• Go

Java:

Map<String, String> authParams = new HashMap();
authParams.put("ztsUrl", "http://localhost:9998");
// authParams.put("ztsProxyUrl", "http://localhost:9999"); // Proxy for accessing ZTS (optional, since v3.0.10/v4.0.3/v4.1.0)
authParams.put("tenantDomain", "shopping"); // Tenant domain name
authParams.put("tenantService", "some_app"); // Tenant service name
authParams.put("providerDomain", "pulsar"); // Provider domain name
authParams.put("privateKey", "file:///path/to/private.pem"); // Tenant private key path
authParams.put("keyId", "v1"); // Key id for the tenant private key (optional, default: "0")
Authentication athenzAuth = AuthenticationFactory
        .create(AuthenticationAthenz.class.getName(), authParams);
PulsarClient client = PulsarClient.builder()
        .serviceUrl("pulsar://my-broker.com:6650")
        .authentication(athenzAuth)
        .build();

Python:

authPlugin = "athenz"
authParams = """
{"tenantDomain": "shopping","tenantService": "some_app","providerDomain": "pulsar","privateKey": "file:///path/to/private.pem","ztsUrl": "http://localhost:9998"}
"""
client = Client(
    "pulsar://my-broker.com:6650",
    authentication=Authentication(authPlugin, authParams),
)

C++:

std::string params = R"({
        "tenantDomain": "shopping",
        "tenantService": "some_app",
        "providerDomain": "pulsar",
        "privateKey": "file:///path/to/private.pem",
        "ztsUrl": "http://localhost:9998"
    })";
pulsar::AuthenticationPtr auth = pulsar::AuthAthenz::create(params);
ClientConfiguration config = ClientConfiguration();
config.setAuth(auth);
Client client("pulsar://my-broker.com:6650", config);

Node.js:

const auth = new Pulsar.AuthenticationAthenz({
    tenantDomain: "shopping",
    tenantService: "some_app",
    providerDomain: "pulsar",
    privateKey: "file:///path/to/private.pem",
    ztsUrl: "http://localhost:9998"
});
const client = new Pulsar.Client({
    serviceUrl: 'pulsar://my-broker.com:6650',
    authentication: auth
});

Go:

provider := pulsar.NewAuthenticationAthenz(map[string]string{
	"ztsUrl":         "http://localhost:9998",
	// "ztsProxyUrl":    "http://localhost:9999", // Proxy for accessing ZTS (optional, since v0.16.0)
	"providerDomain": "pulsar",
	"tenantDomain":   "shopping",
	"tenantService":  "some_app",
	"privateKey":     "file:///path/to/private.pem",
	"keyId":          "v1",
})
client, err := pulsar.NewClient(pulsar.ClientOptions{
	URL:            "pulsar://my-broker.com:6650",
	Authentication: provider,
})

Copper Argos 사용 (Use Copper Argos)

Athenz에는 Copper Argos라는 메커니즘이 있어요. ZTS가 각 서비스에 X.509 인증서와 개인 키 쌍을 배포하고, 서비스가 이를 사용해 조직 내 다른 서비스에 자신을 식별할 수 있게 해요.

Copper Argos를 사용할 때는 최소 다음 네 파라미터를 제공해야 해요.

• providerDomain
• x509CertChain
• privateKey
• caCert

이 경우 tenantDomain, tenantService, keyId는 무시돼요.

• Java
• Python
• C++
• Node.js
• Go

Java:

Map<String, String> authParams = new HashMap();
authParams.put("ztsUrl", "http://localhost:9998");
// authParams.put("ztsProxyUrl", "http://localhost:9999"); // Proxy for accessing ZTS (optional, since v3.0.10/v4.0.3/v4.1.0)
authParams.put("providerDomain", "pulsar"); // Provider domain name
authParams.put("x509CertChain", "file:///path/to/x509cert.pem"); // Distributed X.509 certificate path
authParams.put("privateKey", "file:///path/to/private.pem"); // Distributed private key path
authParams.put("caCert", "file:///path/to/cacert.pem"); // CA certificate path
Authentication athenzAuth = AuthenticationFactory
        .create(AuthenticationAthenz.class.getName(), authParams);
PulsarClient client = PulsarClient.builder()
        .serviceUrl("pulsar://my-broker.com:6650")
        .authentication(athenzAuth)
        .build();

Python:

authPlugin = "athenz"
authParams = """
{"ztsUrl": "http://localhost:9998","providerDomain": "pulsar","x509CertChain": "file:///path/to/x509cert.pem","privateKey": "file:///path/to/private.pem","caCert": "file:///path/to/cacert.pem"}
"""
client = Client(
    "pulsar://my-broker.com:6650",
    authentication=Authentication(authPlugin, authParams),
)

C++:

std::string params = R"({
        "ztsUrl": "http://localhost:9998",
        "providerDomain": "pulsar",
        "x509CertChain": "file:///path/to/x509cert.pem",
        "privateKey": "file:///path/to/private.pem",
        "caCert": "file:///path/to/cacert.pem"
    })";
pulsar::AuthenticationPtr auth = pulsar::AuthAthenz::create(params);
ClientConfiguration config = ClientConfiguration();
config.setAuth(auth);
Client client("pulsar://my-broker.com:6650", config);

Node.js:

const auth = new Pulsar.AuthenticationAthenz({
    ztsUrl: "http://localhost:9998",
    providerDomain: "pulsar",
    x509CertChain: "file:///path/to/x509cert.pem",
    privateKey: "file:///path/to/private.pem",
    caCert: "file:///path/to/cacert.pem"
});
const client = new Pulsar.Client({
    serviceUrl: 'pulsar://my-broker.com:6650',
    authentication: auth
});

Go:

provider := pulsar.NewAuthenticationAthenz(map[string]string{
	"ztsUrl":         "http://localhost:9998",
	// "ztsProxyUrl":    "http://localhost:9999", // Proxy for accessing ZTS (optional, since v0.16.0)
	"providerDomain": "pulsar",
	"x509CertChain":  "file:///path/to/x509cert.pem",
	"privateKey":     "file:///path/to/private.pem",
	"caCert":         "file:///path/to/cacert.pem",
})
client, err := pulsar.NewClient(pulsar.ClientOptions{
	URL:            "pulsar://my-broker.com:6650",
	Authentication: provider,
})

CLI 도구에서 Athenz 인증 구성 (Configure Athenz authentication in CLI tools)

pulsar-admin, pulsar-perf, pulsar-client 같은 커맨드라인 도구는 Pulsar 설치의 conf/client.conf 구성 파일을 사용해요.

Pulsar의 CLI 도구와 Athenz를 사용하려면 conf/client.conf 구성 파일에 다음 인증 파라미터를 추가해야 해요.

# URL for the broker
serviceUrl=http://broker.example.com:8080
# Set Athenz auth plugin and its parameters
authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationAthenz
authParams={"tenantDomain":"shopping","tenantService":"some_app","providerDomain":"pulsar","privateKey":"file:///path/to/private.pem","keyId":"v1"}

더 알아보기 (Learn more)

• 인증의 기본 개념은 Security overview 문서에서 확인해요.
• 권한 부여 설정은 Authorization 문서를 참고해요.
• CLI 도구 종류는 CLI tools 문서를 살펴봐요.
• 안전한 전송을 위한 TLS transport 문서를 봐요.