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

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

작동 방식#

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

사전 요구 사항#

시작하기 전에 다음을 확인합니다:

• Google Workspace 최고 관리자 계정이 있습니다. 모범 사례로 관리자 작업을 수행하기 위해 다단계 인증이 필요한 별도의 계정을 설정해야 합니다. 대부분의 경우 자신의 로그인 사용자 계정에 높은 관리자 권한을 부여하지 않아야 합니다.

• Google Cloud에 가입하고 Google Cloud 프로젝트를 만들 수 있습니다. 이 가이드는 유료 Google Cloud 서비스 사용이 필요하지 않습니다.

• Google Workspace 그룹을 설정할 수 있습니다.

• oidc 리소스를 유지 관리할 수 있는 권한이 있는 Teleport 역할이 있습니다. 이 권한은 사전 설정 editor 역할에서 사용 가능합니다.

• Teleport 클러스터, Enterprise 에디션, 그리고 커맨드라인 도구가 있습니다.

• 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단계. Google Workspace 구성#

Google Workspace가 Teleport와 함께 작동하도록 구성하려면 다음 단계가 필요합니다:

• Google Workspace 에디션을 검토하여 Teleport와 통합 방식을 결정합니다.
• Google Cloud Platform에서 새 프로젝트를 만듭니다.
• 새 프로젝트에 대한 OAuth 동의를 구성합니다.
• 필수 API를 활성화합니다.
• Teleport 클러스터에 Google Workspace 사용자가 로그인할 수 있도록 OAuth 클라이언트 ID를 만듭니다.
• Teleport가 추가 Google Groups 정보에 접근하기 위한 서비스 계정을 만듭니다.
• 서비스 계정에 대한 도메인 전체 위임을 구성합니다.

Google Workspace 에디션 검토#

Google Workspace는 개인과 조직을 위해 다양한 기능과 기능을 갖춘 여러 에디션으로 제공됩니다. Google Workspace 에디션 간의 차이로 인해 사용하는 Google Workspace 에디션에 따라 Teleport가 Google Workspace와 통합하는 방식에 근본적인 차이가 있습니다.

일부 Google Workspace 에디션은 전이적 그룹 멤버십을 제공합니다. 전이적 그룹 멤버십을 사용하면 사용자는 다른 그룹에 속함으로써 한 그룹의 구성원이 될 수 있습니다. 예를 들어 부모 그룹 내에 중첩된 자식 그룹이 있는 경우 자식 그룹의 모든 구성원은 부모 그룹의 구성원이기도 합니다. Teleport는 직접 그룹 멤버십과 전이적 그룹 멤버십을 모두 지원하지만 다른 방법을 사용합니다.

Google Workspace 에디션 및 API#

Google Workspace 서비스 계정은 Google Workspace Cloud Identity API의 메서드를 호출하여 사용자가 특정 그룹에 전이적 멤버십을 가지고 있는지 확인할 수 있습니다. 이 API 메서드는 특정 Google Workspace 에디션에 속하는 사용자에게만 사용할 수 있습니다.

Google Workspace Directory API는 관리자가 Google Workspace 도메인의 사용자와 그룹을 나열할 수 있지만 전이적 그룹 멤버십을 쿼리할 수는 없습니다. Directory API는 모든 Google Workspace 에디션에서 사용 가능합니다.

Teleport의 Google Workspace API 사용 방법#

Teleport OIDC 커넥터는 Google Workspace API를 사용하여 Google Workspace 그룹 구성원을 속한 Teleport 역할에 매핑합니다.

사용자의 Google Workspace 그룹 목록을 가져오기 위해 Teleport는 먼저 Cloud Identity API 메서드를 호출하여 자격 증명을 얻으려고 합니다. 성공하면 Teleport는 자격 증명을 사용하여 사용자의 전이적 그룹 멤버십을 쿼리합니다.

자격 증명이 존재하지 않으면 Teleport는 Directory API 메서드를 호출하여 자격 증명을 얻습니다. Teleport는 그런 다음 Directory API를 사용하여 조직의 전체 Google Workspace에서 사용자의 그룹을 나열합니다. 사용자가 속한 워크스페이스 외부의 그룹은 나열되지 않습니다.

현재 에디션 확인 방법#

Google Workspace 에디션이 전이적 그룹 멤버십 쿼리를 지원하는지 확인하려면:

1. Google Workspace Admin Console에서 Inspect Groups를 엽니다.

   그룹 검사는 Cloud Identity API에 의존합니다.

2. List all groups for a member 및 Include external groups를 선택합니다.

   Google Workspace 에디션이 Cloud Identity API를 지원하는 경우 외부 그룹에 대한 접근 허용 또는 차단에 설명된 대로 워크스페이스 수준에서 외부 그룹에 대한 접근을 차단해야 합니다. 그렇지 않으면 워크스페이스 외부의 모든 그룹에 멤버십이 있으면 사용자가 로그인하지 못합니다.

   Google Workspace 에디션이 Cloud Identity API를 지원하지 않는 경우 역할 기반 접근 제어가 전이적 그룹 멤버십에 의존하지 않도록 해야 합니다.

새 프로젝트 만들기#

기존 Google Cloud 프로젝트에 Teleport용 싱글 사인온을 추가하려면 Google Cloud console에서 해당 프로젝트를 선택하고 이 단계를 건너뛸 수 있습니다. 프로젝트가 없거나 Teleport를 위해 특별히 새 프로젝트를 만들려면 Enabled APIs & Service 프로젝트 선택기 대시보드로 직접 이동할 수 있습니다.

새 프로젝트를 만들려면:

1. Google Cloud console을 엽니다.

2. Google Cloud console 탐색 메뉴에서 APIs & Services를 클릭합니다.

3. Enabled APIs and services에서 프로젝트 선택기를 클릭한 다음 New Project를 클릭합니다. 대시보드에 선택할 프로젝트가 없으면 Create Project를 클릭합니다.

   

4. 프로젝트 이름을 입력하고 프로젝트의 조직과 위치를 선택한 다음 Create를 클릭합니다.

OAuth 동의 구성#

새 프로젝트에 대한 OAuth 동의를 구성하려면:

1. Google Cloud console 사이드바에서 OAuth consent screen을 클릭합니다.

2. User Type으로 Internal을 선택하고 Create를 클릭합니다.

   

3. 다음을 수행하여 OAuth 클라이언트 동의 정보를 구성합니다:

   • 애플리케이션 이름을 입력합니다.
   • OAuth 동의에 대한 이메일 메시지를 받을 사용자 또는 그룹을 선택합니다.
   • 필요에 따라 다른 애플리케이션 옵션을 설정합니다.
   • 프로젝트에 변경 사항이 있는 경우 연락할 개발자의 이메일 주소를 제공합니다.

4. Save and continue를 클릭합니다.

5. Add or remove scopes를 클릭합니다.

6. .../auth/userinfo.email 및 openid 범위를 선택한 다음 Update를 클릭합니다.

7. Save and continue를 클릭합니다.

8. 요약 페이지의 정보를 검토한 다음 Back to dashboard를 클릭합니다.

필수 API 활성화#

OAuth 클라이언트에 필요한 API를 활성화하려면:

1. API Library에서 Admin SDK API를 선택한 다음 Enable을 클릭하여 직접 그룹 멤버십을 지원합니다.
2. API Library에서 Cloud Identity API를 선택한 다음 Enable을 클릭하여 전이적 그룹 멤버십을 지원합니다.

하나 또는 두 API 라이브러리를 모두 활성화할 수 있습니다. 그러나 Google Workspace 에디션은 사용하려는 API를 지원해야 합니다. 지원되는 Google Workspace 에디션이 있는지 확인하려면 API 라이브러리 문서를 참조하세요.

OAuth 클라이언트 ID 만들기#

OAuth 클라이언트 식별자를 만들려면:

1. Google Cloud console 사이드바에서 APIs & Services를 클릭합니다.

2. APIs & Services 사이드바에서 Credentials를 클릭합니다.

3. Create credentials를 클릭하여 만들 수 있는 자격 증명 목록을 표시합니다.

   

4. OAuth client ID를 선택합니다.

5. Application type으로 Web application을 선택하고 애플리케이션 이름을 입력합니다.

6. Authorized redirect URIs에서 Add URI를 클릭합니다.

7. 리다이렉트 URI를 Teleport 클러스터 주소로 설정한 다음 URI에 /v1/webapi/oidc/callback을 추가합니다. 여러 공개 주소를 가진 셀프 호스팅 클러스터가 있는 경우 이 주소가 첫 번째로 나열된 것을 가리키도록 합니다:

   

8. Create를 클릭합니다.

9. 만든 OAuth 클라이언트에서 Client ID와 Client secret을 복사하거나 Download JSON을 클릭하여 이 정보를 저장한 다음 OK를 클릭합니다.

   JSON을 클릭하여 클라이언트 식별자와 클라이언트 시크릿을 저장하도록 선택하면 이 JSON 파일은 인증 자격 증명을 처리하는 데 사용되는 파일이 아님에 유의하세요. 두 번째 JSON 파일은 OAuth 클라이언트에 대한 서비스 계정을 만들 때 생성됩니다.

   예를 들어:

   

서비스 계정 만들기#

서비스 계정을 만들려면:

1. Google Cloud console 사이드바에서 IAM & admin을 클릭한 다음 Service Accounts를 선택합니다.

2. Create service account를 클릭합니다.

3. 서비스 계정 이름과 선택적으로 서비스 계정의 용도에 대한 설명을 입력합니다.

4. Create and continue를 클릭한 다음 Done을 클릭합니다.

   

   Done을 클릭하면 새 서비스 계정이 현재 프로젝트의 서비스 계정 목록에 추가됩니다. 새로 만든 계정을 클릭하여 세부 정보를 보고 계정 정보를 편집할 수 있습니다.

5. 새 서비스 계정을 클릭하여 세부 정보를 표시하고 나중에 사용할 Unique ID를 복사합니다.

   

6. Keys를 클릭하고 Add key를 클릭하고 Create new key를 선택하여 서비스 계정에 대한 키를 만듭니다.

   

7. Key type으로 JSON을 선택한 다음 Create를 클릭합니다.

   Google Cloud는 다음과 유사한 서비스 계정 키가 포함된 JSON 파일을 자동으로 다운로드합니다:

   {
      "type": "service_account",
      "project_id": "teleport-project-xxxxxx",
      "private_key_id": "f06e000000000000000dc18",
      "private_key": "-----BEGIN PRIVATE KEY-----\n0000000000000w==\n-----END PRIVATE KEY-----\n",
      "client_email": "g-w-sso@teleport-project-xxxxxx.iam.gserviceaccount.com",
      "client_id": "11xxxxxxxxxxxxx76",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://oauth2.googleapis.com/token",
      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
      "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/gwsso%40teleport-project-xxxxxx.iam.gserviceaccount.com",
      "universe_domain": "googleapis.com"
    }
   

   이 파일은 Teleport Auth Service를 실행하는 호스트의 로컬 파일을 참조하거나 커넥터 리소스를 만드는 명령어에 내용을 포함하여 Teleport Auth Service가 사용하도록 OIDC 커넥터를 구성하는 데 사용됩니다.

도메인 전체 위임 구성#

Teleport가 사용할 서비스 계정이 있으므로 서비스 계정에 대한 도메인 전체 위임을 구성할 수 있습니다.

위임을 구성하려면:

1. Google Workspace Admin console을 열고 도메인 전체 위임 관리로 이동합니다.

2. Add new를 클릭합니다.

3. 서비스 계정에서 복사한 숫자 Unique ID를 붙여넣습니다.

4. Google Workspace 에디션에 따라 다음 범위 중 하나를 추가합니다:

   • 직접 그룹만의 경우: https://www.googleapis.com/auth/admin.directory.group.readonly
   • 직접 및 전이적 그룹 멤버십 지원의 경우: https://www.googleapis.com/auth/cloud-identity.groups.readonly

5. Authorize를 클릭합니다.

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

이 섹션에서는 Teleport가 Google Workspace와 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 커넥터 구성#

Google Workspace를 준비한 후 tctl sso configure oidc 명령을 실행하여 OIDC 커넥터를 만들 수 있습니다. Teleport 클러스터 배포 방식에 따라 두 가지 방법 중 하나로 OIDC 커넥터 리소스를 만들 수 있습니다:

• 커넥터 리소스에 서비스 계정 정보를 임베드할 수 있습니다.
• Teleport Auth Service를 실행하는 호스트에 서비스 계정 JSON 파일을 업로드할 수 있습니다.

서비스 계정 JSON은 고가용성 클러스터로 Teleport를 배포하는 경우 모든 Teleport Auth Service 호스트에서 사용 가능해야 합니다. 대부분의 경우 여러 서버의 파일에 자격 증명을 저장하지 않도록 고가용성 및 클라우드 배포에서 임베드된 JSON 방법을 사용하여 커넥터를 만들어야 합니다.

임베드된 JSON으로 OIDC 커넥터를 만드는 대신 JSON 파일을 업로드하는 방법도 있습니다. 셀프 호스팅 Teleport 클러스터가 있는 경우 Teleport Auth Service를 실행하는 모든 호스트에 서비스 계정 JSON 파일을 업로드할 수 있습니다.

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

$ tctl sso configure oidc --preset google --id 


콜백 주소 변경

The callback address can be changed if calling back to a remote machine
instead of the local machine is required:
# --bind-addr sets the host and port tsh will listen on, and --callback changes
# what link is displayed to the user
$ tsh login --proxy=proxy.example.com --auth=github --bind-addr=localhost:1234 --callback https://remote.machine:1234

For this to work the hostname or CIDR of the remote machine that will be used for
the callback will need to be allowed via your auth connector's client_redirect_settings:
kind: oidc
metadata:
  name: example-connector
spec:
  client_redirect_settings:
    # a list of hostnames allowed for HTTPS client redirect URLs
    # can be a regex pattern
    allowed_https_hostnames:
      - remote.machine
      - '*.app.github.dev'
      - '^\d+-[a-zA-Z0-9]+\.foo.internal$'
    # a list of CIDRs allowed for HTTP or HTTPS client redirect URLs
    insecure_allowed_cidr_ranges:
      - '192.168.1.0/24'
      - '2001:db8::/96'



커넥터 테스트#
커넥터를 테스트하려면 다음 명령을 실행합니다:
$ cat gworkspace-connector.yaml | tctl sso test

이 명령은 브라우저를 열고 Google을 사용하여 Teleport 클러스터에 로그인하려고 합니다. 실패하면 문제 해결 정보를 위해 명령 출력을 검토합니다.
커넥터 만들기#
tctl 도구를 사용하여 커넥터를 만들려면 다음 명령을 실행합니다:
$ tctl create -f gworkspace-connector.yaml

커넥터를 만들면 Teleport 웹 UI에 새 로그인 옵션 Login with Google이 표시됩니다. 커맨드라인에서 로그인하려면:
$ tsh --proxy=proxy.example.com login --auth=google

이 명령은 싱글 사인온 엔드포인트 URL을 표시하고 브라우저에서 자동으로 열려고 합니다.
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.

문제 해결#

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.

추가 참고 자료#

Google Workspace Cloud Identity API
Google Workspace Directory API
중첩된 Google Workspace 그룹 작동 방식

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

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

groups,admins,auditor,editor

$ tctl sso configure oidc --preset google --id 


콜백 주소 변경

The callback address can be changed if calling back to a remote machine
instead of the local machine is required:
# --bind-addr sets the host and port tsh will listen on, and --callback changes
# what link is displayed to the user
$ tsh login --proxy=proxy.example.com --auth=github --bind-addr=localhost:1234 --callback https://remote.machine:1234

For this to work the hostname or CIDR of the remote machine that will be used for
the callback will need to be allowed via your auth connector's client_redirect_settings:
kind: oidc
metadata:
  name: example-connector
spec:
  client_redirect_settings:
    # a list of hostnames allowed for HTTPS client redirect URLs
    # can be a regex pattern
    allowed_https_hostnames:
      - remote.machine
      - '*.app.github.dev'
      - '^\d+-[a-zA-Z0-9]+\.foo.internal$'
    # a list of CIDRs allowed for HTTP or HTTPS client redirect URLs
    insecure_allowed_cidr_ranges:
      - '192.168.1.0/24'
      - '2001:db8::/96'



커넥터 테스트#
커넥터를 테스트하려면 다음 명령을 실행합니다:
$ cat gworkspace-connector.yaml | tctl sso test

이 명령은 브라우저를 열고 Google을 사용하여 Teleport 클러스터에 로그인하려고 합니다. 실패하면 문제 해결 정보를 위해 명령 출력을 검토합니다.
커넥터 만들기#
tctl 도구를 사용하여 커넥터를 만들려면 다음 명령을 실행합니다:
$ tctl create -f gworkspace-connector.yaml

커넥터를 만들면 Teleport 웹 UI에 새 로그인 옵션 Login with Google이 표시됩니다. 커맨드라인에서 로그인하려면:
$ tsh --proxy=proxy.example.com login --auth=google

이 명령은 싱글 사인온 엔드포인트 URL을 표시하고 브라우저에서 자동으로 열려고 합니다.
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.

문제 해결#

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.

추가 참고 자료#

Google Workspace Cloud Identity API
Google Workspace Directory API
중첩된 Google Workspace 그룹 작동 방식