Identity 토큰

Identity 토큰

Identity 정보는 Vault 전반에서 사용되지만, 다른 애플리케이션이 쓸 수 있도록 내보낼 수도 있어요. 권한이 있는 사용자/애플리케이션은 자신과 연결된 엔티티의 identity 정보를 담은 토큰을 요청할 수 있어요. 이 토큰은 OIDC ID 토큰 구조를 따르는 서명된 JWT예요.

토큰을 검증하는 데 쓰는 공개 키는 OIDC discovery와 JWKS 규약에 따라 Vault가 인증이 필요 없는(unauthenticated) 엔드포인트에 게시해요. 그래서 JWT/OIDC 라이브러리에서 바로 사용할 수 있어야 해요. Vault는 토큰 검증을 위한 introspection 엔드포인트도 제공해요.

출처: 문서

본문

역할과 키(Roles and keys)

OIDC 호환 ID 토큰은 역할(role)에 대해 생성돼요. 역할은 템플릿 시스템으로 토큰 클레임을 구성하고, 토큰 TTL을 설정하며, 토큰 서명에 사용할 "키"를 지정하는 방법을 제공해요. 역할 템플릿은 토큰 내용을 사용자 지정하는 선택적 파라미터로, 다음 섹션에서 설명할게요. 토큰 TTL은 토큰의 만료 시각을 제어하며, 이 시간이 지나면 검증 라이브러리는 토큰을 유효하지 않은 것으로 간주해요. 모든 역할에는 토큰의 aud 파라미터에 추가될 연결된 client_id가 있어요. JWT/OIDC 라이브러리는 보통 이 값을 요구해요. 이 파라미터는 운영자가 원하는 값으로 설정하거나, 설정하지 않으면 Vault가 생성한 값이 사용돼요.

역할의 key 파라미터는 역할을 기존의 명명된 키(named key)에 연결해요(여러 역할이 같은 키를 참조할 수 있어요). 서명되지 않은 ID 토큰은 생성할 수 없어요.

명명된 키는 Vault가 생성한 공개/개인 키 쌍이에요. 개인 키는 identity 토큰 서명에 사용되고, 공개 키는 클라이언트가 서명을 검증하는 데 사용돼요. 키는 정기적으로 회전하며, 새 키 쌍이 생성되고 이전 공개 키는 검증 목적으로 제한된 시간 동안 유지돼요.

명명된 키의 구성은 회전 주기(rotation period), 검증 TTL(verification ttl), 서명 알고리즘, 허용 클라이언트 ID를 지정해요. 회전 주기는 새 서명 키가 생성되는 빈도와 이전 서명 키의 개인 부분이 삭제되는 시점을 지정해요. 검증 TTL은 회전 후 공개 키가 검증 목적으로 유지되는 시간이에요. 기본적으로 키는 24시간마다 회전하고, 회전 후 24시간 동안 계속 검증에 사용할 수 있어요.

키의 허용 클라이언트 ID 목록은 어떤 역할이 그 키를 참조할 수 있는지 제한해요. *로 설정하면 모든 역할을 허용해요. 유효성 평가는 구성 시점이 아니라 토큰이 요청될 때 이뤄져요.

토큰 내용과 템플릿(Token contents and templates)

Identity 토큰은 항상 최소한 OIDC가 요구하는 클레임을 포함해요.

• iss — 발급자(issuer) URL
• sub — 요청자의 엔티티 ID
• aud — 역할의 client_id
• iat — 발급 시각
• exp — 토큰의 만료 시각

또한 운영자는 역할별 템플릿을 구성해 다양한 다른 엔티티 정보를 토큰에 추가할 수 있어요. 템플릿은 대체 가능한 파라미터가 있는 JSON으로 구성돼요. 파라미터 문법은 ACL Path Templating에서 쓰는 것과 같아요.

예를 들어:

{
  "color": {{identity.entity.metadata.color}},
  "userinfo": {
     "username": {{identity.entity.aliases.usermap_123.metadata.username}},
     "groups": {{identity.entity.groups.names}}
  },
  "nbf": {{time.now}}
}

토큰이 요청되면 결과 템플릿은 다음과 같이 채워질 수 있어요.

{
  "color": "green",
  "userinfo": {
     "username": "bob",
     "groups": ["web", "engr", "default"]
  },
  "nbf": 1561411915
}

그리고 이 값은 기본 OIDC 클레임과 병합되어 최종 토큰이 돼요.

{
  "iss": "https://10.1.1.45:8200/v1/identity/oidc",
  "sub": "a2cd63d3-5364-406f-980e-8d71bb0692f5",
  "aud": "SxSouteCYPBoaTFy94hFghmekos",
  "iat": 1561411915,
  "exp": 1561412215,
  "color": "green",
  "userinfo": {
    "username": "bob",
    "groups": ["web", "engr", "default"]
  },
  "nbf": 1561411915
}

템플릿이 병합되면서 최상위 템플릿 키가 최상위 토큰 키가 된다는 점을 눈여겨 보세요. 이런 이유로 템플릿은 표준 OIDC 클레임을 덮어쓰는 최상위 키를 포함할 수 없어요.

엔티티에 없는 템플릿 파라미터(존재하지 않는 메타데이터나 존재하지 않는 별칭 accessor 같은)는 데이터 타입에 따라 빈 문자열이나 빈 객체가 돼요.

템플릿은 역할에 구성되며 선택적으로 base64로 인코딩될 수 있어요.

전체 템플릿 파라미터 목록은 다음과 같아요.

토큰 생성(Token generation)

인증된 클라이언트는 토큰 생성 엔드포인트를 사용해 토큰을 요청할 수 있어요. 토큰은 요청된 역할의 사양에 따라 요청자의 엔티티에 대해 생성돼요. 임의의 엔티티에 대한 토큰은 생성할 수 없어요.

Vault가 생성한 ID 토큰의 진위 검증(Verifying authenticity)

Identity 토큰은 Vault가 게시한 공개 키를 사용하거나 Vault가 제공하는 introspection 엔드포인트를 통해 클라이언트 쪽에서 검증할 수 있어요.

Vault는 OIDC 검증 라이브러리와 쉽게 통합할 수 있는 표준 .well-known 엔드포인트를 제공해요. 라이브러리를 구성하려면 보통 issuer URL과 client ID를 제공하면 돼요. 그러면 라이브러리가 키 요청을 처리하고 토큰의 서명과 클레임 요구 사항을 검증할 수 있어요. 이 접근 방식의 장점은 .well-known 엔드포인트가 인증되지 않으므로 권한(authorization)이 아닌 Vault에 대한 접근만 필요하다는 점이에요.

또는 토큰을 introspection 엔드포인트를 통해 Vault에 보내 검증할 수 있어요. 응답은 토큰이 "active"인지 여부와 검증 중 발생한 오류를 알려줘요. 클라이언트가 검증을 Vault에 위임할 수 있게 하는 것에 더해, 이 엔드포인트를 사용하면 토큰만으로는 판단할 수 없는 엔티티가 여전히 활성 상태인지 여부도 함께 확인돼요. .well-known 엔드포인트와 달리 introspection 엔드포인트에 접근하려면 유효한 Vault 토큰과 충분한 권한이 필요해요.

발급자 고려 사항(Issuer considerations)

identity 토큰 시스템에는 구성 가능한 파라미터가 하나 있는데 바로 **issuer(발급자)**예요. issuer iss 클레임은 클라이언트가 토큰을 올바르게 검증하는 데 특히 중요하며, 성능 복제(performance replication)와 함께 Identity 토큰을 쓸 때는 특별히 주의해야 해요.

토큰 소비자는 issuer URL을 사용해 Vault에서 공개 키를 요청하므로 issuer는 네트워크에서 도달 가능해야 해요. 또 반환되는 키 집합에는 요청과 일치해야 하는 issuer가 포함돼요.

기본적으로 Vault는 issuer를 Vault 인스턴스의 api_addr로 설정해요. 이는 주어진 클러스터에서 발급된 토큰은 같은 클러스터 안에서 검증되어야 한다는 뜻이에요. 또는 issuer 파라미터를 명시적으로 구성할 수 있어요. 이 주소는 Vault 인스턴스의 identity/oidc 경로를 가리켜야 하며(예: https://vault-1.example.com:8200/v1/identity/oidc), identity 토큰을 검증하려는 어떤 클라이언트에서든 도달 가능해야 해요.

API

Identity 시크릿 엔진은 완전한 HTTP API를 갖고 있어요. 자세한 내용은 Identity 시크릿 엔진 API를 참고해 주세요.

더 알아보기 (Learn more)

• OIDC ID 토큰 구조를 살펴보세요.
• ACL Path Templating 문법을 확인해 보세요.
• Identity 시크릿 엔진 API 문서에서 토큰 생성·introspection 엔드포인트를 확인해 보세요.