JWT 인증 메서드

JWT 인증 메서드 (JWT Auth Method)

JWT 인증 메서드는 JWT를 직접 제공해 Consul로 인증하는 데 사용할 수 있어요. JWT는 로컬 제공 키로 암호화 검증되거나, 구성된 경우 OIDC Discovery 서비스를 사용해 적절한 키를 가져올 수 있어요. 이 문서에서 구성 매개변수, 검증 방식, 클레임 매핑을 설명할게요.

출처: 문서

본문

1.8.0+: 이 기능은 Consul 버전 1.8.0 이상에서 사용할 수 있습니다.

jwt 인증 메서드는 JWT를 직접 제공해 Consul로 인증하는 데 사용할 수 있습니다. JWT는 로컬에서 제공된 키를 사용해 암호화 검증되거나, 구성된 경우 OIDC Discovery 서비스를 사용해 적절한 키를 가져올 수 있습니다.

이 페이지는 JWT와 기본 auth method 문서에 설명된 개념에 대한 일반적인 지식을 가정합니다.

jwt와 oidc 인증 메서드 유형 모두 JWT의 클레임 데이터에 대한 추가 처리를 허용합니다.

JWT vs OIDC 인증 메서드 (JWT vs OIDC Auth Methods)

oidc와 jwt 인증 메서드 모두 궁극적으로 bearer 토큰으로서 JWT에서 동작하므로 주어진 사용 사례에 어떤 것이 맞는지 혼동할 수 있습니다.

  • JWT: Consul 로그인을 수행하는 사용자 또는 애플리케이션은 시작할 때 이미 유효한 JWT를 소유하고 있어야 합니다. 브라우저 상호작용이 필요하지 않습니다. 이는 운영자가 유효한 JWT를 VM에 놓아 두거나 컨테이너에 제공하도록 이미 마련한 기계 중심의 헤드리스(headless) 로그인에 이상적입니다.
  • OIDC: Consul 로그인을 수행하는 사용자는 JWT를 가지지 않으며 그것이 무엇을 의미하는지 알 필요조차 없습니다. 이는 운영자나 관리자가 SSO를 널리 배포했고 권한 있는 동료에게 Consul 인스턴스에 접근해야 할 때마다 Consul ACL 토큰을 추적·배포하는 부담을 원하지 않는 인간 중심의 대화형 로그인에 이상적입니다. 브라우저 상호작용이 필요합니다. 이것은 Consul Enterprise에서만 사용할 수 있습니다.

구성 매개변수 (Config Parameters)

jwt 유형의 인증 메서드를 제대로 구성하려면 다음 auth method Config 매개변수가 필요합니다:

  • JWTValidationPubKeys (array<string>) - 서명을 로컬로 인증하는 데 사용할 PEM 인코딩 공개 키 목록. JWKSURL, JWTValidationPubKeys, OIDCDiscoveryURL 중 정확히 하나가 필요합니다.
  • OIDCDiscoveryURL (string: "") - .well-known 구성 요소가 없는 OIDC Discovery URL(기본 경로). JWKSURL, JWTValidationPubKeys, OIDCDiscoveryURL 중 정확히 하나가 필요합니다.
  • OIDCDiscoveryCACert (string: "") - OIDC Discovery URL과 통신하는 데 사용되는 TLS 클라이언트용 PEM 인코딩 CA 인증서. 참고: 모든 줄은 개행(\n)으로 끝나야 합니다. 설정하지 않으면 시스템 인증서가 사용됩니다.
  • JWKSURL (string: "") - 서명을 인증하는 데 사용할 JWKS URL. JWKSURL, JWTValidationPubKeys, OIDCDiscoveryURL 중 정확히 하나가 필요합니다.
  • JWKSCACert (string: "") - JWKS URL과 통신하는 데 사용되는 TLS 클라이언트용 PEM 인코딩 CA 인증서. 참고: 모든 줄은 개행(\n)으로 끝나야 합니다. 설정하지 않으면 시스템 인증서가 사용됩니다.
  • ClaimMappings (map[string]string) - 메타데이터 필드로 복사될 클레임(키)의 매핑. 캡처하는 클레임이 단수(예: 속성)인 경우 이를 사용합니다. 매핑되면 값은 number, string, boolean 중 하나일 수 있으며 반환될 때 모두 문자열화됩니다.
  • ListClaimMappings (map[string]string) - 메타데이터 필드로 복사될 클레임(키)의 매핑. 캡처하는 클레임이 목록형(예: groups)인 경우 이를 사용합니다. 매핑되면 각 목록의 값은 number, string, boolean 중 하나일 수 있으며 반환될 때 모두 문자열화됩니다.
  • JWTSupportedAlgs (array<string>) - 지원되는 서명 알고리즘 목록. 기본값은 RS256입니다.
  • BoundAudiences (array<string>) - 로그인에 유효한 aud 클레임 목록. 아무 것이나 일치하면 충분합니다.
  • BoundIssuer (string: "") - JWT의 iss 클레임을 일치시킬 값.
  • ExpirationLeeway (duration: 0s) - 클록 스큐(skew)를 고려해 토큰 만료를 검증할 때의 여유 시간(초). 0으로 설정하면 기본값 150(2.5분)이고 -1로 설정하면 비활성화할 수 있습니다.
  • NotBeforeLeeway (duration: 0s) - 클록 스큐를 고려해 토큰의 not before 값을 검증할 때의 여유 시간(초). 0으로 설정하면 기본값 150(2.5분)이고 -1로 설정하면 비활성화할 수 있습니다.
  • ClockSkewLeeway (duration: 0s) - 클록 스큐를 고려해 모든 클레임을 검증할 때의 여유 시간(초). 0으로 설정하면 기본값 60(1분)이고 -1로 설정하면 비활성화할 수 있습니다.

샘플 구성 (Sample Configs)

정적 키 (Static Keys)

{
    "Name": "example-jwt-auth-static-keys",
    "Type": "jwt",
    "Description": "Example JWT auth method with static keys",
    "Config": {
        "BoundIssuer": "corp-issuer",
        "JWTValidationPubKeys": [
            "<public key PEM>"
        ],
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}

JWKS

{
    "Name": "example-jwt-auth-jwks",
    "Type": "jwt",
    "Description": "Example JWT auth method with JWKS",
    "Config": {
        "JWKSURL": "https://my-corp-jwks-url.example.com/",
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}

OIDC Discovery

{
    "Name": "example-oidc-auth",
    "Type": "oidc",
    "Description": "Example OIDC auth method",
    "Config": {
        "BoundAudiences": [
            "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
        ],
        "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}

JWT 검증 (JWT Verification)

JWT 서명은 발급자의 공개 키로 검증됩니다. 이 과정은 세 가지 방법 중 하나로 수행할 수 있습니다:

  • 정적 키 (Static Keys) - 구성에 공개 키 집합을 직접 저장합니다.
  • JWKS - JSON Web Key Set (JWKS) URL(및 선택적 인증서 체인)을 구성합니다. 인증 중 이 엔드포인트에서 키가 가져와집니다.
  • OIDC Discovery - OIDC Discovery URL(및 선택적 인증서 체인)을 구성합니다. 인증 중 이 URL에서 키가 가져와집니다. OIDC Discovery를 사용하면 OIDC 검증 기준(예: iss, aud 등)이 적용됩니다.

여러 방법이 필요하면 이 유형의 다른 인증 메서드를 다른 이름으로 만들 수 있습니다.

클레임 매핑을 통한 신뢰된 아이덴티티 속성 (Trusted Identity Attributes via Claim Mappings)

JWT 클레임의 데이터는 신뢰된 아이덴티티 속성으로 인증 단계에서 반환되어 바인딩 규칙 선택기와 바인드 이름 보간에 사용할 수 있습니다.

어떤 클레임이 어떤 아이덴티티 속성에 매핑되는지는 ClaimMappings와 ListClaimMappings가 제어합니다. 둘 다 "<JWT claim>":"<attribute suffix>" 형식의 요소를 복사하는 맵입니다.

이 두 매핑 유형의 유일한 차이는 ClaimMappings가 단수 값(이름, 부서, 팀 같은)을 매핑하는 데 사용되고 ListClaimMappings가 값 목록을 매핑하는 데 사용된다는 것입니다.

ClaimMappings가 매핑하는 단수 값을 바인딩 규칙에서 보간할 수 있으며, ListClaimMappings가 매핑하는 값 목록은 보간할 수 없습니다.

다음이 여러분의 구성 스니펫이라고 가정합니다:

{
  "Name": "example-auth-method",
  "Type": "<jwt|oidc>",
  "Description": "Example auth method",
  "Config": {
    "ClaimMappings": {
      "givenName": "first_name",
      "surname": "last_name"
    },
    "ListClaimMappings": {
      "groups": "groups"
    }
  }
}

이는 JWT 클레임 "givenName"과 "surname"의 값이 각각 "value.first_name"과 "value.last_name"이라는 속성에 복사되어야 함을 지정합니다. 또한 JWT 클레임 "groups"의 값 목록이 "list.groups"라는 속성에 복사되어야 합니다.

다음 표는 추출될 결과 속성과 규칙 바인딩(Rule Bindings)에서 사용할 수 있는 방법을 보여줍니다:

| 속성 (Attributes) | 지원되는 선택기 연산 (Supported Selector Operations) | 보간 가능 (Can be Interpolated) | | value.first_name | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | | value.last_name | Equal, Not Equal, In, Not In, Matches, Not Matches | yes | | list.groups | In, Not In, Is Empty, Is Not Empty | no |

클레임 사양과 JSON Pointer (Claim Specifications and JSON Pointer)

ClaimMappings와 ListClaimMappings 필드는 JWT 내부의 데이터를 가리키는 데 사용됩니다. 원하는 키가 JWT의 최상위 수준에 있으면 이름을 직접 제공할 수 있습니다. 더 낮은 수준에 중첩되어 있으면 JSON Pointer를 사용할 수 있습니다.

다음 JWT 클레임이 디코딩되었다고 가정합니다:

{
  "division": "North America",
  "groups": {
    "primary": "Engineering",
    "secondary": "Software"
  },
  "iss": "https://my-corp-app-name.auth0.com/",
  "sub": "auth0|eiw7OWoh5ieSh7ieyahC3ief0uyuraphaengae9d",
  "aud": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
  "iat": 1589224148,
  "exp": 1589260148,
  "nonce": "eKiihooH3Fah8Ieshah4leeti6ien3"
}

"division" 매개변수는 최상위 키이므로 "North America"를 참조합니다. /groups/primary 매개변수는 JSON Pointer 구문을 사용해 더 낮은 수준의 "Engineering"을 참조합니다. 모든 유효한 JSON Pointer를 선택기로 사용할 수 있습니다. 구문의 전체 설명은 JSON Pointer RFC를 참조하세요.

더 알아보기 (Learn more)