이 가이드는 SAML 인증 커넥터로 특정 사용자 그룹에게 자격 증명을 발급하도록 Keycloak을 구성하는 방법을 설명합니다. 역할 기반 접근 제어(RBAC)와 함께 사용하면 Teleport 관리자가 다음과 같은 정책을 정의할 수 있습니다:

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

다음 단계는 Keycloak 그룹과 일치하는 예제 SAML 인증 커넥터를 구성합니다. 다른 옵션을 구성하도록 선택할 수 있습니다.

작동 방식#

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

사전 요구 사항#

시작하기 전에 다음이 필요합니다:

• realm과 관리 작업을 수행하기 위해 Keycloak Admin Console에 대한 관리자 계정.
• 마스터 realm이 아닌 다른 realm에 있어야 합니다.
• realm 디렉터리에 하나 이상의 사용자가 등록되어 있어야 합니다.
• realm 디렉터리에 최소 두 그룹을 만들고 각 그룹에 하나 이상의 사용자를 할당해야 합니다.
• 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단계. Keycloak 구성#

SAML 클라이언트 만들기#

1. SAML 통합에 사용할 realm을 선택합니다. 메뉴에서 Clients를 클릭합니다.

2. Create client를 클릭합니다.

   

3. Client type을 SAML로 설정하고 Teleport Proxy Service URL의 URL로 Client ID를 설정합니다.

   https:///v1/webapi/saml/acs/keycloak
   

   

4. Valid Redirect URIs 필드를 Teleport Proxy Service 호스트의 URL로 설정합니다. 여러 공개 주소를 가진 셀프 호스팅 클러스터가 있는 경우 이 주소가 첫 번째로 나열된 것을 가리키도록 합니다:

   https:///v1/webapi/saml/acs/keycloak
   

   

   다음 단계로 진행하기 전에 Save를 클릭합니다.

SAML 어설션 매핑 구성#

1. 왼쪽 사이드바에서 Clients로 이동합니다.

2. Teleport SAML 클라이언트를 선택하고 Client Scope 탭으로 이동합니다.

3. Client Scopes 탭에서 Teleport 클라이언트 범위를 클릭합니다.

   

4. Mappers 탭에서 Configure a new mapper를 클릭합니다.

   

5. 속성 매핑 목록에서 Groups list를 선택합니다.

   

6. 아래 이미지와 같이 값을 채우고 Save를 클릭합니다.

   

7. User Attribute 매퍼를 추가하기 위해 1~6단계를 반복합니다.

   

8. 아래 이미지와 같이 값을 채우고 Save를 클릭합니다.

   

   이렇게 하면 Teleport 역할 내에서 {{external.username}} 속성으로 사용자 이름을 사용할 수 있습니다.

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

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

Keycloak 그룹을 사용하여 역할 매핑을 정의하는 경우 그룹 이름에 명시적 선행 /를 포함해야 합니다.

SAML 커넥터 구성#

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

$ tctl sso configure saml --name keycloak \
--entity-descriptor https://<root>/realms/{realm-name}/protocol/saml/descriptor \
--attributes-to-roles  \
--attributes-to-roles  \
--audience https://mytenant.teleport.sh/v1/webapi/saml/acs/keycloak \
--acs https://mytenant.teleport.sh/v1/webapi/saml/acs/keycloak > keycloak-connector.yaml

위의 예제에서:

• --entity-descriptor는 앱 페더레이션 메타데이터 URL을 지정합니다.
• --acs는 성공적인 인증 후 SAML 프로바이더가 콜백하는 위치를 지정합니다.
• --audience는 서비스 프로바이더(Teleport)를 고유하게 식별합니다.

keycloak-connector.yaml 파일은 이제 다음과 유사해야 합니다:

kind: saml
metadata:
  name: keycloak
spec:
  acs: https://mytenant.teleport.sh/v1/webapi/saml/acs/keycloak
  attributes_to_roles:
  - name: groups
    roles:
    - editor
    - auditor
    value: /admins
  - name: groups
    roles:
    - access
    value: /devs
  audience: https://mytenant.teleport.sh/v1/webapi/saml/acs/keycloak
  cert: ""
  display: ""
  entity_descriptor: ""
  entity_descriptor_url: https://<root>/realms/{realm-name}/protocol/saml/descriptor
  issuer: ""
  service_provider_issuer: https://mytenant.teleport.sh/v1/webapi/saml/acs/keycloak
  sso: ""
version: v2

선택적으로 인증 커넥터를 테스트하려면 SAML 클라이언트의 Keys 탭으로 이동하여 Client signature required 옵션을 일시적으로 비활성화합니다. 이 가이드를 진행하면서 나중 단계에서 활성화됩니다.

커넥터 테스트#

클러스터에 커넥터가 있으면 tctl로 테스트할 수 있습니다:

$ cat keycloak-connector.yaml | tctl sso test

브라우저가 열리고 Keycloak 사용자 자격 증명을 사용하여 Teleport 클러스터에 로그인합니다. 문제가 있는 경우 CLI 출력이 커넥터 구성 디버깅을 도와줍니다.

tctl 도구를 사용하여 커넥터를 만들려면 다음 명령을 실행합니다:

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

클라이언트 인증서 서명 검증(권장)#

Client Signature Required가 활성화되면 클라이언트에서 오는 문서에 서명이 필요합니다. Keycloak은 Keys 탭에 설정된 클라이언트 공개 키나 인증서를 사용하여 이 서명을 검증합니다.

Keycloak이 Teleport에서 클라이언트 서명 검증을 요청하도록 하려면 키를 생성하고 Keycloak에 가져와서 서명 키를 구성해야 합니다. 클라이언트는 SAML 요청과 응답에 서명하고 서명이 검증됩니다.

서명을 위한 개인 키 만들기#

• 먼저 개인 키와 인증서를 생성합니다.

$ openssl genrsa -out priv.pem 2048
$ openssl req -new -x509 -key priv.pem -out cert.pem

• 방금 생성한 인증서(PEM 형식)를 PKCS#12 형식으로 변환합니다.

openssl pkcs12 -in cert.pem -name teleport -export -out cert.pkcs12

Keycloak에 인증서를 가져올 때 사용할 name과 정의된 export password를 기록해 두세요.

$ tctl edit saml/keycloak

Teleport가 signing_key_pair를 생성했음을 알 수 있습니다. 이 키 쌍은 응답에 서명하는 데 사용됩니다.

kind: saml
metadata:
  name: keycloak
spec:
  acs: https://mytenant.teleport.sh/v1/webapi/saml/acs/keycloak
  attributes_to_roles:
  - name: groups
    roles:
    - editor
    - auditor
    value: /admins
  - name: groups
    roles:
    - access
    value: /devs
  audience: https://mytenant.teleport.sh/v1/webapi/saml/acs/keycloak
  cert: ""
  display: Keycloak
  entity_descriptor:
  entity_descriptor_url: https://<root>/realms/{realm-name}/protocol/saml/descriptor
  issuer: https://<root>/realms/{realm-name}
  service_provider_issuer: https://mytenant.teleport.sh/v1/webapi/saml/acs/keycloak
  signing_key_pair:
    cert: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
  sso: https://<root>/realms/{realm-name}/protocol/saml
version: v2

cert.pkcs12의 데이터를 사용하여 assertion_key_pair를 추가합니다.

편집 후 파일은 다음과 같이 보일 것입니다:

kind: saml
metadata:
  name: keycloak
spec:
  acs: https://mytenant.teleport.sh/v1/webapi/saml/acs/keycloak
  attributes_to_roles:
  - name: groups
    roles:
    - editor
    - auditor
    value: /admins
  - name: groups
    roles:
    - access
    value: /devs
  audience: https://mytenant.teleport.sh/v1/webapi/saml/acs/keycloak
  cert: ""
  display: Keycloak
  entity_descriptor:
  entity_descriptor_url: https://<root>/realms/{realm-name}/protocol/saml/descriptor
  issuer: https://<root>/realms/{realm-name}
  service_provider_issuer: https://mytenant.teleport.sh/v1/webapi/saml/acs/keycloak
  assertion_key_pair:
    cert: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
  signing_key_pair:
    cert: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
  sso: https://<root>/realms/{realm-name}/protocol/saml
version: v2

편집기에서 파일을 저장하고 닫아 커넥터를 업데이트합니다.

클라이언트 서명 검증 활성화#

• 왼쪽 사이드바에서 Clients로 이동합니다.

• Teleport SAML 클라이언트를 선택합니다.

• Keys 탭으로 이동하여 "Client Signature Required"를 활성화합니다.

  

• 변환된 cert.pkcs12 인증서를 가져옵니다.

  

  인증서를 Key Alias 및 Store Password로 변환할 때 정의한 올바른 name과 password를 입력해야 합니다.

• Confirm을 클릭하여 활성화합니다.

이 커넥터로 SSO 로그인이 성공하면 클라이언트 서명 검증이 작동하는 것입니다.

다음 단계#

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.

서명 검증 비호환성#

적절한 서명 키로 "Client signature required"가 활성화되면 아래 이미지와 같이 유효하지 않은 요청자 오류가 발생합니다.

Keycloak 서버 로그에는 error=invalid_signature 및 request validation failed: org.keycloak.common.VerificationException: SigAlg was null 오류가 포함됩니다.

이는 Keycloak이 서명 검증 예상을 충족하지 않는 SAML 요청을 받을 때 발생하여 Keycloak이 SAML 서명을 검증하려고 할 때 실패합니다.

문제를 해결하려면:

• 클라이언트 인증서 서명 검증 섹션을 참조하여 인증서 구성을 검토합니다. 인증서가 최신 상태인지 개인 키가 올바르게 쌍을 이루고 있는지 확인합니다.
• 위의 사항이 확인되면 Keycloak 엄격한 서명 요구 사항에 맞게 Keycloak 인증 커넥터에 spec.provider: ping 파라미터를 일시적으로 추가합니다.