OAuth2 및 OIDC 인증 | Teleport 공식 기술 문서 한국판 by 인포그랩

OAuth2 및 OIDC 인증

이 가이드는 특정 사용자 그룹에 Teleport 자격 증명을 발급하기 위해 OpenID Connect (OIDC라고도 함) 를 사용하는 SSO 공급자를 구성하는 방법을 설명합니다. 역할 기반 액세스 제어(RBAC)와 결합하여 OIDC를 사용할 경우 Teleport 관리자들이 다음과 같은 정책을 정의할 수 있습니다:

"DBA" 그룹의 구성원만 PostgreSQL 데이터베이스에 연결할 수 있습니다.
개발자는 프로덕션 서버에 SSH로 접속해서는 안 됩니다.

사전 요구 사항

사용자 그룹/역할에 할당된 SSO/IdP에 대한 관리자 액세스.
oidc 리소스를 유지할 수 있는 권한이 있는 Teleport 역할. 이 권한은 기본 editor 역할에서 사용할 수 있습니다.

실행 중인 Teleport 클러스터. Teleport를 시작하려면 가입하기 무료 체험판을 이용해 보세요.
tctl 관리 도구 및 tsh 클라이언트 도구 버전 >= 16.2.0.

tctl 및 tsh 다운로드 방법에 대한 지침은 설치를 방문하세요.

당신의 Teleport 클러스터에 연결할 수 있는지 확인하려면, tsh login으로 로그인한 다음 현재 자격 증명을 사용하여 tctl 명령어를 실행할 수 있는지 확인하십시오. 예를 들어:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
클러스터  teleport.example.com
버전  16.2.0
CA 핀   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
클러스터에 연결하고 tctl status 명령어를 실행할 수 있다면, 현재 자격 증명을 사용하여 작업대에서 후속 tctl 명령어를 실행할 수 있습니다. 자신의 Teleport 클러스터를 호스팅하는 경우, Teleport 인증 서비스를 호스팅하는 컴퓨터에서 전체 권한으로 tctl 명령어를 실행할 수도 있습니다.

아이덴티티 공급자

사용할 외부 아이덴티티 공급자와 Teleport를 등록하고 client_id 및 client_secret을 얻으십시오. 이 정보는 아이덴티티 공급자의 웹사이트에 문서화되어 있어야 합니다. 몇 가지 링크는 다음과 같습니다:

Google Workspace

Google Workspace에 대한 내용은 Google Workspace와 함께하는 Teleport 인증을 참조하십시오.

아이덴티티 공급자로부터 관련 정보를 저장하십시오. 이 가이드를 따라가기 쉽게 하기 위해 여기에 클라이언트 ID를 추가할 수 있으며, 아래 예제 명령에 포함됩니다:

클라이언트 ID: <CLIENT-ID>

OIDC 리디렉션 URL

OIDC는 인증이 완료된 후 Teleport로 제어를 반환하기 위해 HTTP 리디렉션에 의존합니다. 리디렉션 URL은 Teleport 관리자가 사전에 선택해야 합니다.

Teleport의 OIDC 인증을 위한 리디렉션 URL은 mytenant.teleport.sh/v1/webapi/oidc/callback입니다. mytenant.teleport.sh를 귀하의 Teleport Cloud 테넌트 또는 프록시 서비스 주소로 바꾸십시오.

OIDC 커넥터 구성

다음 단계는 Teleport에 OIDC 커넥터를 추가하는 것입니다. 커넥터는 tctl 리소스 명령 또는 Teleport 웹 UI를 사용하여 생성, 테스트 및 추가하거나 제거할 수 있습니다.

작업 공간에서 client-secret.txt라는 파일을 생성하고, 그 안에는 클라이언트 비밀만 포함되도록 하십시오.

새 커넥터를 생성하려면 tctl sso configure를 사용하십시오. 다음 예제는 oidc-connector.yaml이라는 YAML 형식의 커넥터 리소스 파일을 생성합니다:

tctl sso configure oidc --name <CONNECTOR-NAME> \  --issuer-url <PATH-TO-PROVIDER> \  --id <CLIENT-ID> \  --secret $(cat client-secret.txt) \  --claims-to-roles <CLAIM-KEY>,<CLAIM-VALUE>,access \  --claims-to-roles <CLAIM-KEY>,<CLAIM-VALUE>,editor > oidc-connector.yaml

--name: 일반적으로 IdP의 이름이며, 이 이름으로 커넥터가 Teleport에서 식별됩니다.
--issuer-url: IdP의 OIDC 구성 엔드포인트에 대한 기본 경로로, .well-known/openid-configuration는 제외합니다. 예를 들어 엔드포인트가 https://example.com/.well-known/openid-configuration인 경우 https://example.com을 사용합니다.
--id: IdP에 정의된 클라이언트 ID. 아이덴티티 공급자에 따라 이는 사용자가 정의할 수 있는 문자열(예: teleport)일 수도 있고, 할당된 문자열일 수도 있습니다.
--secret: 이 클라이언트를 인증하기 위해 IdP에서 제공하는 클라이언트 토큰/비밀.
--claims-to-roles: OIDC 클레임/값을 Teleport 역할과 연결하는 매핑.

이와 모든 사용 가능한 플래그에 대한 자세한 내용은 Teleport CLI 참조 페이지의 tctl sso configure oidc 섹션을 참조하십시오.

생성된 파일은 아래 예제와 같아야 합니다. 이 커넥터는 아이덴티티 공급자로부터 <CLAIM-KEY> 범위를 요청하고, 해당 키 내에서 반환된 값에 따라 access 또는 editor 역할에 매핑합니다:

(!examples/resources/oidc-connector.yaml!)

다음 예제는 아이덴티티 공급자로 Keycloak을 사용하여 생성되었습니다. Keycloak은 keycloak.example.com에서 제공되며, Teleport 프록시 서비스는 teleport.example.com에서 수신 대기합니다. Keycloak에서 클라이언트 이름은 teleport입니다. teleport-dedicated 클라이언트 범위 아래에 "그룹 멤버십" 매퍼를 추가했습니다:

kind: oidc
metadata:
  name: keycloak
spec:
  claims_to_roles:
  - claim: groups
    roles:
    - access
    value: /users
  - claim: groups
    roles:
    - editor
    value: /admins
  client_id: teleport
  client_secret: abc123...
  issuer_url: https://keycloak.example.com/realms/master
  redirect_url: https://teleport.example.com:443/v1/webapi/oidc/callback
version: v3

커넥터를 클러스터에 적용하기 전에 올바르게 구성되었는지 테스트할 수 있습니다:

cat oidc-connector | tctl sso test

이 명령은 웹 브라우저를 열고 IdP를 통해 Teleport 클러스터에 로그인하려고 시도합니다. 실패할 경우, 이 명령의 출력 내용을 리뷰하여 문제를 해결하십시오.

Tip

CLI 출력의 "[OIDC] Claims" 섹션은 IdP에서 제공한 사용자 정보의 모든 세부 정보를 제공합니다. 이는 사용자 속성을 계산할 수 없습니다와 같은 오류를 해결하는 데 좋은 출발점입니다.

테스트가 성공하면 커넥터를 생성하십시오:

tctl create -f oidc-connector.yaml

선택 사항: ACR 값

Teleport는 OIDC 공급자로부터 인증 코드 획득 시 인증 컨텍스트 클래스 참조(ACR) 값을 전송하는 것을 지원합니다. 기본적으로 ACR 값은 설정되지 않습니다. 그러나 acr_values 필드가 설정된 경우, Teleport는 acr 클레임에서도 동일한 값을 수신할 것으로 기대하며, 그렇지 않으면 콜백을 유효하지 않은 것으로 간주합니다.

또한, Teleport는 OIDC 구성에서 provider 필드를 설정하여 OIDC 공급자 특정 ACR 값 처리를 지원합니다. 현재로서는 내장 지원이 NetIQ에만 제공됩니다.

ACR 값과 공급자 특정 처리를 사용하는 예는 다음과 같습니다:

# ACR 값을 사용하는 예시 커넥터
kind: oidc
version: v2
metadata:
  name: "oidc-connector"
spec:
  issuer_url: "https://oidc.example.com"
  client_id: "xxxxxxxxxxxxxxxxxxxxxxx.example.com"
  client_secret: "zzzzzzzzzzzzzzzzzzzzzzzz"
  redirect_url: "https://mytenant.teleport.sh/v1/webapi/oidc/callback"
  display: "Example로 로그인"
  acr_values: "foo/bar"
  provider: netiq
  scope: [ "group" ]
  claims_to_roles:
     - claim: "group"
       value: "editor"
       roles: [ "editor" ]
     - claim: "group"
       value: "user"
       roles: [ "access" ]

선택 사항: 최대 나이

Teleport는 버전 13.3.7부터 사용자의 세션 최대 연령을 설정하는 max_age 필드를 지원하여 사용자가 재인증해야 하는 최대 연령을 제어할 수 있습니다. 기본적으로 max_age는 설정되지 않으며, 사용자가 OIDC를 사용하여 인증을 받은 후, 구성된 OIDC 공급자가 그들을 강제로 인증하지 않는 한 재인증할 필요가 없습니다. 이를 사용하여 더 자주 재인증하도록 사용자에게 강제할 수 있습니다. max_age가 0초로 설정되면, 사용자는 Teleport에서 인증할 때마다 OIDC 공급자와 재인증해야 합니다.

지정된 기간은 전체 초 단위로 입력해야 합니다. 24h는 1440s와 동일하기 때문에 작동하지만, 60s500ms는 60.5초이기 때문에 허용되지 않습니다.

# OIDC yaml의 추가 부분이 제거되었습니다.
spec:
  max_age: 24h

모든 OIDC 공급자가 max_age 설정을 지원하지는 않습니다. Google과 GitLab은 이를 지원하지 않는 것으로 알려져 있으며, 이러한 공급자를 사용할 경우 max_age 필드가 설정되면 인증이 실패합니다.

선택 사항: 프롬프트

OIDC 프로토콜에 따라 최종 사용자에 대한 재인증 및 동의에 대한 인증 서버 프롬프트를 설정합니다. prompt 값이 설정되지 않으면 Teleport는 기본값으로 select_account를 사용합니다.

# OIDC yaml의 추가 부분이 제거되었습니다.
spec:
  # https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest에 정의된 유효한 값
  # none: 인증 또는 동의 사용자 인터페이스 페이지를 표시하지 않아야 합니다.
  # select_account: 인증 서버는 최종 사용자에게 사용자 계정을 선택하라는 메시지를 표시해야 합니다.
  # login: 인증 서버는 최종 사용자에게 재인증을 요청해야 합니다.
  # consent: 인증 서버는 최종 사용자에게 클라이언트에 정보를 반환하기 전에 동의하도록 요청해야 합니다.
  prompt: 'login'

선택 사항: 리디렉션 URL 및 타임아웃

리디렉션 URL은 모든 사용자가 접근할 수 있어야 하며, 선택적 리디렉션 타임아웃을 설정할 수 있습니다.

# OIDC yaml의 추가 부분이 제거되었습니다.
spec:
  redirect_url: https://<cluster-url>.example.com:3080/v1/webapi/oidc/callback
  # 선택적 리디렉션 타임아웃.
  # redirect_timeout: 90s

선택 사항: 이메일 확인 비활성화

기본적으로 Teleport는 email_verified 클레임을 검증하며, 확인된 이메일 주소가 없는 사용자는 로그인할 수 없습니다:

ERROR: SSO 흐름 실패.
아이덴티티 공급자 콜백이 오류와 함께 실패했습니다: OIDC 공급자가 이메일을 검증하지 않았습니다.
        이메일이 OIDC 공급자에 의해 검증되지 않음

테스트 및 기타 목적을 위해 OIDC 커넥터에서 allow_unverified_email을 활성화하여 이 동작을 비활성화할 수 있습니다. 이 옵션은 시스템의 전반적인 보안을 약화시키므로 활성화하는 것을 권장하지 않습니다.

kind: oidc
version: v2
metadata:
  name: connector
spec:
  allow_unverified_email: true

선택 사항: 사용자 이름으로 사용할 클레임 지정하기

기본적으로 Teleport는 사용자의 이메일을 Teleport 사용자 이름으로 사용합니다.

대신에 사용자 이름으로 사용해야 할 클레임을 지정하기 위해 username_claim을 정의할 수 있습니다:

kind: oidc
version: v2
metadata:
  name: connector
spec:
  # 사용자의 Teleport 사용자 이름으로 `preferred_username` 클레임을 사용합니다.
  username_claim: preferred_username

기본 OIDC 인증 활성화

OIDC 인증을 기본으로 사용하도록 Teleport를 구성하고 로컬 사용자 데이터베이스 대신 사용하십시오.

귀하의 Teleport 에디션에 대한 지침을 따르십시오:

/etc/teleport.yaml의 auth_service 섹션을 업데이트하고 teleport 데몬을 재시작하십시오.

auth_service:
  authentication:
    type: oidc

cap.yaml이라는 파일을 만드십시오:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:    
  type: oidc
version: v2

리소스를 생성하십시오:

tctl create -f cap.yaml

문제 해결

SSO 구성 문제를 해결하는 것은 어려울 수 있습니다. 일반적으로 Teleport 관리자는 다음을 수행할 수 있어야 합니다:

SSO 공급자가 Teleport에 내보내고 전달하는 SAML/OIDC 클레임 및 값이 무엇인지 확인할 수 있어야 합니다.
관련 클레임을 커넥터에서 정의된 역할 매핑으로 Teleport가 어떻게 매핑하는지 확인할 수 있어야 합니다.
자체 호스팅된 Teleport Enterprise 클러스터의 경우, Teleport 프록시 서비스와 SSO 공급자 모두에 대해 HTTP/TLS 인증서가 올바르게 구성되어 있는지 확인해야 합니다.

무언가가 작동하지 않는 경우, 다음을 권장합니다:

커넥터 정의에서 호스트 이름, 토큰 및 TCP 포트를 다시 확인하십시오.

웹 UI 사용하기

"액세스가 거부되었습니다." 또는 다른 로그인이 오류가 발생하면 가장 먼저 확인해야 할 곳은 감사 로그입니다. 관리 영역 아래에서 Teleport 웹 UI의 활동 탭 내에서 액세스할 수 있습니다.

역할 clusteradmin이 설정되지 않아 사용자가 거부된 예:

{  
  "code": "T1001W",  
  "error": "role clusteradmin is not found",  
  "event": "user.login",  
  "method": "oidc",  
  "success": false,  
  "time": "2019-06-15T19:38:07Z",  
  "uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"  
}

Teleport가 예상하는 노드를 표시하지 않음

When Teleport의 인증 서비스가 Teleport 노드를 나열하라는 요청을 받으면 (예: 웹 UI에서 노드를 표시하거나 tsh ls를 통해), 현재 사용자가 볼 수 있는 권한이 있는 노드만 반환합니다.

사용자의 Teleport 클러스터에 있는 각 노드에 대해 인증 서비스는 다음 검사를 순서대로 적용하며, 하나의 검사가 실패하면 해당 노드를 사용자에게 숨깁니다:

사용자의 역할 중 어느 것도 노드의 레이블과 일치하는 deny 규칙을 포함하지 않아야 합니다.
사용자의 역할 중 적어도 하나는 노드의 레이블과 일치하는 allow 규칙을 포함해야 합니다.

예상할 때 노드를 볼 수 없다면, 사용자의 역할에 Teleport 접근 제어 참조에 문서화된 적절한 allow 및 deny 규칙이 포함되어 있는지 확인하세요.

SSO를 구성할 때, 각 사용자의 특성이 올바르게 채워지고 있는지 확인하십시오. 사용자가 Teleport에서 노드를 보려면 역할의 allow.logins에서 템플릿 변수를 채우는 결과가 사용자의 traits.logins 중 하나와 일치해야 합니다.

이 예에서 사용자는 env: dev 레이블이 있는 노드에 대해 ubuntu, debian 및 SSO 특성 logins에서 가져온 사용자 이름을 가집니다. SSO 특성 사용자 이름이 bob인 경우 사용자 이름에는 ubuntu, debian 및 bob이 포함됩니다.

kind: role  
metadata:  
  name: example-role  
spec:  
  allow:  
    logins: ['{{external.logins}}', ubuntu, debian]  
    node_labels:  
      'env': 'dev'  
version: v5

OIDC로 단일 로그인 실패

"JWT 확인 실패: oidc: JWT 서명을 검증할 수 없음: 일치하는 키가 없음"이라는 오류 메시지를 받으면, 일반적으로 JWT 토큰 서명에 사용된 알고리즘과 JSON 웹 키 세트(JWKS)에서 지원되는 알고리즘 간의 불일치를 나타냅니다. 특히, 토큰이 한 알고리즘, 예를 들어 HS256으로 서명된 경우, JWKS는 다른 알고리즘에 대한 키만 나열할 수 있습니다. 예를 들어 RS256. 이 문제는 기본 기능을 제공하는 ID 공급자를 사용할 때 주로 발생합니다.

확인해야 할 사항은 다음과 같습니다:

JWT 헤더가 올바른 서명 알고리즘을 지정하는지 확인하십시오. 이는 JWKS 엔드포인트 응답의 키 섹션에 나열된 알고리즘 중 하나와 일치해야 합니다.
JWKS 엔드포인트가 모든 관련 공개 키를 반환하는지 확인하십시오. 때때로 키가 회전하면 유효한 키가 누락될 수 있습니다.

문제를 해결하려면 JWT 알고리즘 헤더를 JWKS에서 지원되는 알고리즘과 일치시킵니다. 필요한 경우 키를 회전시킵니다. JWKS가 활성 공개 키만 게시하는지 확인하십시오. 올바른 구성으로 서명이 성공적으로 검증되어야 합니다.

Teleport 원문 보기