이 가이드는 OpenID Connect(OIDC라고도 함)를 사용하는 SSO 프로바이더를 구성하여 특정 사용자 그룹에게 Teleport 자격 증명을 발급하는 방법을 설명합니다. 역할 기반 접근 제어(RBAC)와 함께 사용하면 OIDC를 통해 Teleport 관리자가 다음과 같은 정책을 정의할 수 있습니다:

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

작동 방식#

You can register your Teleport cluster as an application with your SSO provider, then create an authentication connector resource that provides Teleport with information about your application. When a user signs in to Teleport, your SSO provider executes its own authentication flow, then sends an HTTP request to your Teleport cluster to indicate that authentication has completed.

Teleport authenticates users to your infrastructure by issuing short-lived certificates. After a user completes an SSO authentication flow, Teleport issues short-lived TLS and SSH certificates to the user. Teleport also creates a temporary user on the Auth Service backend.

Teleport roles are encoded in the user's certificates. To assign Teleport roles to the user, the Auth Service inspects the role mapping within the authentication connector, which associates user data on your SSO provider with the names of one or more Teleport roles.

사전 요구 사항#

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

• A running Teleport Enterprise cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace with the web address of your Teleport Proxy Service:

     $ TELEPORT_DOMAIN=
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     

  2. Follow the instructions for your platform to install tctl and tsh clients:

To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials.

For example, run the following command, assigning to the domain name of the Teleport Proxy Service in your cluster and to your Teleport username:

$ tsh login --proxy= --user=
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

1/3단계. OIDC 프로바이더 구성#

사용할 외부 아이덴티티 프로바이더에 Teleport를 등록하고 client_id와 client_secret을 얻습니다. 이 정보는 아이덴티티 프로바이더 웹사이트에 문서화되어 있어야 합니다. 다음은 몇 가지 링크입니다:

• Auth0 클라이언트 구성
• Google Identity Platform
• Keycloak 클라이언트 등록

아이덴티티 프로바이더에서 관련 정보를 저장합니다. 이 가이드를 더 쉽게 따르려면 여기에 클라이언트 ID를 추가하면 아래 예제 명령에 포함됩니다:

클라이언트 ID:

OIDC 리다이렉트 URL 선택#

OIDC는 HTTP 리다이렉트를 사용하여 인증 완료 후 Teleport로 제어를 반환합니다. 리다이렉트 URL은 Teleport 관리자가 미리 선택해야 합니다.

Teleport에서 OIDC 인증의 리다이렉트 URL은 /v1/webapi/oidc/callback입니다. 를 Teleport Cloud 테넌트 또는 Proxy Service 주소로 교체합니다. 여러 공개 주소를 가진 셀프 호스팅 클러스터가 있는 경우 이 주소가 첫 번째로 나열된 것을 가리키도록 합니다.

2/3단계. OIDC 프로바이더를 Teleport에 연결#

이 섹션에서는 Teleport가 IdP와 OIDC 메시지를 교환하고 사용자에게 인증서를 발급하는 데 필요한 정보를 제공하는 인증 커넥터를 만듭니다.

역할 매핑 할당#

When a user authenticates to Teleport, the Teleport Auth Service issues SSH and TLS certificates to the user that contain the user's Teleport roles.

For SSO authentication connectors, the Auth Service determines which roles to encode in the certificate by reading the authentication connector's role mapping. The role mapping indicates which Teleport roles to assign based on data that your identity provider stores about the user.

When you configure an authentication connector using the tctl CLI, a role mapping takes the following format:

<claim_name>,<claim_value>,<teleport_role_1>,<teleport_role_2>,...,<teleport_role_n>

For example, the following role mapping means that any user with the claim groups with the value admins receives the Teleport roles auditor and editor:

groups,admins,auditor,editor

For the purpose of this guide, assign two separate role mappings:

• A more permissive role mapping:
• A more restrictive role mapping:

OIDC 커넥터 구성#

다음 단계는 Teleport에 OIDC 커넥터를 추가하는 것입니다. 커넥터는 tctl 리소스 명령이나 Teleport 웹 UI를 사용하여 만들고, 테스트하고, 추가하거나 제거합니다.

워크스테이션에서 클라이언트 시크릿만 포함된 client-secret.txt 파일을 만듭니다.

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

$ tctl sso configure oidc --name 

선택 사항: 요청 객체 모드#
Teleport는 RFC 9101을 따르는 "요청 객체"라고 하는 JSON Web Token(JWT)으로 인증 요청 파라미터를 전송하는 기능을 지원합니다. 현재 Teleport는 값으로 전송된 서명된 요청 객체만 지원합니다. 이 옵션은 OIDC IdP 통합에 사용되는 Teleport의 JSON Web Key Sets(JWKS)을 사용하여 IdP가 요청 객체 서명을 검증하기 위해 제공되거나 검색하도록 구성해야 합니다. 이 JWKS는 Web API의 /.well-known/jwks-oidc 경로에서 찾을 수 있습니다.
또한 요청 객체 서명 검증에 사용되는 공개 키는 tctl을 통해 찾을 수 있습니다.
$ tctl get cert_authority/oidc_idp/$CLUSTER_NAME --format=json | jq -r .[].spec.active_keys.jwt[].public_key

기본적으로 request_object_mode는 설정되지 않으며, 인증 요청 파라미터는 인증 엔드포인트의 쿼리 문자열로 전송됩니다.
kind: oidc
version: v2
metadata:
  name: connector
spec:
  # IdP에 인증 요청을 할 때 서명된 요청 객체를 사용합니다.
  request_object_mode: signed

요청 객체는 MFA 검사에도 지원됩니다. MFA 클라이언트에 request_object_mode가 명시적으로 설정되지 않은 경우 기본적으로 로그인 클라이언트의 요청 객체 모드가 사용됩니다. 원하는 경우 MFA 클라이언트가 별도의 요청 객체 모드를 사용하도록 명시적으로 구성할 수 있습니다.
kind: oidc
version: v2
metadata:
  name: connector
spec:
  client_id: teleport_login
  client_secret: abc123...
  request_object_mode: none
  mfa:
    client_id: teleport_mfa
    client_secret: mfa123...
    request_object_mode: signed

참고: 요청 객체 지원은 Teleport Enterprise 버전 17.7.2 이상 및 18.1.6 이상에서 사용 가능합니다.
커넥터 테스트#
클러스터에 커넥터를 적용하기 전에 올바르게 구성되었는지 테스트할 수 있습니다:
$ cat oidc-connector.yaml | tctl sso test

웹 브라우저가 열리고 IdP를 통해 Teleport 클러스터에 로그인하려고 합니다. 실패하면 이 명령의 출력에서 문제 해결 세부 정보를 검토하세요.
Tip
CLI 출력의 "[OIDC] Claims" 섹션에는 IdP에서 제공하는 사용자의 모든 세부 정보가 있습니다. 이는 Failed to calculate user attributes.와 같은 오류를 문제 해결할 때 좋은 출발점입니다.

커넥터 만들기#
테스트가 성공적이면 커넥터를 만듭니다:
$ tctl create -f oidc-connector.yaml

3/3단계. 기본 OIDC 인증 활성화#

Edit your cluster authentication preferences so you can make the authentication
connector you configured in this guide the default authentication method for
your Teleport cluster.
Open the Teleport Web UI. From the left sidebar, navigate to Zero Trust
Access > Auth Connectors. Find the connector you would like to make the
default and, from its three-dot menu, select Set as default.
If you are managing your Teleport resources as configuration files, you can
choose a default authentication connector using a dynamic resource. In this
case, use tctl to edit the cluster_auth_preference value:
$ tctl edit cluster_auth_preference

Set the value of spec.type to oidc:
kind: cluster_auth_preference
metadata:
  ...
  name: cluster-auth-preference
spec:
  ...
  type: oidc
  ...
version: v2

After you save and exit the editor, tctl will update the resource:
cluster auth preference has been updated


Additional ways to edit cluster auth preferences
The cluster auth preference is available as a Teleport Terraform provider
resource. Find a list of configuration options in the Cluster Auth Preferences
Resource
Reference.
If you self-host Teleport, you can edit your Teleport Auth Service configuration
file to include the following:
# Snippet from /etc/teleport.yaml
auth_service:
  authentication:
    type: oidc


If you need to log in again before configuring your identity provider, use the
flag --auth=local.

다음 단계#

Now that you have connected Teleport to your identity provider, you can
customize the way Teleport includes IdP data in Teleport roles.
With role templates, you can include user data from your IdP directly in
Teleport roles. If you use the external template variable in the value of a
role field, Teleport passes that value from your IdP. In this example, all of
the role options you can use for allowing users to assume certain principals on
remote systems come from your IdP:
kind: role
version: v7
metadata:
  name: sso-users
spec:
  allow:
    logins: ['{{external.logins}}']
    aws_role_arns: ['{{external.aws_role_arns}}']
    azure_identities: ['{{external.azure_identities}}']
    db_names: ['{{external.db_names}}']
    db_roles: ['{{external.db_roles}}']
    db_users: ['{{external.db_users}}']
    desktop_groups: ['{{external.desktop_groups}}']
    gcp_service_accounts: ['{{external.gcp_service_accounts}}']
    host_groups: ['{{external.host_groups}}']
    host_sudoers: ['{{external.host_sudoers}}']
    kubernetes_groups: ['{{external.kubernetes_groups}}']
    kubernetes_users: ['{{external.kubernetes_users}}']
    windows_desktop_logins: ['{{external.windows_desktop_logins}}']

For more information on using the external template variable, see Role
Templates.
For an explanation of the fields listed above, see the Role
Reference.
If you need to transform your IdP user data before you include it in Teleport
roles, you can do so using Login Rules. Login Rules allow you to include
external traits within Teleport roles even if your IdP provides user data in a
different format than the one expected by Teleport. Read more about Login
Rules.

문제 해결#
Note
이 섹션의 내용은 원문 문서를 참조하세요. (oidc-login-troubleshooting.mdx)