OneLogin을 SSO 프로바이더로 사용한 Teleport 인증

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

1. 애플리케이션에 사용자를 추가합니다:

   

2. 인증 커넥터의 SAML 메타데이터를 얻습니다. 애플리케이션이 설정되면 More Actions 메뉴로 이동하여 SAML Metadata 옵션을 찾습니다:

   

   옵션을 왼쪽 클릭하여 XML 문서를 로컬 파일로 다운로드하거나 옵션을 마우스 오른쪽 버튼으로 클릭하고 링크 주소를 복사할 수 있습니다. Teleport Auth Service는 제공된 문서를 읽거나 주소를 쿼리하여 SAML 메타데이터를 얻습니다. Auth Service가 최신 정보를 사용할 수 있도록 주소를 복사하는 것을 권장합니다.

2/3단계. OneLogin을 Teleport에 연결#

이 섹션에서는 Teleport가 OneLogin과 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:

SAML 커넥터 구성#

tctl을 사용하여 SAML 커넥터를 만듭니다. 를 이전 단계에서 복사한 XML 문서의 URL로 업데이트합니다. XML 문서를 대신 다운로드했다면 XML 메타데이터 파일의 경로를 사용합니다:

$ tctl sso configure saml --preset onelogin \
--entity-descriptor  \
--attributes-to-roles  \
--attributes-to-roles  > onelogin.yaml

이렇게 하면 커넥터 리소스를 설명하는 onelogin.yaml이 만들어집니다:

<div class="admonition note"><div class="admonition-title">Note</div><p>이 섹션의 내용은 원문 문서를 참조하세요. (<code>onelogin-connector.yaml</code>)</p></div>

커넥터 테스트#

새로 만든 구성을 테스트합니다:

$ cat onelogin.yaml | tctl sso test

tctl sso test는 브라우저를 열고 OneLogin으로 인증을 시도합니다. 성공하면 출력에 수신된 SAML 속성과 Teleport 역할에 매핑된 내용이 출력됩니다. 테스트가 실패하면 출력이 구성 문제 해결을 도와줍니다.

커넥터 만들기#

tctl 도구를 사용하여 커넥터를 만듭니다:

$ tctl create -f onelogin.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.