이 가이드는 특정 사용자 그룹에게 로그인 자격 증명을 발급하는 싱글 사인온(SSO) 프로바이더로 Active Directory Federation Services(ADFS)를 구성하는 방법을 설명합니다. 역할 기반 접근 제어(RBAC)와 함께 사용하면 Teleport 관리자가 다음과 같은 정책을 정의할 수 있습니다:

• "DBA" 그룹의 구성원만 PostgreSQL을 실행하는 머신에 SSH로 접근할 수 있습니다.
• 개발자는 프로덕션 서버에 절대 SSH 접근을 하면 안 됩니다.

작동 방식#

You can register your Teleport cluster as an application with ADFS, then create an authentication connector resource that provides Teleport with information about your application. When a user signs in to Teleport, ADFS 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 ADFS with the names of one or more Teleport roles.

사전 요구 사항#

• 관리자 접근 권한과 최소 두 그룹에 할당된 사용자가 있는 ADFS 설치.
• saml 리소스를 유지 관리할 수 있는 접근 권한이 있는 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단계. ADFS 구성#

사용자에 대한 클레임을 내보내도록 ADFS를 구성해야 하고(ADFS 용어로 Claims Provider Trust), Teleport를 신뢰하도록 ADFS를 구성해야 합니다(ADFS 용어로 Relying Party Trust).

Claims Provider Trust 구성을 위해 AD FS 관리 창을 엽니다. Claims Provider Trusts 아래에서 Active Directory를 마우스 오른쪽 버튼으로 클릭하고 Edit Claim Rules를 선택합니다. 최소한 Name ID와 Group 두 가지 들어오는 클레임을 지정해야 합니다.

• Name ID는 LDAP 속성 E-Mail-Addresses를 Name ID에 매핑해야 합니다.

  

• 그룹 멤버십 클레임은 사용자를 역할에 매핑하는 데 사용해야 합니다(예: 일반 사용자와 관리자를 분리하기 위해).

  

• 동적 역할을 사용하는 경우(아래 참조), LDAP 속성 SAM-Account-Name을 Windows account name에 매핑하는 것이 유용할 수 있습니다:

  

• 그리고 E-Mail-Addresses에서 UPN으로의 다른 매핑을 만듭니다:

  

또한 Relying Party Trust를 만들어야 합니다. 아래 정보를 참고하여 마법사를 진행하세요.

• Relaying Party Trust 만들기:
• 신뢰 당사자에 대한 데이터를 수동으로 입력합니다.
• 표시 이름을 Teleport와 같은 이름으로 설정합니다.
• 토큰 암호화 인증서를 건너뜁니다.
• *"Enable support for SAML 2.0 Web SSO protocol"*을 선택하고 URL을 https:///v1/webapi/saml/acs로 설정합니다. 도메인 이름을 Teleport Proxy Service URL로 교체합니다. 여러 공개 주소를 가진 셀프 호스팅 클러스터가 있는 경우 이 주소가 첫 번째로 나열된 것을 가리키도록 합니다.
• 신뢰 당사자 식별자를 https:///v1/webapi/saml/acs로도 설정합니다.
• 접근 제어 정책으로 *"Permit everyone"*을 선택합니다.

Relying Party Trust가 만들어지면 Claim Issuance Policy를 업데이트합니다. 이전과 마찬가지로 최소한 Name ID와 Group 클레임을 신뢰 당사자(Teleport)에게 보내야 합니다. 동적 역할을 사용하는 경우 LDAP 속성 SAM-Account-Name을 *"Windows account name"*에 매핑하고 E-Mail-Addresses에서 *"UPN"*으로의 다른 매핑을 만드는 것이 유용할 수 있습니다.

마지막으로 Active Directory에서 만든 사용자에게 이메일 주소가 연결되어 있는지 확인합니다. 이를 확인하려면 Server Manager를 열고 *"Tools -> Active Directory Users and Computers"*를 선택하여 사용자를 선택하고 마우스 오른쪽 버튼을 클릭하여 속성을 엽니다. 이메일 주소 필드가 채워져 있는지 확인합니다.

2/3단계. ADFS를 Teleport에 연결#

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

역할 매핑 할당#

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:

<attribute_name>,<attribute_value>,<teleport_role_1>,<teleport_role_2>,...,<teleport_role_n>

For example, the following role mapping means that any user with the attribute 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:

역할 매핑에서 각 속성이 다음 네임스페이스 접두사로 시작하는지 확인합니다:

http://schemas.xmlsoap.org/claims/

SAML 커넥터 구성#

tctl을 사용하여 SAML 커넥터 리소스를 만듭니다:

$ tctl sso configure saml --acs https:///v1/webapi/saml/acs \
  --preset adfs \
  --entity-descriptor https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml \
  --attributes-to-roles  \
  --attributes-to-roles   \
  > adfs.yaml

--attributes-to-roles 플래그는 이전에 할당한 역할 매핑을 포함합니다.

acs 필드는 이전에 ADFS에서 설정한 값과 일치해야 하며, entity_descriptor_url은 "ADFS -> Service -> Endpoints -> Metadata" 아래 ADFS에서 얻을 수 있습니다.

서명 키 내보내기#

마지막 단계로 서명 키를 내보내야 합니다:

$ tctl saml export adfs > saml.cer

saml.cer을 ADFS 서버에 복사하고 "Relying Party Trust"를 열어 이 파일을 서명 검증 인증서 중 하나로 추가합니다:

이제 웹 UI에 새 버튼 "Login with MS Active Directory"가 표시됩니다. CLI는 이전과 동일합니다:

$ tsh --proxy=proxy.example.com login

이 명령은 SSO 로그인 URL을 출력하고 브라우저에서 자동으로 열려고 합니다.

커넥터 테스트#

다음 명령을 실행하여 커넥터를 테스트합니다:

$ tctl sso test < adfs.yaml

커넥터 만들기#

커넥터를 적용합니다:

$ tctl create -f adfs.yaml

3/3단계. 인증 기본 설정 구성#

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 saml:

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

After you save and exit the editor, tctl will update the resource:

cluster auth preference has been updated

# Snippet from /etc/teleport.yaml
auth_service:
  authentication:
    type: saml

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.

문제 해결#

Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator must be able to:

• Be able to see what SAML/OIDC claims and values are getting exported and passed by the SSO provider to Teleport.
• Be able to see how Teleport maps the received claims to role mappings as defined in the connector.
• For self-hosted Teleport Enterprise clusters, ensure that HTTP/TLS certificates are configured properly for both the Teleport Proxy Service and the SSO provider.

If something is not working, we recommend to:

• Double-check the host names, tokens and TCP ports in a connector definition.

Using the Web UI#

If you get "access denied" or other login errors, the number one place to check is the Audit Log. To view the recording, select Audit in the Teleport Web UI, then click Session Recordings in the menu.

Example of a user being denied because the role clusteradmin wasn't set up:

{
  "code": "T1001W",
  "error": "role clusteradmin is not found",
  "event": "user.login",
  "message": "Failed to calculate user attributes.\n\trole clusteradmin is not found",
  "method": "oidc",
  "success": false,
  "time": "2024-11-07T15:41:25.584Z",
  "uid": "71e46f17-d611-48bb-bf5e-effd90016c13"
}

Teleport does not show the expected Nodes#

(!docs/pages/includes/node-logins.mdx!)

When configuring SSO, ensure that the identity provider is populating each user's traits correctly. For a user to see a Node in Teleport, the result of populating a template variable in a role's allow.logins must match at least one of a user's traits.logins.

In this example a user will have usernames ubuntu, debian and usernames from the SSO trait logins for Nodes that have a env: dev label. If the SSO trait username is bob then the usernames would include ubuntu, debian, and bob.

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

Single sign-on fails with OIDC#

When encountering the error message "Failed to verify JWT: oidc: unable to verify JWT signature: no matching keys", it typically indicates a discrepancy between the algorithm used to sign the JWT token and the algorithm(s) supported by the JSON Web Key Set (JWKS). Specifically, the token might be signed with one algorithm, e.g., HS256, while the JWKS only lists keys for a different algorithm. e.g., RS256. This issue predominantly arises when using identity providers that offer extremely low-level functionality.

Here are some things to check:

• Verify the JWT header specifies the correct signing algorithm. This should match one of the algorithms listed in the keys section of the JWKS endpoint response.
• Ensure the JWKS endpoint is returning all relevant public keys. Sometimes key rotation can cause valid keys to be omitted.

To resolve the issue, align the JWT algorithm header with a supported algorithm in the JWKS. Rotate keys if necessary. Verify the JWKS only publishes the active public keys. With proper configuration, the signature should validate successfully.