📣 Teleport의 공식 파트너 인포그랩에서 OpenAI 기술 기반으로 자체 개발한 자동화 번역 프로그램을 통해 Teleport 공식 문서의 한글판을 국내 최초로 제공합니다.
Infograb logo
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 원문 보기
인포레터에서 최신 DevOps 트렌드를 격주로 만나보세요!