액세스 요청 플러그인 구축 방법 | Teleport 공식 기술 문서 한국판 by 인포그랩

액세스 요청 플러그인 구축 방법

Teleport의 액세스 요청을 사용하면 기본적으로 Teleport 사용자를 특권이 더 낮은 역할에 할당하고, 일시적으로 그들의 특권을 상승시키도록 허용할 수 있습니다. 검토자는 조직의 기존 커뮤니케이션 워크플로(예: Slack, 이메일, PagerDuty)를 통해 액세스 요청을 승인하거나 거부할 수 있으며, 이는 액세스 요청 플러그인을 사용하여 가능합니다.

Teleport의 API 클라이언트 라이브러리를 사용하여 조직의 고유한 워크플로와 통합된 액세스 요청 플러그인을 구축할 수 있습니다.

이 가이드에서는 Google Sheets를 통해 액세스 요청을 관리할 수 있는 플러그인을 작성하는 방법을 보여 주어 Teleport의 API 클라이언트 라이브러리의 여러 가지를 탐구할 것입니다. 플러그인은 새로운 액세스 요청을 Google Sheets 스프레드시트에 목록으로 표시하고 각 요청을 허용하거나 거부할 수 있는 링크를 제공합니다.

이번 가이드에서 구축할 플러그인은 학습 도구로 의도되었습니다. 생산 Teleport 클러스터에 연결하지 마십시오. 대신 데모 클러스터를 사용하십시오.

전제 조건

실행 중인 Teleport 클러스터. Teleport를 시작하려면 가입하기 무료 체험판을 이용해 보세요.
tctl 관리 도구 및 tsh 클라이언트 도구 버전 >= 16.2.0.

tctl 및 tsh 다운로드 방법에 대한 지침은 설치를 방문하세요.

워크스테이션에 설치된 Go 버전1.22+. Go 다운로드 페이지를 참조하십시오. 이 가이드를 완료하는 데 Go에 대한 이해는 필요하지 않지만, 본인의 액세스 요청 플러그인을 구축하려면 Go 지식이 필요합니다.

데모 플러그인을 설정하려면 Google Sheets API에 인증해야 하므로 다음이 필요합니다:

서비스 계정을 생성할 수 있는 권한이 있는 Google Cloud 프로젝트.
Google Sheets 스프레드시트를 생성하는 데 사용할 Google 계정. 플러그인에 사용할 서비스 계정에 편집 권한을 부여할 것입니다.

Tip

데모 프로젝트를 설정할 계획이 없더라도 이 가이드를 따라 액세스 요청 플러그인을 개발하는 데 사용할 수 있는 라이브러리, 유형 및 함수를 확인할 수 있습니다.

데모는 최소한의 작동 예제로, GitHub의 gravitational/teleport 저장소에서 완전한 플러그인을 확인할 수 있습니다.

1단계/5. Go 프로젝트 설정

최소 액세스 요청 플러그인의 소스 코드를 다운로드하십시오:

git clone https://github.com/gravitational/teleport -b branch/v16
cd teleport/examples/access-plugin-minimal

이 가이드의 나머지 부분에서는 이 플러그인을 설정하는 방법을 보여주고 플러그인이 액세스 요청과 특정 워크플로를 어떻게 통합하는지 탐색할 것입니다.

2단계/5. Google Sheets API 설정

액세스 요청 플러그인은 일반적으로 두 개의 API와 통신합니다. Teleport Auth Service의 gRPC API로부터 액세스 요청 이벤트를 수신하고, 선택한 메시징 또는 협업 도구의 API와 상호작용하는 데 이 데이터를 사용합니다.

이 섹션에서는 Google Sheets API를 활성화하고, 플러그인을 위한 Google Cloud 서비스 계정을 생성하며, 해당 서비스 계정을 사용하여 Google Sheets에 인증합니다.

Google Sheets API 활성화

아래의 Google Cloud 콘솔 URL을 방문하여 Google Sheets API를 활성화하십시오:

https://console.cloud.google.com/apis/enableflow?apiid=sheets.googleapis.com

사용하려는 Google Cloud 프로젝트인지 확인하십시오.

클릭하여 다음 > 활성화합니다.

플러그인을 위한 Google Cloud 서비스 계정 생성

아래의 Google Cloud 콘솔 URL을 방문하십시오:

https://console.cloud.google.com/iam-admin/serviceaccounts

서비스 계정 생성을 클릭하십시오.

서비스 계정 이름에 "Teleport Google Sheets Plugin"을 입력하십시오. Google Cloud가 서비스 계정 ID 필드를 자동으로 채워줍니다.

생성 및 계속을 클릭합니다. 서비스 계정에 역할을 부여하라는 메시지가 표시되면 계속을 클릭합니다. 역할 없이 서비스 계정을 생성합니다. 사용자에게 서비스 계정에 대한 액세스를 부여하는 단계를 건너뛰고 완료를 클릭합니다.

콘솔이 서비스 계정 보기로 이동합니다. 방금 생성한 서비스 계정의 이름을 클릭한 다음 키 탭을 클릭하십시오. 키 추가를 클릭한 다음 새 키 만들기를 클릭합니다. 키 유형을 "JSON"으로 두고 생성을 클릭합니다.

Google Cloud 자격 증명 파일을 credentials.json으로 저장하십시오. 이 파일은 Go 프로젝트 디렉터리에 위치해야 합니다.

플러그인은 Google Sheets에 인증하기 위해 이 JSON 파일을 사용할 것입니다.

Google Sheets 스프레드시트 생성

다음 URL을 방문하고 올바른 사용자로 인증되었는지 확인하십시오:

https://sheets.new

스프레드시트의 이름을 지정합니다.

플러그인에 스프레드시트에 대한 액세스를 제공하려면 공유를 클릭합니다. 사람 및 그룹 추가 필드에 teleport-google-sheets-plugin@PROJECT_NAME.iam.gserviceaccount.com을 입력하며, 여기서 PROJECT_NAME을 프로젝트 이름으로 바꿉니다. 서비스 계정이 "편집자" 권한을 갖도록 해야 합니다. 공유를 클릭한 후 경고 메시지가 표시되면 어쨌든 공유를 클릭합니다.

플러그인이 생성한 서비스 계정을 사용하여 Google Sheets에 인증하면 스프레드시트를 수정할 수 있는 액세스 권한이 부여됩니다.

다음으로, 스프레드시트가 다음과 같도록 확인해야 합니다:

시트는 하나만 존재해야 합니다.
시트에는 다음 열이 포함되어야 합니다:

ID	생성됨	사용자	역할	상태	링크

액세스 요청 플러그인을 작성한 후 스프레드시트는 데이터를 자동으로 채워 넣습니다.

3단계/5. Teleport RBAC 설정

이 섹션에서는 액세스 요청을 생성하고 검토할 수 있는 Teleport 역할을 설정하며, 액세스 요청 플러그인이 Teleport에 인증하는 자격 증명을 생성할 수 있는 다른 Teleport 역할을 설정합니다.

플러그인을 위한 사용자와 역할 생성

Teleport의 Access Request 플러그인은 Access Requests를 나열하고 읽을 수 있는 권한을 가진 사용자로 Teleport 클러스터에 인증합니다. 이렇게 하면 플러그인이 Teleport Auth Service에서 Access Requests를 검색하고 이를 검토자에게 제시할 수 있습니다.

access-plugin이라는 사용자 및 역할을 정의하려면 access-plugin.yaml이라는 파일에 다음 내용을 추가합니다:

kind: role
version: v5
metadata:
  name: access-plugin
spec:
  allow:
    rules:
      - resources: ['access_request']
        verbs: ['list', 'read']
      - resources: ['access_plugin_data']
        verbs: ['update']
---
kind: user
metadata:
  name: access-plugin
spec:
  roles: ['access-plugin']
version: v2

사용자와 역할을 생성합니다:

tctl create -f access-plugin.yaml

As with all Teleport users, the Teleport Auth Service authenticates the
access-plugin 사용자를 발급하는 짧은 수명의 TLS 자격 증명을 통해 인증합니다. 이 경우, 우리는 임시 사용자를 통해
access-plugin 역할 및 사용자를 가장하여 자격 증명을 수동으로 요청해야 합니다.

자체 호스팅 Teleport Enterprise 배포를 실행하고 Auth Service 호스트에서
tctl을 사용하는 경우, 이미 임시 권한이 있습니다.

access-plugin에 대한 임시 권한을 부여하려면,
access-plugin-impersonator라는 역할을 정의하며 다음 YAML 문서를
access-plugin-impersonator.yaml라는 파일에 붙여넣습니다:

kind: role
version: v5
metadata:
  name: access-plugin-impersonator
spec:
  allow:
    impersonate:
      roles:
      - access-plugin
      users:
      - access-plugin

access-plugin-impersonator 역할을 생성합니다:

tctl create -f access-plugin-impersonator.yaml

기계 ID로 플러그인에 대한 신원 파일을 제공하는 경우,
기계 ID 봇 사용자에게 access-plugin 역할을 부여하십시오. 그렇지 않으면,
access-plugin 역할 및 사용자에 대한 자격 증명을 생성하는 데 사용할 사용자에게 이 역할을 부여하십시오:

access-plugin-impersonator 역할을 Teleport 사용자에게 할당하려면 인증 제공자에 맞는 적절한 명령어를 실행하세요:

로컬 사용자의 역할을 콤마로 구분된 목록으로 가져옵니다:
```
ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')
```

로컬 사용자를 편집하여 새로운 역할을 추가합니다:

tctl users update $(tsh status -f json | jq -r '.active.username') \  --set-roles "${ROLES?},access-plugin-impersonator"

Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

github 인증 커넥터를 가져옵니다:
```
tctl get github/github --with-secrets > github.yaml
```
--with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 github.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 github.yaml 파일을 제거해야 합니다.
github.yaml을 편집하고 teams_to_roles 섹션에 access-plugin-impersonator을 추가합니다.

이 역할에 매핑할 팀은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 하지만 팀에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 팀이어야 합니다.

여기에 예시가 있습니다:
```
  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - access-plugin-impersonator
```
변경 사항을 적용합니다:
```
tctl create -f github.yaml
```
Teleport 클러스터에서 로그아웃한 후 새로운 역할을 assum 하기 위해 다시 로그인합니다.

saml 구성 리소스를 가져옵니다:
```
tctl get --with-secrets saml/mysaml > saml.yaml
```
--with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 saml.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 saml.yaml 파일을 제거해야 합니다.
saml.yaml을 편집하고 attributes_to_roles 섹션에 access-plugin-impersonator을 추가합니다.

이 역할에 매핑할 속성은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 그러나 그룹에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 그룹이어야 합니다.

여기에 예시가 있습니다:
```
  attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - access-plugin-impersonator
```
변경 사항을 적용합니다:
```
tctl create -f saml.yaml
```
Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

oidc 구성 리소스를 가져옵니다:
```
tctl get oidc/myoidc --with-secrets > oidc.yaml
```
--with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 oidc.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 oidc.yaml 파일을 제거해야 합니다.
oidc.yaml을 편집하고 claims_to_roles 섹션에 access-plugin-impersonator을 추가합니다.

이 역할에 매핑할 클레임은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 그러나 그룹에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 그룹이어야 합니다.

여기에 예시가 있습니다:
```
  claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - access-plugin-impersonator
```
변경 사항을 적용합니다:
```
tctl create -f oidc.yaml
```
Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

이제 access-plugin 역할 및 사용자의 서명된 인증서를 생성할 수 있습니다.

액세스 플러그인 신원 내보내기

플러그인이 Teleport 클러스터에 연결하기 위해 필요한 자격 증명을 요청하려면 tctl auth sign 명령어를 사용합니다.

아래의 tctl auth sign 명령은 access-plugin 사용자를 대리하여 서명된 자격 증명을 생성하고, 로컬 디렉토리에 신원 파일을 작성합니다:

tctl auth sign --user=access-plugin --out=auth.pem

Teleport의 액세스 요청 플러그인은 Teleport Auth Service의 gRPC 엔드포인트에 TLS를 통해 연결함으로써 새로운 액세스 요청을 수신하고 업데이트합니다.

신원 파일 auth.pem에는 TLS 및 SSH 자격 증명이 모두 포함되어 있습니다. 액세스 요청 플러그인은 SSH 자격 증명을 사용하여 Proxy Service에 연결하고, 이는 Auth Service에 대한 역 터널 연결을 설정합니다. 플러그인은 이 역 터널과 TLS 자격 증명을 사용하여 Auth Service의 gRPC 엔드포인트에 연결합니다.

나중에 플러그인을 구성할 때 이 파일을 참조할 것입니다.

역할 액세스 요청 설정

이 가이드에서는 플러그인을 사용하여 역할 액세스 요청을 관리합니다. 이를 위해 클러스터에서 역할 액세스 요청을 설정합니다.

For the purpose of this guide, we will define an editor-requester role, which
can request the built-in editor role, and an editor-reviewer role that can
review requests for the editor role.

editor-request-rbac.yaml라는 파일을 생성하고 다음 내용을 추가하세요:

kind: role  
version: v5  
metadata:  
  name: editor-reviewer  
spec:  
  allow:  
    review_requests:  
      roles: ['editor']  
---  
kind: role  
version: v5  
metadata:  
  name: editor-requester  
spec:  
  allow:  
    request:  
      roles: ['editor']  
      thresholds:  
        - approve: 1  
          deny: 1

정의한 역할을 생성하세요:

tctl create -f editor-request-rbac.yaml
role 'editor-reviewer' has been created  role 'editor-requester' has been created

editor-requester 역할을 가진 사용자들로부터 요청을 검토할 수 있도록
editor-reviewer 역할을 자신의 계정에 할당하세요.

editor-reviewer 역할을 Teleport 사용자에게 할당하려면 인증 제공자에 맞는 적절한 명령어를 실행하세요:

로컬 사용자의 역할을 콤마로 구분된 목록으로 가져옵니다:
```
ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')
```

로컬 사용자를 편집하여 새로운 역할을 추가합니다:

tctl users update $(tsh status -f json | jq -r '.active.username') \  --set-roles "${ROLES?},editor-reviewer"

Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

github 인증 커넥터를 가져옵니다:
```
tctl get github/github --with-secrets > github.yaml
```
--with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 github.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 github.yaml 파일을 제거해야 합니다.
github.yaml을 편집하고 teams_to_roles 섹션에 editor-reviewer을 추가합니다.

이 역할에 매핑할 팀은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 하지만 팀에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 팀이어야 합니다.

여기에 예시가 있습니다:
```
  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - editor-reviewer
```
변경 사항을 적용합니다:
```
tctl create -f github.yaml
```
Teleport 클러스터에서 로그아웃한 후 새로운 역할을 assum 하기 위해 다시 로그인합니다.

saml 구성 리소스를 가져옵니다:
```
tctl get --with-secrets saml/mysaml > saml.yaml
```
--with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 saml.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 saml.yaml 파일을 제거해야 합니다.
saml.yaml을 편집하고 attributes_to_roles 섹션에 editor-reviewer을 추가합니다.

이 역할에 매핑할 속성은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 그러나 그룹에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 그룹이어야 합니다.

여기에 예시가 있습니다:
```
  attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - editor-reviewer
```
변경 사항을 적용합니다:
```
tctl create -f saml.yaml
```
Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

oidc 구성 리소스를 가져옵니다:
```
tctl get oidc/myoidc --with-secrets > oidc.yaml
```
--with-secrets 플래그는 spec.signing_key_pair.private_key의 값을 oidc.yaml 파일에 추가합니다. 이 키는 민감한 값을 포함하고 있기 때문에, 리소스를 업데이트한 후 즉시 oidc.yaml 파일을 제거해야 합니다.
oidc.yaml을 편집하고 claims_to_roles 섹션에 editor-reviewer을 추가합니다.

이 역할에 매핑할 클레임은 귀하의 조직에서 어떻게 역할 기반 접근 제어(RBAC)를 설계했느냐에 따라 달라집니다. 그러나 그룹에는 귀하의 사용자 계정이 포함되어야 하며, 조직 내에서 가능한 한 작은 그룹이어야 합니다.

여기에 예시가 있습니다:
```
  claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - editor-reviewer
```
변경 사항을 적용합니다:
```
tctl create -f oidc.yaml
```
Teleport 클러스터에서 로그아웃한 후 새로운 역할을 asum 하기 위해 다시 로그인합니다.

editor-requester 역할을 가진 사용자 myuser를 생성하세요. 이 사용자는
editor 역할을 요청하지 않는 한 클러스터 구성을 편집할 수 없습니다:

tctl users add myuser --roles=editor-requester

tctl은 터미널에 초대 URL을 출력할 것입니다. URL을 방문하고
myuser로 처음 로그인하여 Teleport 클러스터에 대해 설정된 자격 증명을 등록하세요.

이 가이드의 후반부에서 myuser가 editor 역할을 요청할 것이며,
이를 통해 요청을 검토할 수 있습니다.

4단계/5. 액세스 요청 플러그인 작성

이 단계에서는 examples/access-plugin-minimal/main.go에 있는 액세스 요청 플러그인의 구조를 안내합니다. 여기의 예제를 사용하여 자신의 액세스 요청 플러그인을 작성할 수 있습니다.

임포트

액세스 요청 플러그인이 Go 표준 라이브러리에서 임포트할 패키지는 다음과 같습니다:

패키지	설명
`context`	`context.Context` 유형 포함. `context.Context`는
장기 실행 루틴을 제어하기 위한 추상화로, 실패하거나 시간 초과가 발생할 수 있는
외부 서비스에 대한 연결을 포함합니다. 프로그램은 컨텍스트를 취소하거나
타임아웃 및 메타데이터를 할당할 수 있습니다.
`errors`	오류 처리.
`fmt`	데이터를 출력, 문자열 또는 오류 형식으로 지정.
`strings`	문자열 조작.

플러그인은 다음의 서드파티 코드를 임포트합니다:

패키지	설명
`github.com/gravitational/teleport/api/client`	Auth Service의
gRPC API에 인증하고 요청을 하는 라이브러리.
`github.com/gravitational/teleport/api/types`	Auth Service API에서 사용되는
유형, 예: 액세스 요청.
`github.com/gravitational/trace`	표준 라이브러리보다 더 유용한 세부 사항으로
오류를 표현.
`google.golang.org/api/option`	Google API 클라이언트 구성 설정.
`google.golang.org/api/sheets/v4`	Google Sheets API 클라이언트 라이브러리,
프로그램에서 `sheets`로 별칭 설정.
`google.golang.org/grpc`	gRPC 클라이언트 및 서버 라이브러리.

구성

먼저, 환경에 대해 구성해야 할 두 개의 상수를 선언합니다:

(!examples/access-plugin-minimal/config.go!)

proxyAddr는 Teleport Proxy Service 또는 Teleport Enterprise Cloud 테넌트의 호스트 이름과 포트를 나타냅니다. 예를 들어 mytenant.teleport.sh:443으로 설정합니다.

spreadSheetID는 이전에 생성한 스프레드시트의 ID로 설정합니다. 스프레드시트 ID를 찾으려면 Google Drive에서 스프레드시트를 방문하십시오. ID는 아래의 URL 경로 세그먼트의 SPREADSHEET_ID 부분에 있습니다:

https://docs.google.com/spreadsheets/d/SPREADHSEET_ID/edit#gid=0

`AccessRequestPlugin` 유형

plugin.go 파일에서는 액세스 요청 플러그인 코드를 조직하는 데 사용할 유형을 선언합니다:

(!examples/access-plugin-minimal/plugin.go!)

AccessRequestPlugin 유형은 일반 액세스 요청 플러그인을 나타내며, 이 유형을 사용하여 자신의 플러그인을 구축할 수 있습니다. 이 유형은 Teleport API 클라이언트와 EventHandler, 즉 HandleEvent 메서드를 구현하는 모든 Go 유형을 포함합니다.

우리 경우에는 HandleEvent를 구현하는 유형은 Google Sheets API 클라이언트를 포함하는 구조체 유형인 googleSheetsClient입니다.

행 데이터 준비

스프레드시트에 새로운 행을 만들거나 기존 행을 업데이트할 때, 액세스 요청에서 데이터를 추출하여 Google Sheets에 제공하는 방법이 필요합니다. 이를 makeRowData 메서드로 해결합니다:

(!examples/access-plugin-minimal/makerowdata.go!)

Sheets.RowData 유형은 문자열에 대한 포인터를 광범위하게 사용하므로, 제공된 문자열에 대한 포인터를 반환하는 유틸리티 함수 stringPtr을 도입하여 sheets.RowData의 셀 값 할당을 함수 호출 체인을 사용하여 더 쉽게 진행합니다.

makeRowData는 googleSheetsClient 유형의 메서드입니다. (*가 googleSheetsClient 앞에 위치하는 이유는 메서드가 googleSheetsClient에 대한 포인터를 받기 때문입니다.) 이 메서드는 Teleport의 API 라이브러리에서 액세스 요청 내의 필드를 나타내기 위해 사용하는 types.AccessRequest를 받습니다.

Google Sheets 클라이언트 라이브러리는 스프레드시트를 업데이트하기 위해 요청에 포함하는 sheets.RowData 유형을 정의합니다. 이 함수는 types.AccessRequest를 *sheets.RowData로 변환합니다(또 다른 포인터).

액세스 요청은 승인됨, 거부됨, 보류 중, 없음의 상태 중 하나를 가집니다. 요청 상태는 Teleport의 types 라이브러리에서 가져오며 requestStates 맵에서 문자열로 매핑됩니다.

데이터를 추출할 때, types.AccessRequest.GetName() 메서드를 사용하여 스프레드시트에 포함할 수 있는 문자열 형식의 액세스 요청 ID를 검색합니다.

사용자는 Teleport 웹 UI 내에서 요청 ID에 해당하는 URL을 방문하여 액세스 요청을 검토할 수 있습니다. makeRowData는 해당 URL에 대한 링크로 삽입할 수 있는 =HYPERLINK 공식을 조립합니다.

행 생성

다음 함수는 Google Sheets API에 요청을 제출하여, makeRowData에서 반환된 데이터를 사용하여 새로운 행을 생성합니다. 행 생성 시도가 실패할 경우 오류를 반환합니다:

(!examples/access-plugin-minimal/createrow.go!)

createRow는 sheets.BatchUpdateSpreadsheetRequest를 조립하고 이를 Google Sheets API에 전송하여 오류를 반환합니다.

예기치 않은 HTTP 상태 코드를 기록하되 오류를 반환하지 않는 이유는 이는 일시적인 서버 측 문제일 수 있기 때문입니다. 생산 액세스 요청 플러그인은 이러한 상황을 보다 정교하게 처리하여, 나중에 다시 시도할 수 있도록 요청을 저장하는 등의 방식으로 개선할 수 있습니다.

행 업데이트

행 업데이트 코드는 새로운 행을 생성하는 코드와 유사합니다:

(!examples/access-plugin-minimal/updaterow.go!)

updateRow와 createRow의 유일한 차이점은 &sheets.UpdateCellsRequest를 보내느냐 &sheets.AppendCellsRequest를 보내느냐 차이입니다. 이 함수는 업데이트할 스프레드시트 내의 행 번호를 받아 이를 제공된 액세스 요청의 정보로 업데이트합니다.

스프레드시트를 업데이트할 위치 결정

프로그램이 액세스 요청 업데이트 이벤트를 수신할 때, 액세스 요청과 관련된 스프레드시트의 행을 찾아 이를 업데이트할 방법이 필요합니다:

(!examples/access-plugin-minimal/updatespreadsheet.go!)

updateSpreadSheet는 types.AccessRequest를 받아 스프레드시트에서 가장 최근 데이터를 가져오고, 업데이트할 행을 식별하고, 그에 따라 updateRow를 호출합니다. 각 행의 첫 번째 열을 선형 검색하여 해당 열이 액세스 요청의 ID와 일치하는지 확인합니다. 그런 후 updateRow를 액세스 요청 및 행 번호로 호출합니다.

수신 액세스 요청 처리

플러그인은 이벤트를 수신할 때 핸들러 함수를 호출합니다. 이를 설정하기 위해 AccessRequestPlugin 유형의 Run 메서드를 사용하며, 이 메서드는 플러그인의 main 루프를 포함합니다:

(!examples/access-plugin-minimal/watcherjob.go!)

앞서 설명한 대로 AccessRequestPlugin 유형의 EventHandler 필드는 HandleEvent 메서드를 가진 인터페이스에 할당됩니다. 이 경우에는 *googleSheetsClient.HandleEvent가 됩니다. 이 메서드는 액세스 요청이 보류 상태인지, 즉 요청이 새로운 것인지 확인합니다. 그렇다면 createRow를 호출하고, 그렇지 않으면 updateSpreadsheet를 호출합니다.

Teleport API 클라이언트 유형인 client.Client는 Auth Service API에서 새로운 감사 이벤트를 듣기 위해 NewWatcher 메서드를 호출합니다. 해당 메서드의 두 번째 매개변수는 청취할 감사 이벤트 유형을 나타내며, 이 경우 Teleport 액세스 요청과 관련된 이벤트입니다.

NewWatcher의 결과는 types.Watcher로 Run이 새로운 감사 이벤트에 응답하여 Events 메서드를 호출할 수 있도록 합니다. 이 메서드는 Go 채널을 반환하며, 이는 병행 루틴들이 의사소통할 수 있게 해주는 런타임 추상화입니다. 또한 Done이 반환하는 또 다른 채널은 감시자가 완료되었을 때를 나타냅니다.

for 루프 내에서 Run 메서드는 먼저 준비된 Done 채널 또는 Events 채널에서 수신하여, Events 채널에서 수신될 경우 이벤트를 처리하기 위해 HandleEvent 메서드를 호출합니다.

API 클라이언트 초기화

이제 Teleport 및 Google Sheets API 클라이언트를 사용하여 액세스 요청 사건을 듣고 이를 통해 스프레드시트를 유지할 수 있는 모든 코드가 작성되었습니다. 마지막 단계는 API 클라이언트를 초기화하여 프로그램을 시작하는 것입니다:

(!examples/access-plugin-minimal/main.go!)

main 함수는 프로그램의 진입점으로, AccessRequestPlugin과 googleSheetsClient를 초기화하고 이를 사용하여 플러그인을 실행합니다.

이 함수는 이전에 다운로드한 자격 증명 파일을 사용하여 상대 경로 credentials.json에서 Google Sheets API 클라이언트를 생성합니다.

client는 Teleport API 클라이언트를 설정하는 라이브러리입니다. 우리 플러그인은 이를 통해 client.LoadIdentityFile을 호출하여 client.Credentials를 얻습니다. 그 후 이를 사용하여 client.New를 호출하여 제공된 신원 파일을 사용하여 Addrs 필드의 Teleport Proxy Service에 연결합니다.

이 예제에서는 gRPC 클라이언트가 보다 자세한 연결 오류를 반환하도록 client.New에 grpc.WithReturnConnectionError() 함수 호출을 전달합니다.

Warning

이 프로그램은 자격 증명이나 Teleport 클러스터 주소를 검증하지 않습니다. 다음 사항을 반드시 확인하십시오:

이전에 내보낸 신원 파일의 TTL이 만료되지 않았습니다.
proxyAddr 상수에 제공한 값에는
Teleport Proxy Service의 호스트와 웹 포트가 모두 포함됩니다. (예: mytenant.teleport.sh:443)

5단계/5. 플러그인 테스트

플러그인을 실행하여 Teleport 클러스터에서 Google Sheets로 액세스 요청을 전달합니다. 다음 명령어를 examples/access-plugin-minimal 내에서 실행하십시오:

go run teleport-sheets

이제 플러그인이 실행 중이므로 액세스 요청을 생성하십시오:

Teleport 관리자는 tctl을 사용하여 다른 사용자의 액세스 요청을 생성할 수 있습니다:

tctl request create myuser --roles=editor

사용자는 tsh를 사용하여 액세스 요청을 생성하고 승인된 역할로 로그인할 수 있습니다:

tsh request create --roles=editor
요청 승인 중... (id: 8f77d2d1-2bbf-4031-a300-58926237a807)

사용자는 "액세스 요청" 탭을 방문하고 "새 요청"을 클릭하여 웹 UI를 사용하여 액세스를 요청할 수 있습니다:

스프레드시트에서 PENDING 상태로 새로운 액세스 요청이 나타나는 것을 확인할 수 있습니다.

스프레드시트에서 새로운 요청 옆의 "액세스 요청 보기"를 클릭합니다. 원래 사용자로 Teleport 웹 UI에 로그인합니다. 검토를 제출할 때(예: 요청 거부) 새 상태가 스프레드시트에 나타날 것입니다.

액세스 요청 플러그인은 플러그인을 통해 액세스 요청 검토를 허용해서는 안되며, 항상 검토자를 Teleport 웹 UI로 안내하여 검토를 완료하도록 해야 합니다. 그렇지 않으면 무단 당사자가 플러그인으로 위조된 트래픽을 전송하여 특권을 상승시킬 수 있습니다.

다음 단계

이 가이드에서는 Teleport의 API 클라이언트 라이브러리를 사용하여 액세스 요청 플러그인을 설정하는 방법을 보여주었습니다. 이 가이드에서 시연한 최소 플러그인을 넘어 커뮤니케이션 및 프로젝트 관리 도구를 최대한 활용하는 보다 정교한 워크플로를 설정하는 데 Teleport API를 사용할 수 있습니다.

상태 관리

우리가 이 가이드에서 개발한 플러그인은 무상태이며, 모든 행을 검색하여 액세스 요청 정보를 업데이트하지만, 실제 액세스 요청 플러그인은 일반적으로 상태를 관리해야 합니다. [plugindata](https://pkg.go.dev/github.com/gravitational/teleport/api/types#PluginData) 패키지를 사용하면 액세스 요청 플러그인이 이를 더 쉽게 관리할 수 있습니다.

예제 상담

GitHub의 gravitational/teleport 저장소를 탐색하여 Teleport에서 개발된 플러그인 예제를 확인하십시오. 이러한 플러그인이 이 가이드에서 논의한 패키지를 어떻게 사용하는지, 구성 검증 및 상태 관리와 같은 보다 완전한 기능을 추가하는 방법을 볼 수 있습니다.

단기 자격 증명으로 플러그인 프로비저닝

이 예제에서는 tctl auth sign 명령을 사용하여 플러그인을 위한 자격 증명을 가져왔습니다. 생산 사용을 위해서는 이러한 자격 증명이 도난되는 위험을 줄이기 위해 Machine ID를 통한 단기 자격 증명을 프로비저닝하는 것이 좋습니다. 더 알아보려면 Machine ID 문서를 참조하세요.

Teleport 원문 보기