OpenID Connect

OpenID Connect (OIDC) 인증 방법 (OpenID Connect (OIDC) Auth Method)

Enterprise 기능으로, oidc 인증 방법을 사용해 OIDC로 Consul에 인증할 수 있어요. 구성된 OIDC 공급자와 사용자의 웹 브라우저를 이용해 인증하며, Consul UI 또는 명령줄에서 시작할 수 있어요.

출처: 문서

본문

Enterprise

이 기능은 자체 관리형(self-managed) Consul Enterprise 버전 1.8.0+가 필요합니다.

자세한 내용은 엔터프라이즈 기능 매트릭스를 참조하세요.

oidc 인증 방법을 사용해 OIDC로 Consul에 인증할 수 있습니다. 이 방법은 사용자의 웹 브라우저를 사용해 구성된 OIDC 공급자를 통한 인증을 허용합니다.

이 방법은 Consul UI 또는 명령줄에서 시작할 수 있습니다.

이 페이지는 OIDC 개념과 기본 인증 방법 문서(auth method documentation)에 설명된 개념에 대한 일반적인 지식을 가정합니다.

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

JWT vs OIDC 인증 방법 (JWT vs OIDC Auth Methods)

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

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

구성 매개변수 (Config Parameters)

oidc 유형의 인증 방법을 올바르게 구성하려면 다음 인증 방법 Config 매개변수가 필요합니다.

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

클라이언트 시크릿이 있는 예시 구성 (Example configuration with client secret)

{
    "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를 클라이언트 어서션으로 사용하는 예시 구성 (Example configuration with JWT as client assertion)

다음 예시는 OIDC 공급자에게 보내는 클라이언트 어서션으로 RSA 프라이빗 키로 서명된 JWT를 설정하는 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 디스커버리를 통해 발급자의 공개 키에 대해 검증됩니다. 키는 인증 중에 OIDC Discovery URL에서 가져오며 OIDC 검증 기준(예: iss, aud 등)이 적용됩니다.

OIDC 인증 (OIDC Authentication)

Consul에는 두 가지 내장 OIDC 로그인 흐름이 포함됩니다: Consul UI와 consul login을 사용하는 CLI.

리디렉션 URI (Redirect URIs)

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

Consul UI

Consul UI를 통해 로그인하려면 http://localhost:8500/ui/oidc/callback 또는 https://{host:port}/ui/oidc/callback 형식의 리디렉션 URI가 필요합니다. "host:port"는 Consul UI를 제공하는 Consul 에이전트에 대해 올바른 값이어야 합니다.

CLI

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

Consul UI

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

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 Configuration Troubleshooting)

OIDC에 필요한 구성의 양은 상대적으로 적지만 작동하지 않는 이유를 디버깅하는 것은 까다로울 수 있습니다. OIDC 설정을 위한 몇 가지 팁:

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

클레임 매핑을 통한 신뢰된 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	예
value.last_name	Equal, Not Equal, In, Not In, Matches, Not Matches	예
list.groups	In, Not In, Is Empty, Is Not Empty	아니요

클레임 사양 및 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를 참조하세요.

OpenID Connect

OpenID Connect (OIDC) 인증 방법 (OpenID Connect (OIDC) Auth Method)

본문

JWT vs OIDC 인증 방법 (JWT vs OIDC Auth Methods)

구성 매개변수 (Config Parameters)

클라이언트 시크릿이 있는 예시 구성 (Example configuration with client secret)

JWT를 클라이언트 어서션으로 사용하는 예시 구성 (Example configuration with JWT as client assertion)

JWT 검증 (JWT Verification)

OIDC 인증 (OIDC Authentication)

리디렉션 URI (Redirect URIs)

Consul UI

CLI

OIDC 로그인 (OIDC Login)

Consul UI

CLI

OIDC 구성 문제 해결 (OIDC Configuration Troubleshooting)

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

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

더 알아보기 (Learn more)