OIDC ACL 인증 메서드

OIDC ACL 인증 메서드

oidc 인증 메서드는 OIDC를 사용해 Consul과 인증하는 데 사용할 수 있어요. 이 메서드는 사용자의 웹 브라우저를 사용해 구성된 OIDC 공급자를 통한 인증을 가능하게 하며, Consul UI 또는 명령줄에서 시작할 수 있어요. Enterprise 전용 기능이에요.

출처: 문서

본문

Enterprise

이 기능은 자체 관리 Consul Enterprise 1.8.0+ 버전이 필요합니다. 추가 정보는 enterprise feature matrix를 참조하세요.

oidc 인증 메서드는 OIDC를 사용해 Consul과 인증하는 데 사용할 수 있습니다. 이 메서드는 사용자의 웹 브라우저를 사용해 구성된 OIDC 공급자를 통한 인증을 가능하게 합니다. 이 메서드는 Consul UI 또는 명령줄에서 시작할 수 있습니다.

이 페이지는 OIDC 개념과 주요 auth method documentation에 설명된 개념에 대한 일반적인 지식을 가정합니다.

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

JWT vs OIDC 인증 메서드

oidc와 jwt 인증 메서드 모두 궁극적으로 JWT를 bearer 토큰으로 처리하므로 어떤 것이 주어진 사용 사례에 적합한지 혼란스러울 수 있습니다.

  • JWT: Consul 로그인을 수행하는 사용자 또는 애플리케이션은 시작하기 전에 유효한 JWT를 이미 소유하고 있어야 합니다. 브라우저 상호작용이 필요하지 않습니다. 이는 운영자가 이미 VM에 JWT를 떨어뜨리거나 컨테이너에 제공하도록 준비한 머신 중심의 헤드리스 로그인에 이상적입니다.
  • OIDC: Consul 로그인을 수행하는 사용자는 JWT가 없으며 그 의미를 알 필요조차 없습니다. 이는 운영자나 관리자가 SSO를 널리 배포했고 Consul 인스턴스에 액세스해야 할 수 있는 승인된 동료에게 Consul ACL 토큰을 추적하고 배포하는 부담을 원하지 않는 인간 중심의 대화형 로그인에 이상적입니다. 브라우저 상호작용이 필요합니다. 이것은 Consul Enterprise에서만 사용할 수 있습니다.

구성 매개변수 (Config parameters)

oidc 유형의 인증 메서드를 올바르게 구성하려면 다음 auth method Config 매개변수가 필요합니다.

  • OIDCDiscoveryURL (string: <required>) - .well-known 구성 요소(기본 경로)가 없는 OIDC Discovery URL.
  • OIDCDiscoveryCACert (string: "") - OIDC Discovery URL과 통신하는 데 사용되는 TLS 클라이언트가 사용하는 PEM 인코딩 CA 인증서. 참고: 모든 줄은 줄바꿈(\n)으로 끝나야 합니다. 설정하지 않으면 시스템 인증서가 사용됩니다.
  • OIDCClientID (string: <required>) - OIDC 공급자에 구성된 OAuth Client ID.
  • OIDCClientSecret (string: <required>) - OIDC 공급자에 구성된 OAuth Client Secret.
  • OIDCClientAssertion (OIDCClientAssertion) - 서명된 JWT를 클라이언트 어서션으로 OIDC 공급자에 보냅니다. 이는 OIDC 클라이언트에 대한 "private key JWT" 인증을 활성화합니다. 이 필드는 선택 사항입니다. OIDCClientSecret 또는 OIDCClientAssertion 중 하나만 설정할 수 있으며, 두 필드를 모두 설정하면 구성 오류가 발생합니다. 클라이언트 어서션용 JWT는 RS256 알고리즘으로 서명됩니다.
    • Audience (array<string>) - 어서션을 처리하는 URL. 기본값은 부모 ACLAuthMethodConfig의 OIDCDiscoveryURL입니다.
    • PrivateKey (OIDCClientAssertionKey) - JWT 서명에 사용할 외부 키 자료.
    • PemKey (string) - JWT 서명에 사용할 pem 형식의 RSA 개인 키.
  • OIDCClientUsePKCE (bool: true) - OIDC 인증 흐름에서 Proof Key for Code Exchange (PKCE)를 활성화합니다. 기본값은 true입니다. PKCE는 인가 코드 가로채기 공격으로부터 보호하도록 설계된 OAuth 2.0 인가 코드 그랜트의 추가 보안 메커니즘입니다. 활성화되면 Consul은 OIDC 로그인에 PKCE를 사용하며, 이는 모든 퍼블릭 클라이언트와 브라우저 기반 인증에 권장됩니다. OIDC 공급자가 PKCE를 지원하지 않는 경우가 아니면 PKCE를 권장합니다.
  • AllowedRedirectURIs (array<string>) - redirect_uri의 허용 값 목록. 비어 있으면 안 됩니다.
  • ClaimMappings (map[string]string) - 메타데이터 필드로 복사될 클레임(key)의 매핑. 캡처하는 클레임이 속성 같은 단일 값이면 이를 사용하세요. 매핑되면 값은 숫자, 문자열 또는 불리언 중 하나일 수 있으며 반환 시 모두 문자열화됩니다.
  • ListClaimMappings (map[string]string) - 메타데이터 필드로 복사될 클레임(key)의 매핑. 캡처하는 클레임이 그룹 같은 목록 형태이면 이를 사용하세요. 매핑되면 각 목록의 값은 숫자, 문자열 또는 불리언 중 하나일 수 있으며 반환 시 모두 문자열화됩니다.
  • OIDCScopes (array<string>) - OIDC 스코프 목록.
  • OIDCACRValues (array<string>) - 인증 요청에 사용할 Authentication Context Class Reference 값 목록. 이 매개변수에 대한 자세한 내용은 OIDC reference를 참조하세요. v1.11.0에서 추가되었습니다.
  • JWTSupportedAlgs (array<string>) - JWTSupportedAlgs는 지원되는 서명 알고리즘 목록입니다. 기본값은 RS256입니다. (Available algorithms)
  • BoundAudiences (array<string>) - 로그인에 유효한 aud 클레임 목록; 어떤 것이든 일치하면 충분합니다.
  • VerboseOIDCLogging (bool: false) - 디버그 수준 로깅이 활성화되면 수신된 OIDC 토큰과 클레임을 기록합니다. OIDC 응답에 민감한 정보가 있을 수 있으므로 프로덕션에서는 권장되지 않습니다.

클라이언트 시크릿이 있는 예시 구성

{
    "Name": "example-oidc-auth",
    "Type": "oidc",
    "Description": "Example OIDC auth method",
    "Config": {
        "AllowedRedirectURIs": [
            "http://localhost:8550/oidc/callback",
            "http://localhost:8500/ui/oidc/callback"
        ],
        "BoundAudiences": [
            "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
        ],
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://consul.com/groups": "groups"
        },
        "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
        "OIDCClientSecret": "...(omitted)...",
        "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/"
    }
}

JWT를 클라이언트 어서션으로 사용하는 예시 구성

다음 예시는 RSA 개인 키로 서명된 JWT를 OIDC 공급자에게 보내는 클라이언트 어서션으로 설정하는 OIDC 인증 메서드를 활성화합니다.

{
    "Name": "example-oidc-auth",
    "Type": "oidc",
    "Description": "Example OIDC auth method",
    "Config": {
        "AllowedRedirectURIs": [
            "http://localhost:8550/oidc/callback",
            "http://localhost:8500/ui/oidc/callback"
        ],
        "BoundAudiences": [
            "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
        ],
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://consul.com/groups": "groups"
        },
        "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
        "OIDCClientAssertion": {
          "PrivateKey": {
            "PemKey": "[REDACTED PRIVATE KEY]\n"
          }
        },
        "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/"
    }
}

JWT 검증 (JWT verification)

JWT 서명은 OIDC discovery를 통해 발급자의 공개 키에 대해 검증됩니다. 키는 인증 중에 OIDC Discovery URL에서 가져오며 OIDC 검증 기준(예: iss, aud 등)이 적용됩니다.

OIDC 인증 (OIDC authentication)

Consul에는 두 가지 내장 OIDC 로그인 흐름이 있습니다. Consul UI와 consul login을 사용하는 CLI입니다.

Redirect URI

OIDC 인증 메서드 구성의 중요한 부분은 redirect URI를 올바르게 설정하는 것입니다. 이는 Consul과 OIDC 공급자 모두에서 수행해야 하며, 이러한 구성은 일치해야 합니다. redirect URI는 AllowedRedirectURIs 매개변수로 인증 메서드에 지정됩니다. Consul UI와 CLI 흐름을 구성하기 위한 redirect URI가 다르므로 설치에 따라 하나 또는 둘 다 설정해야 합니다.

Consul UI

Consul UI를 통한 로그인에는 http://localhost:8500/ui/oidc/callback 또는 https://{host:port}/ui/oidc/callback 형식의 redirect URI가 필요합니다.

"host:port"는 Consul UI를 제공하는 Consul 에이전트에 대해 올바른 값이어야 합니다.

CLI

consul login -type=oidc -method=<name>을 통한 인증을 지원하려면 localhost redirect URI를 설정해야 합니다(보통 http://localhost:8550/oidc/callback). CLI를 통한 로그인은 필요에 따라 다른 호스트 및/또는 수신 포트를 지정할 수 있으며, 이 호스트/포트가 있는 URI는 구성된 redirect URI 중 하나와 일치해야 합니다. 이러한 동일한 "localhost" URI도 공급자에 추가해야 합니다.

OIDC 로그인

Consul UI

  1. 메뉴 바 오른쪽 상단의 "Log in" 링크를 클릭합니다.
  2. 선택한 OIDC 인증 메서드에 대한 "Continue with..." 버튼 중 하나를 클릭합니다.
  3. 구성된 공급자로 인증을 완료합니다.

CLI

$ consul login -method=oidc -type=oidc -token-sink-file=consul.token

Complete the login via your OIDC provider. Launching browser to:

    https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8550%2Foidc%2Fcallback&client_id=r3qXc2bix9eF...

브라우저가 생성된 URL로 열려 공급자의 로그인을 완료합니다. 브라우저를 자동으로 열 수 없으면 URL을 수동으로 입력할 수 있습니다.

콜백 리스너는 다음 선택 매개변수로 사용자 지정할 수 있습니다. 일반적으로 설정할 필요는 없습니다.

콜백 리스너는 기본적으로 localhost:8550에서 수신합니다. 이를 사용자 지정하려면 선택 플래그 -oidc-callback-listen-addr=<host:port>을 사용하세요.

OIDC 구성 문제 해결

OIDC에 필요한 구성 양은 비교적 적지만, 왜 작동하지 않는지 디버깅하는 것은 까다로울 수 있습니다. OIDC 설정을 위한 몇 가지 팁:

  • Consul 서버의 로그 출력을 모니터링하세요. OIDC 검증 실패에 대한 중요한 정보가 출력됩니다.
  • Consul과 공급자 모두에서 Redirect URI가 올바른지 확인하세요. 정확히 일치해야 합니다. http/https, 127.0.0.1/localhost, 포트 번호, 후행 슬래시 존재 여부를 확인하세요.
  • BoundAudiences는 선택 사항이며 일반적으로 필요하지 않습니다. OIDC 공급자는 client_id를 audience로 사용하며 OIDC 검증은 이를 기대합니다.
  • 필요한 모든 정보를 받기 위해 필요한 스코프가 무엇인지 공급자를 확인하세요. "profile"과 "groups" 스코프는 종종 요청해야 하며, 인증 메서드에 OIDCScopes="profile,groups"를 설정해 추가할 수 있습니다.
  • 로그에서 클레임 관련 오류를 참조하고 있다면 공급자의 문서를 매우 신중하게 검토하여 클레임의 이름 지정과 구조 방식을 참조하세요. 공급자에 따라 검사할 수 있는 JWT를 얻기 위해 간단한 curl implicit grant 요청을 구성할 수 있습니다. JWT를 디코딩하는 예시(이 경우 JSON 응답의 access_token 필드에 있음): 
    jq --raw-output '.access_token / "." | .[1] | @base64d' jwt.json
  • 디버그 수준 로깅이 활성화되면 수신된 OIDC 토큰을 기록하는 VerboseOIDCLogging 옵션을 사용할 수 있습니다. 이는 공급자 설정을 디버깅하고 수신된 클레임이 기대한 대로인지 확인할 때 도움이 될 수 있습니다. 클레임 데이터는 그대로 기록되고 민감한 정보를 포함할 수 있으므로 이 옵션을 프로덕션에서 사용해서는 안 됩니다.

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

JWT 클레임의 데이터는 바인딩 규칙 선택자와 바인드 이름 보간에 사용하기 위한 신뢰된 ID 속성으로 인증 단계에서 반환될 수 있습니다.

어떤 클레임이 어떤 ID 속성으로 매핑되는지 제어는 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에서 사용할 수 있는 방법을 보여줍니다.

| 속성 | 지원되는 선택자 연산 | 보간 가능 | | 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

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)