InfoGrab Docs

Access Request 플러그인 빌드 방법

요약

Teleport Access Request를 사용하면 Teleport 사용자를 기본적으로 낮은 권한의 역할에 할당하고, 일시적으로 권한을 상승할 수 있도록 허용할 수 있습니다. Teleport의 API 클라이언트 라이브러리를 사용하여 조직의 고유한 워크플로와 통합되는 Access Request 플러그인을 빌드할 수 있습니다.

Teleport Access Request를 사용하면 Teleport 사용자를 기본적으로 낮은 권한의 역할에 할당하고, 일시적으로 권한을 상승할 수 있도록 허용할 수 있습니다. 검토자는 Access Request 플러그인을 사용하여 조직의 기존 커뮤니케이션 워크플로(예: Slack, 이메일, PagerDuty) 내에서 Access Request를 승인하거나 거부할 수 있습니다.

Teleport의 API 클라이언트 라이브러리를 사용하여 조직의 고유한 워크플로와 통합되는 Access Request 플러그인을 빌드할 수 있습니다.

이 가이드에서는 Google Sheets를 통해 Access Request를 관리할 수 있는 플러그인 작성 방법을 보여주며 Teleport의 다양한 API 클라이언트 라이브러리를 살펴봅니다. 플러그인은 Google Sheets 스프레드시트에 새 Access Request를 나열하고, 각 요청을 승인하거나 거부하는 링크를 제공합니다.

플러그인 결과

작동 방식#

Teleport Access Request 플러그인은 Teleport Auth Service gRPC API에 인증하고 Auth Service가 Access Request를 생성하거나 업데이트할 때 메시지를 수신합니다. 그런 다음 플러그인은 수신한 Access Request 알림을 기반으로 서드파티 API와 상호작용합니다. Teleport API 클라이언트 라이브러리에는 Teleport ID 파일을 사용하여 API에 인증하는 메서드와 Auth Service에서 감사 이벤트를 수신하여 특정 작업을 수행하는 메서드가 포함되어 있습니다.

Warning

이 가이드에서 빌드하는 플러그인은 학습 도구로 만들어졌습니다. 프로덕션 Teleport 클러스터에는 연결하지 마십시오. 데모 클러스터를 사용하세요.

사전 요구사항#

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

  • 워크스테이션에 Go 버전 [teleport.golang]+ 설치. Go 다운로드 페이지를 참조하세요. 이 가이드를 완료하기 위해 Go에 익숙할 필요는 없지만, 자체 Access Request 플러그인을 빌드하려면 Go 지식이 필요합니다.

Google Sheets API에 인증이 필요한 데모 플러그인을 설정하기 위해 다음이 필요합니다:

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

데모 프로젝트를 설정하지 않더라도, 이 가이드를 통해 Access Request 플러그인 개발에 사용할 수 있는 라이브러리, 타입, 함수를 확인할 수 있습니다.

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

Recommended: Configure Machine & Workload Identity to provide short-lived Teleport credentials to the plugin. Before following this guide, follow a Machine & Workload Identity deployment guide to run the tbot binary on your infrastructure.

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

최소한의 Access Request 플러그인 소스 코드를 다운로드합니다:

$ git clone https://github.com/gravitational/teleport -b branch/v(=teleport.major_version=)
$ cd teleport/examples/access-plugin-minimal

이 가이드의 나머지 부분에서는 이 플러그인을 설정하는 방법과 플러그인이 Teleport의 API를 사용하여 Access Request를 특정 워크플로에 통합하는 방식을 살펴봅니다.

2/5단계. Google Sheets API 설정#

Access Request 플러그인은 일반적으로 두 개의 API와 통신합니다. Teleport Auth Service의 gRPC API에서 Access Request 이벤트를 수신하고, 선택한 메시지 또는 협업 도구의 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 자격 증명 파일을 Go 프로젝트 디렉터리에 credentials.json으로 저장합니다.

플러그인은 이 JSON 파일을 사용하여 Google Sheets에 인증합니다.

Google Sheets 스프레드시트 생성#

다음 URL을 방문하고 올바른 사용자로 인증되어 있는지 확인합니다:

https://sheets.new

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

공유를 클릭하여 플러그인에 스프레드시트 접근 권한을 부여합니다. 사람 및 그룹 추가 필드에 teleport-google-sheets-plugin@PROJECT_NAME.iam.gserviceaccount.com을 입력하고 PROJECT_NAME을 프로젝트 이름으로 바꿉니다. 서비스 계정에 "편집자" 권한이 있는지 확인합니다. 공유를 클릭한 다음, 경고 메시지가 표시되면 어쨌든 공유를 클릭합니다.

생성한 서비스 계정으로 Google Sheets에 인증함으로써, 플러그인은 스프레드시트를 수정할 수 있게 됩니다.

다음으로, 스프레드시트 내에서 다음이 사실인지 확인합니다:

  • 시트가 하나만 있음
  • 시트에 다음 열이 포함되어 있음:
ID Created User Roles Status Link

Access Request 플러그인을 작성하면 스프레드시트에 데이터가 자동으로 채워집니다.

3/5단계. Teleport RBAC 설정#

이 섹션에서는 Access Request를 생성하고 검토할 수 있는 Teleport 역할과 Access Request 플러그인이 Teleport에 인증하기 위한 자격 증명을 생성할 수 있는 다른 Teleport 역할을 설정합니다.

플러그인을 위한 RBAC 설정#

플러그인에 필요한 권한은 사전 설정된 access-plugin 역할에 구성되어 있습니다. 플러그인에 대한 자격 증명을 생성하려면, Machine ID 봇 사용자 또는 일반 Teleport 사용자를 정의합니다.

If you haven't set up a Machine ID bot yet, refer to the deployment guide to run the tbot binary on your infrastructure.

Next, allow the Machine ID bot to generate credentials for the access-plugin role. You can do this using tctl, replacing my-bot with the name of your bot:

$ tctl bots update my-bot --add-roles access-plugin

As with all Teleport users, the Teleport Auth Service authenticates the access-plugin user by issuing short-lived TLS credentials. In this case, we will need to request the credentials manually by impersonating the access-plugin role and user.

If you are running a self-hosted Teleport Enterprise deployment and are using tctl from the Auth Service host, you will already have impersonation privileges.

To grant your user impersonation privileges for access-plugin, define a user named access-plugin and a role named access-plugin-impersonator by adding the following YAML document into a file called access-plugin-impersonator.yaml:

kind: user
metadata:
  name: access-plugin
spec:
  roles: ['access-plugin']
version: v2
---
kind: role
version: v7
metadata:
  name: access-plugin-impersonator
spec:
  allow:
    impersonate:
      roles:
      - access-plugin
      users:
      - access-plugin

Create the user and role:

$ tctl create -f access-plugin-impersonator.yaml
user "access-plugin" has been created
role "access-plugin-impersonator" has been created

(!docs/pages/includes/create-role-using-web.mdx!)

Assign this role to the user you plan to use to generate credentials for the access-plugin role and user:

(!docs/pages/includes/add-role-to-user.mdx role="access-plugin-impersonator"!)

You will now be able to generate signed certificates for the access-plugin role and user.

액세스 플러그인 ID 내보내기#

플러그인에 Teleport ID 파일 접근 권한을 부여합니다. 유출 시 위험도가 낮은 단기 ID 파일을 생성하기 위해 Machine ID를 사용하는 것을 권장하지만, 데모 배포에서는 tctl로 장기 ID 파일을 생성할 수 있습니다:

Configure tbot with an output that will produce the credentials needed by the plugin. As the plugin will be accessing the Teleport API, the correct output type to use is identity.

For this guide, the directory destination will be used. This will write these credentials to a specified directory on disk. Ensure that this directory can be written to by the Linux user that tbot runs as, and that it can be read by the Linux user that the plugin will run as.

Modify your tbot configuration to add an identity output.

If running tbot on a Linux server, use the directory output to write identity files to the /opt/machine-id directory:

services:
- type: identity
  destination:
    type: directory
    # For this guide, /opt/machine-id is used as the destination directory.
    # You may wish to customize this. Multiple outputs cannot share the same
    # destination.
    path: /opt/machine-id

If running tbot on Kubernetes, write the identity file to Kubernetes secret instead:

services:
  - type: identity
    destination:
      type: kubernetes_secret
      name: teleport-plugin-identity

If operating tbot as a background service, restart it. If running tbot in one-shot mode, execute it now.

You should now see an identity file under /opt/machine-id or a Kubernetes secret named teleport-plugin-identity. This contains the private key and signed certificates needed by the plugin to authenticate with the Teleport Auth Service.

Like all Teleport users, access-plugin needs signed credentials in order to connect to your Teleport cluster. You will use the tctl auth sign command to request these credentials.

The following tctl auth sign command impersonates the access-plugin user, generates signed credentials, and writes an identity file to the local directory:

$ tctl auth sign --user=access-plugin --out=identity

The plugin connects to the Teleport Auth Service's gRPC endpoint over TLS.

The identity file, identity, includes both TLS and SSH credentials. The plugin uses the SSH credentials to connect to the Proxy Service, which establishes a reverse tunnel connection to the Auth Service. The plugin uses this reverse tunnel, along with your TLS credentials, to connect to the Auth Service's gRPC endpoint.

Certificate Lifetime

By default, tctl auth sign produces certificates with a relatively short lifetime. For production deployments, we suggest using Machine & Workload Identity to programmatically issue and renew certificates for your plugin. See our Machine & Workload Identity getting started guide to learn more.

Note that you cannot issue certificates that are valid longer than your existing credentials. For example, to issue certificates with a 1000-hour TTL, you must be logged in with a session that is valid for at least 1000 hours. This means your user must have a role allowing a max_session_ttl of at least 1000 hours (60000 minutes), and you must specify a --ttl when logging in:

$ tsh login --proxy=teleport.example.com --ttl=60060

If you are running the plugin on a Linux server, create a data directory to hold certificate files for the plugin:

$ sudo mkdir -p /var/lib/teleport/plugins/api-credentials
$ sudo mv identity /var/lib/teleport/plugins/api-credentials

If you are running the plugin on Kubernetes, Create a Kubernetes secret that contains the Teleport identity file:

$ kubectl -n teleport create secret generic --from-file=identity teleport-plugin-identity

Once the Teleport credentials expire, you will need to renew them by running the tctl auth sign command again.

Teleport의 Access Request 플러그인은 TLS를 통해 Teleport Auth Service의 gRPC 엔드포인트에 연결하여 새로운 및 업데이트된 Access Request를 수신합니다.

ID 파일에는 TLS 및 SSH 자격 증명이 모두 포함됩니다. Access Request 플러그인은 SSH 자격 증명을 사용하여 Proxy Service에 연결하고, 이 서비스는 Auth Service에 역방향 터널 연결을 설정합니다. 플러그인은 이 역방향 터널과 TLS 자격 증명을 함께 사용하여 Auth Service의 gRPC 엔드포인트에 연결합니다.

이 파일은 나중에 플러그인 설정 시 참조합니다.

Role Access Request 설정#

이 가이드에서는 플러그인을 사용하여 Role Access Request를 관리합니다. 이를 위해 클러스터에서 Role Access Request를 설정합니다.

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.

Create a file called editor-request-rbac.yaml with the following content:

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

Create the roles you defined:

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

(!docs/pages/includes/create-role-using-web.mdx!)

Allow yourself to review requests by users with the editor-requester role by assigning yourself the editor-reviewer role.

(!docs/pages/includes/add-role-to-user.mdx role="editor-reviewer"!)

Create a user called myuser who has the editor-requester role. This user cannot edit your cluster configuration unless they request the editor role:

$ tctl users add myuser --roles=editor-requester

tctl will print an invitation URL to your terminal. Visit the URL and log in as myuser for the first time, registering credentials as configured for your Teleport cluster.

Later in this guide, you will have myuser request the editor role so you can review the request using the Teleport plugin.

4/5단계. Access Request 플러그인 작성#

이 단계에서는 examples/access-plugin-minimal/main.go에 있는 Access Request 플러그인의 구조를 살펴봅니다. 여기서 제공하는 예시를 사용하여 자체 Access Request 플러그인을 작성할 수 있습니다.

임포트#

Access Request 플러그인이 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에서 사용되는 타입, 예: Access Request.
github.com/gravitational/trace 표준 라이브러리보다 더 유용한 세부 정보로 오류를 표시.
google.golang.org/api/option Google API 클라이언트 설정 옵션.
google.golang.org/api/sheets/v4 프로그램에서 sheets로 별칭된 Google Sheets API 클라이언트 라이브러리.
google.golang.org/grpc gRPC 클라이언트 및 서버 라이브러리.

설정#

먼저 환경에 맞게 설정해야 하는 두 가지 상수를 선언합니다:

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

proxyAddr는 Teleport Proxy Service 또는 Teleport Enterprise Cloud 테넌트의 호스트 이름과 포트를 나타냅니다. 자체 Proxy Service의 주소(예: mytenant.teleport.sh:443)로 지정합니다.

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

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

AccessRequestPlugin 타입#

plugin.go 파일은 Access Request 플러그인 코드를 구성하는 데 사용할 타입을 선언합니다:

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

AccessRequestPlugin 타입은 일반적인 Access Request 플러그인을 나타내며, 이 타입을 사용하여 자체 플러그인을 빌드할 수 있습니다. Teleport API 클라이언트와 HandleEvent 메서드를 구현하는 모든 Go 타입인 EventHandler를 포함합니다.

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

행 데이터 준비#

스프레드시트의 새 행을 생성하거나 기존 행을 업데이트할 때, Access Request에서 데이터를 추출하여 Google Sheets에 제공해야 합니다. makeRowData 메서드로 이를 수행합니다:

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

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

makeRowData는 googleSheetsClient 타입의 메서드입니다. (googleSheetsClient 앞의 *는 메서드가 googleSheetsClient에 대한 포인터를 받는다는 것을 나타냅니다.) Teleport의 API 라이브러리가 Access Request 내의 필드를 나타내는 데 사용하는 types.AccessRequest를 받습니다.

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

Access Request는 승인됨, 거부됨, 대기 중, 없음의 네 가지 상태 중 하나를 가집니다. Teleport의 types 라이브러리에서 요청 상태를 가져와 requestStates 맵에서 문자열로 매핑합니다.

데이터를 추출할 때, types.AccessRequest.GetName() 메서드를 사용하여 스프레드시트에 포함할 수 있는 문자열로 Access Request의 ID를 가져옵니다.

사용자는 요청의 ID에 해당하는 Teleport Web UI URL을 방문하여 Access Request를 검토할 수 있습니다. makeRowData는 스프레드시트에 이 URL로의 링크로 삽입할 수 있는 =HYPERLINK 수식을 조합합니다.

행 생성#

다음 함수는 makeRowData가 반환한 데이터를 사용하여 들어오는 Access Request를 기반으로 새 행을 생성하도록 Google Sheets API에 요청을 제출합니다. 행 생성 시도가 실패하면 오류를 반환합니다:

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

createRow는 sheets.BatchUpdateSpreadsheetRequest를 조합하여 g.sheetsClient.BatchUpdate()를 사용해 Google Sheets API로 전송하고, 요청 전송 중 발생한 오류를 반환합니다.

예상치 못한 HTTP 상태 코드는 오류를 반환하지 않고 로깅합니다. 이는 일시적인 서버 측 문제일 수 있기 때문입니다. 프로덕션 Access Request 플러그인은 이러한 상황을 더 정교하게 처리합니다. 예를 들어 요청을 저장하여 나중에 재시도할 수 있습니다.

행 업데이트#

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

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

updateRow와 createRow의 유일한 차이점은 &sheets.AppendCellsRequest 대신 &sheets.UpdateCellsRequest를 전송한다는 것입니다. 이 함수는 업데이트할 스프레드시트의 행 번호를 받아 제공된 Access Request의 정보로 해당 행을 업데이트하는 요청을 전송합니다.

스프레드시트에서 업데이트 위치 결정#

프로그램이 Access Request를 업데이트하는 이벤트를 수신하면, 스프레드시트에서 Access Request에 해당하는 행을 조회하여 해당 행을 업데이트할 방법이 필요합니다:

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

updateSpreadSheet는 types.AccessRequest를 받아 스프레드시트에서 최신 데이터를 가져오고, 업데이트할 행을 결정한 다음 그에 따라 updateRow를 호출합니다. 선형 검색을 사용하여 시트의 각 행 내 첫 번째 열을 조회하고 해당 열이 Access Request의 ID와 일치하는지 확인합니다. 그런 다음 Access Request와 행 번호로 updateRow를 호출합니다.

들어오는 Access Request 처리#

플러그인은 이벤트를 수신할 때 핸들러 함수를 호출합니다. 이를 설정하기 위해 플러그인의 기본 루프를 포함하는 일반적인 AccessRequestPlugin 타입의 Run 메서드를 사용합니다:

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

위에서 설명했듯이, AccessRequestPlugin 타입의 EventHandler 필드는 HandleEvent 메서드가 있는 인터페이스에 할당됩니다. 이 경우 구현은 *googleSheetsClient.HandleEvent입니다. 이 메서드는 Access Request가 대기 중 상태인지, 즉 요청이 새로운 것인지 확인합니다. 그렇다면 createRow를 호출합니다. 그렇지 않으면 updateSpreadsheet를 호출합니다.

Teleport API 클라이언트 타입인 client.Client에는 gRPC 스트림을 통해 Auth Service API에서 새로운 감사 이벤트를 수신하는 NewWatcher 메서드가 있습니다. 메서드의 두 번째 매개변수는 감시할 감사 이벤트 유형을 나타냅니다. 이 경우 Access Request와 관련된 이벤트입니다.

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

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

API 클라이언트 초기화#

이제 Teleport와 Google Sheets API 클라이언트를 사용하여 Access Request 이벤트를 수신하고 스프레드시트를 유지 관리하는 데 필요한 모든 코드가 준비되었습니다. 마지막 단계는 API 클라이언트를 초기화하여 프로그램을 시작하는 것입니다:

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

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

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

client는 API 클라이언트를 설정하기 위한 Teleport 라이브러리입니다. 플러그인은 client.LoadIdentityFile을 호출하여 client.Credentials를 가져옵니다. 그런 다음 client.Credentials를 사용하여 client.New를 호출하며, 이는 제공된 ID 파일을 사용하여 Addrs 필드에 지정된 Teleport Proxy Service에 연결합니다.

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

Warning

이 프로그램은 자격 증명이나 Teleport 클러스터 주소를 검증하지 않습니다. 다음을 확인하세요:

  • 이전에 내보낸 ID 파일의 TTL이 만료되지 않았는지
  • proxyAddr 상수에 지정한 값이 Teleport Proxy Service의 호스트와 웹 포트를 모두 포함하는지, 예: mytenant.teleport.sh:443

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

플러그인을 실행하여 Teleport 클러스터에서 Google Sheets로 Access Request를 전달합니다. examples/access-plugin-minimal 내에서 다음 명령을 실행합니다:

$ go run teleport-sheets

이제 플러그인이 실행 중이므로 Access Request를 생성합니다:

스프레드시트에서 PENDING 상태로 새 Access Request를 확인할 수 있어야 합니다.

스프레드시트에서 새 요청 옆의 "View Access Request"를 클릭합니다. 원래 사용자로 Teleport Web UI에 로그인합니다. 요청을 검토(예: 거부)하면, 새 상태가 스프레드시트 내에 표시됩니다.

Warning

Access Request 플러그인은 플러그인을 통한 Access Request 검토를 활성화해서는 안 되며, 항상 검토자를 Teleport Web UI로 안내하여 검토를 완료해야 합니다. 그렇지 않으면 권한 없는 당사자가 플러그인으로의 트래픽을 스푸핑하여 권한을 상승할 수 있습니다.

다음 단계#

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

상태 관리#

이 가이드에서 개발한 플러그인은 스프레드시트의 모든 행을 검색하여 Access Request 정보를 업데이트하는 무상태 방식이지만, 실제 Access Request 플러그인은 일반적으로 상태를 관리해야 합니다. plugindata 패키지를 사용하면 Access Request 플러그인이 이를 더 쉽게 수행할 수 있습니다.

예시 참조#

GitHub의 gravitational/teleport 저장소에서 Teleport에서 개발한 플러그인 예시를 탐색하세요. 이 플러그인들이 이 가이드에서 설명한 패키지를 어떻게 사용하는지, 그리고 설정 검증 및 상태 관리와 같은 더 완전한 기능을 어떻게 추가하는지 확인할 수 있습니다.

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

이 예시에서는 tctl auth sign 명령을 사용하여 플러그인의 자격 증명을 가져왔습니다. 프로덕션 사용 시, 자격 증명 도용 위험을 줄이기 위해 머신 및 워크로드 아이덴티티를 통해 단기 자격 증명을 프로비저닝하는 것을 권장합니다. 자세한 내용은 머신 및 워크로드 아이덴티티 문서를 참조하세요.

Access Request 플러그인 빌드 방법

원문 보기
요약

Teleport Access Request를 사용하면 Teleport 사용자를 기본적으로 낮은 권한의 역할에 할당하고, 일시적으로 권한을 상승할 수 있도록 허용할 수 있습니다. Teleport의 API 클라이언트 라이브러리를 사용하여 조직의 고유한 워크플로와 통합되는 Access Request 플러그인을 빌드할 수 있습니다.

Teleport Access Request를 사용하면 Teleport 사용자를 기본적으로 낮은 권한의 역할에 할당하고, 일시적으로 권한을 상승할 수 있도록 허용할 수 있습니다. 검토자는 Access Request 플러그인을 사용하여 조직의 기존 커뮤니케이션 워크플로(예: Slack, 이메일, PagerDuty) 내에서 Access Request를 승인하거나 거부할 수 있습니다.

Teleport의 API 클라이언트 라이브러리를 사용하여 조직의 고유한 워크플로와 통합되는 Access Request 플러그인을 빌드할 수 있습니다.

이 가이드에서는 Google Sheets를 통해 Access Request를 관리할 수 있는 플러그인 작성 방법을 보여주며 Teleport의 다양한 API 클라이언트 라이브러리를 살펴봅니다. 플러그인은 Google Sheets 스프레드시트에 새 Access Request를 나열하고, 각 요청을 승인하거나 거부하는 링크를 제공합니다.

플러그인 결과

작동 방식#

Teleport Access Request 플러그인은 Teleport Auth Service gRPC API에 인증하고 Auth Service가 Access Request를 생성하거나 업데이트할 때 메시지를 수신합니다. 그런 다음 플러그인은 수신한 Access Request 알림을 기반으로 서드파티 API와 상호작용합니다. Teleport API 클라이언트 라이브러리에는 Teleport ID 파일을 사용하여 API에 인증하는 메서드와 Auth Service에서 감사 이벤트를 수신하여 특정 작업을 수행하는 메서드가 포함되어 있습니다.

Warning

이 가이드에서 빌드하는 플러그인은 학습 도구로 만들어졌습니다. 프로덕션 Teleport 클러스터에는 연결하지 마십시오. 데모 클러스터를 사용하세요.

사전 요구사항#

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

  • 워크스테이션에 Go 버전 [teleport.golang]+ 설치. Go 다운로드 페이지를 참조하세요. 이 가이드를 완료하기 위해 Go에 익숙할 필요는 없지만, 자체 Access Request 플러그인을 빌드하려면 Go 지식이 필요합니다.

Google Sheets API에 인증이 필요한 데모 플러그인을 설정하기 위해 다음이 필요합니다:

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

데모 프로젝트를 설정하지 않더라도, 이 가이드를 통해 Access Request 플러그인 개발에 사용할 수 있는 라이브러리, 타입, 함수를 확인할 수 있습니다.

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

Recommended: Configure Machine & Workload Identity to provide short-lived Teleport credentials to the plugin. Before following this guide, follow a Machine & Workload Identity deployment guide to run the tbot binary on your infrastructure.

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

최소한의 Access Request 플러그인 소스 코드를 다운로드합니다:

$ git clone https://github.com/gravitational/teleport -b branch/v(=teleport.major_version=)
$ cd teleport/examples/access-plugin-minimal

이 가이드의 나머지 부분에서는 이 플러그인을 설정하는 방법과 플러그인이 Teleport의 API를 사용하여 Access Request를 특정 워크플로에 통합하는 방식을 살펴봅니다.

2/5단계. Google Sheets API 설정#

Access Request 플러그인은 일반적으로 두 개의 API와 통신합니다. Teleport Auth Service의 gRPC API에서 Access Request 이벤트를 수신하고, 선택한 메시지 또는 협업 도구의 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 자격 증명 파일을 Go 프로젝트 디렉터리에 credentials.json으로 저장합니다.

플러그인은 이 JSON 파일을 사용하여 Google Sheets에 인증합니다.

Google Sheets 스프레드시트 생성#

다음 URL을 방문하고 올바른 사용자로 인증되어 있는지 확인합니다:

https://sheets.new

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

공유를 클릭하여 플러그인에 스프레드시트 접근 권한을 부여합니다. 사람 및 그룹 추가 필드에 teleport-google-sheets-plugin@PROJECT_NAME.iam.gserviceaccount.com을 입력하고 PROJECT_NAME을 프로젝트 이름으로 바꿉니다. 서비스 계정에 "편집자" 권한이 있는지 확인합니다. 공유를 클릭한 다음, 경고 메시지가 표시되면 어쨌든 공유를 클릭합니다.

생성한 서비스 계정으로 Google Sheets에 인증함으로써, 플러그인은 스프레드시트를 수정할 수 있게 됩니다.

다음으로, 스프레드시트 내에서 다음이 사실인지 확인합니다:

  • 시트가 하나만 있음
  • 시트에 다음 열이 포함되어 있음:
ID Created User Roles Status Link

Access Request 플러그인을 작성하면 스프레드시트에 데이터가 자동으로 채워집니다.

3/5단계. Teleport RBAC 설정#

이 섹션에서는 Access Request를 생성하고 검토할 수 있는 Teleport 역할과 Access Request 플러그인이 Teleport에 인증하기 위한 자격 증명을 생성할 수 있는 다른 Teleport 역할을 설정합니다.

플러그인을 위한 RBAC 설정#

플러그인에 필요한 권한은 사전 설정된 access-plugin 역할에 구성되어 있습니다. 플러그인에 대한 자격 증명을 생성하려면, Machine ID 봇 사용자 또는 일반 Teleport 사용자를 정의합니다.

If you haven't set up a Machine ID bot yet, refer to the deployment guide to run the tbot binary on your infrastructure.

Next, allow the Machine ID bot to generate credentials for the access-plugin role. You can do this using tctl, replacing my-bot with the name of your bot:

$ tctl bots update my-bot --add-roles access-plugin

As with all Teleport users, the Teleport Auth Service authenticates the access-plugin user by issuing short-lived TLS credentials. In this case, we will need to request the credentials manually by impersonating the access-plugin role and user.

If you are running a self-hosted Teleport Enterprise deployment and are using tctl from the Auth Service host, you will already have impersonation privileges.

To grant your user impersonation privileges for access-plugin, define a user named access-plugin and a role named access-plugin-impersonator by adding the following YAML document into a file called access-plugin-impersonator.yaml:

kind: user
metadata:
  name: access-plugin
spec:
  roles: ['access-plugin']
version: v2
---
kind: role
version: v7
metadata:
  name: access-plugin-impersonator
spec:
  allow:
    impersonate:
      roles:
      - access-plugin
      users:
      - access-plugin

Create the user and role:

$ tctl create -f access-plugin-impersonator.yaml
user "access-plugin" has been created
role "access-plugin-impersonator" has been created

(!docs/pages/includes/create-role-using-web.mdx!)

Assign this role to the user you plan to use to generate credentials for the access-plugin role and user:

(!docs/pages/includes/add-role-to-user.mdx role="access-plugin-impersonator"!)

You will now be able to generate signed certificates for the access-plugin role and user.

액세스 플러그인 ID 내보내기#

플러그인에 Teleport ID 파일 접근 권한을 부여합니다. 유출 시 위험도가 낮은 단기 ID 파일을 생성하기 위해 Machine ID를 사용하는 것을 권장하지만, 데모 배포에서는 tctl로 장기 ID 파일을 생성할 수 있습니다:

Configure tbot with an output that will produce the credentials needed by the plugin. As the plugin will be accessing the Teleport API, the correct output type to use is identity.

For this guide, the directory destination will be used. This will write these credentials to a specified directory on disk. Ensure that this directory can be written to by the Linux user that tbot runs as, and that it can be read by the Linux user that the plugin will run as.

Modify your tbot configuration to add an identity output.

If running tbot on a Linux server, use the directory output to write identity files to the /opt/machine-id directory:

services:
- type: identity
  destination:
    type: directory
    # For this guide, /opt/machine-id is used as the destination directory.
    # You may wish to customize this. Multiple outputs cannot share the same
    # destination.
    path: /opt/machine-id

If running tbot on Kubernetes, write the identity file to Kubernetes secret instead:

services:
  - type: identity
    destination:
      type: kubernetes_secret
      name: teleport-plugin-identity

If operating tbot as a background service, restart it. If running tbot in one-shot mode, execute it now.

You should now see an identity file under /opt/machine-id or a Kubernetes secret named teleport-plugin-identity. This contains the private key and signed certificates needed by the plugin to authenticate with the Teleport Auth Service.

Like all Teleport users, access-plugin needs signed credentials in order to connect to your Teleport cluster. You will use the tctl auth sign command to request these credentials.

The following tctl auth sign command impersonates the access-plugin user, generates signed credentials, and writes an identity file to the local directory:

$ tctl auth sign --user=access-plugin --out=identity

The plugin connects to the Teleport Auth Service's gRPC endpoint over TLS.

The identity file, identity, includes both TLS and SSH credentials. The plugin uses the SSH credentials to connect to the Proxy Service, which establishes a reverse tunnel connection to the Auth Service. The plugin uses this reverse tunnel, along with your TLS credentials, to connect to the Auth Service's gRPC endpoint.

Certificate Lifetime

By default, tctl auth sign produces certificates with a relatively short lifetime. For production deployments, we suggest using Machine & Workload Identity to programmatically issue and renew certificates for your plugin. See our Machine & Workload Identity getting started guide to learn more.

Note that you cannot issue certificates that are valid longer than your existing credentials. For example, to issue certificates with a 1000-hour TTL, you must be logged in with a session that is valid for at least 1000 hours. This means your user must have a role allowing a max_session_ttl of at least 1000 hours (60000 minutes), and you must specify a --ttl when logging in:

$ tsh login --proxy=teleport.example.com --ttl=60060

If you are running the plugin on a Linux server, create a data directory to hold certificate files for the plugin:

$ sudo mkdir -p /var/lib/teleport/plugins/api-credentials
$ sudo mv identity /var/lib/teleport/plugins/api-credentials

If you are running the plugin on Kubernetes, Create a Kubernetes secret that contains the Teleport identity file:

$ kubectl -n teleport create secret generic --from-file=identity teleport-plugin-identity

Once the Teleport credentials expire, you will need to renew them by running the tctl auth sign command again.

Teleport의 Access Request 플러그인은 TLS를 통해 Teleport Auth Service의 gRPC 엔드포인트에 연결하여 새로운 및 업데이트된 Access Request를 수신합니다.

ID 파일에는 TLS 및 SSH 자격 증명이 모두 포함됩니다. Access Request 플러그인은 SSH 자격 증명을 사용하여 Proxy Service에 연결하고, 이 서비스는 Auth Service에 역방향 터널 연결을 설정합니다. 플러그인은 이 역방향 터널과 TLS 자격 증명을 함께 사용하여 Auth Service의 gRPC 엔드포인트에 연결합니다.

이 파일은 나중에 플러그인 설정 시 참조합니다.

Role Access Request 설정#

이 가이드에서는 플러그인을 사용하여 Role Access Request를 관리합니다. 이를 위해 클러스터에서 Role Access Request를 설정합니다.

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.

Create a file called editor-request-rbac.yaml with the following content:

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

Create the roles you defined:

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

(!docs/pages/includes/create-role-using-web.mdx!)

Allow yourself to review requests by users with the editor-requester role by assigning yourself the editor-reviewer role.

(!docs/pages/includes/add-role-to-user.mdx role="editor-reviewer"!)

Create a user called myuser who has the editor-requester role. This user cannot edit your cluster configuration unless they request the editor role:

$ tctl users add myuser --roles=editor-requester

tctl will print an invitation URL to your terminal. Visit the URL and log in as myuser for the first time, registering credentials as configured for your Teleport cluster.

Later in this guide, you will have myuser request the editor role so you can review the request using the Teleport plugin.

4/5단계. Access Request 플러그인 작성#

이 단계에서는 examples/access-plugin-minimal/main.go에 있는 Access Request 플러그인의 구조를 살펴봅니다. 여기서 제공하는 예시를 사용하여 자체 Access Request 플러그인을 작성할 수 있습니다.

임포트#

Access Request 플러그인이 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에서 사용되는 타입, 예: Access Request.
github.com/gravitational/trace 표준 라이브러리보다 더 유용한 세부 정보로 오류를 표시.
google.golang.org/api/option Google API 클라이언트 설정 옵션.
google.golang.org/api/sheets/v4 프로그램에서 sheets로 별칭된 Google Sheets API 클라이언트 라이브러리.
google.golang.org/grpc gRPC 클라이언트 및 서버 라이브러리.

설정#

먼저 환경에 맞게 설정해야 하는 두 가지 상수를 선언합니다:

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

proxyAddr는 Teleport Proxy Service 또는 Teleport Enterprise Cloud 테넌트의 호스트 이름과 포트를 나타냅니다. 자체 Proxy Service의 주소(예: mytenant.teleport.sh:443)로 지정합니다.

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

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

AccessRequestPlugin 타입#

plugin.go 파일은 Access Request 플러그인 코드를 구성하는 데 사용할 타입을 선언합니다:

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

AccessRequestPlugin 타입은 일반적인 Access Request 플러그인을 나타내며, 이 타입을 사용하여 자체 플러그인을 빌드할 수 있습니다. Teleport API 클라이언트와 HandleEvent 메서드를 구현하는 모든 Go 타입인 EventHandler를 포함합니다.

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

행 데이터 준비#

스프레드시트의 새 행을 생성하거나 기존 행을 업데이트할 때, Access Request에서 데이터를 추출하여 Google Sheets에 제공해야 합니다. makeRowData 메서드로 이를 수행합니다:

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

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

makeRowData는 googleSheetsClient 타입의 메서드입니다. (googleSheetsClient 앞의 *는 메서드가 googleSheetsClient에 대한 포인터를 받는다는 것을 나타냅니다.) Teleport의 API 라이브러리가 Access Request 내의 필드를 나타내는 데 사용하는 types.AccessRequest를 받습니다.

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

Access Request는 승인됨, 거부됨, 대기 중, 없음의 네 가지 상태 중 하나를 가집니다. Teleport의 types 라이브러리에서 요청 상태를 가져와 requestStates 맵에서 문자열로 매핑합니다.

데이터를 추출할 때, types.AccessRequest.GetName() 메서드를 사용하여 스프레드시트에 포함할 수 있는 문자열로 Access Request의 ID를 가져옵니다.

사용자는 요청의 ID에 해당하는 Teleport Web UI URL을 방문하여 Access Request를 검토할 수 있습니다. makeRowData는 스프레드시트에 이 URL로의 링크로 삽입할 수 있는 =HYPERLINK 수식을 조합합니다.

행 생성#

다음 함수는 makeRowData가 반환한 데이터를 사용하여 들어오는 Access Request를 기반으로 새 행을 생성하도록 Google Sheets API에 요청을 제출합니다. 행 생성 시도가 실패하면 오류를 반환합니다:

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

createRow는 sheets.BatchUpdateSpreadsheetRequest를 조합하여 g.sheetsClient.BatchUpdate()를 사용해 Google Sheets API로 전송하고, 요청 전송 중 발생한 오류를 반환합니다.

예상치 못한 HTTP 상태 코드는 오류를 반환하지 않고 로깅합니다. 이는 일시적인 서버 측 문제일 수 있기 때문입니다. 프로덕션 Access Request 플러그인은 이러한 상황을 더 정교하게 처리합니다. 예를 들어 요청을 저장하여 나중에 재시도할 수 있습니다.

행 업데이트#

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

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

updateRow와 createRow의 유일한 차이점은 &sheets.AppendCellsRequest 대신 &sheets.UpdateCellsRequest를 전송한다는 것입니다. 이 함수는 업데이트할 스프레드시트의 행 번호를 받아 제공된 Access Request의 정보로 해당 행을 업데이트하는 요청을 전송합니다.

스프레드시트에서 업데이트 위치 결정#

프로그램이 Access Request를 업데이트하는 이벤트를 수신하면, 스프레드시트에서 Access Request에 해당하는 행을 조회하여 해당 행을 업데이트할 방법이 필요합니다:

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

updateSpreadSheet는 types.AccessRequest를 받아 스프레드시트에서 최신 데이터를 가져오고, 업데이트할 행을 결정한 다음 그에 따라 updateRow를 호출합니다. 선형 검색을 사용하여 시트의 각 행 내 첫 번째 열을 조회하고 해당 열이 Access Request의 ID와 일치하는지 확인합니다. 그런 다음 Access Request와 행 번호로 updateRow를 호출합니다.

들어오는 Access Request 처리#

플러그인은 이벤트를 수신할 때 핸들러 함수를 호출합니다. 이를 설정하기 위해 플러그인의 기본 루프를 포함하는 일반적인 AccessRequestPlugin 타입의 Run 메서드를 사용합니다:

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

위에서 설명했듯이, AccessRequestPlugin 타입의 EventHandler 필드는 HandleEvent 메서드가 있는 인터페이스에 할당됩니다. 이 경우 구현은 *googleSheetsClient.HandleEvent입니다. 이 메서드는 Access Request가 대기 중 상태인지, 즉 요청이 새로운 것인지 확인합니다. 그렇다면 createRow를 호출합니다. 그렇지 않으면 updateSpreadsheet를 호출합니다.

Teleport API 클라이언트 타입인 client.Client에는 gRPC 스트림을 통해 Auth Service API에서 새로운 감사 이벤트를 수신하는 NewWatcher 메서드가 있습니다. 메서드의 두 번째 매개변수는 감시할 감사 이벤트 유형을 나타냅니다. 이 경우 Access Request와 관련된 이벤트입니다.

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

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

API 클라이언트 초기화#

이제 Teleport와 Google Sheets API 클라이언트를 사용하여 Access Request 이벤트를 수신하고 스프레드시트를 유지 관리하는 데 필요한 모든 코드가 준비되었습니다. 마지막 단계는 API 클라이언트를 초기화하여 프로그램을 시작하는 것입니다:

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

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

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

client는 API 클라이언트를 설정하기 위한 Teleport 라이브러리입니다. 플러그인은 client.LoadIdentityFile을 호출하여 client.Credentials를 가져옵니다. 그런 다음 client.Credentials를 사용하여 client.New를 호출하며, 이는 제공된 ID 파일을 사용하여 Addrs 필드에 지정된 Teleport Proxy Service에 연결합니다.

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

Warning

이 프로그램은 자격 증명이나 Teleport 클러스터 주소를 검증하지 않습니다. 다음을 확인하세요:

  • 이전에 내보낸 ID 파일의 TTL이 만료되지 않았는지
  • proxyAddr 상수에 지정한 값이 Teleport Proxy Service의 호스트와 웹 포트를 모두 포함하는지, 예: mytenant.teleport.sh:443

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

플러그인을 실행하여 Teleport 클러스터에서 Google Sheets로 Access Request를 전달합니다. examples/access-plugin-minimal 내에서 다음 명령을 실행합니다:

$ go run teleport-sheets

이제 플러그인이 실행 중이므로 Access Request를 생성합니다:

스프레드시트에서 PENDING 상태로 새 Access Request를 확인할 수 있어야 합니다.

스프레드시트에서 새 요청 옆의 "View Access Request"를 클릭합니다. 원래 사용자로 Teleport Web UI에 로그인합니다. 요청을 검토(예: 거부)하면, 새 상태가 스프레드시트 내에 표시됩니다.

Warning

Access Request 플러그인은 플러그인을 통한 Access Request 검토를 활성화해서는 안 되며, 항상 검토자를 Teleport Web UI로 안내하여 검토를 완료해야 합니다. 그렇지 않으면 권한 없는 당사자가 플러그인으로의 트래픽을 스푸핑하여 권한을 상승할 수 있습니다.

다음 단계#

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

상태 관리#

이 가이드에서 개발한 플러그인은 스프레드시트의 모든 행을 검색하여 Access Request 정보를 업데이트하는 무상태 방식이지만, 실제 Access Request 플러그인은 일반적으로 상태를 관리해야 합니다. plugindata 패키지를 사용하면 Access Request 플러그인이 이를 더 쉽게 수행할 수 있습니다.

예시 참조#

GitHub의 gravitational/teleport 저장소에서 Teleport에서 개발한 플러그인 예시를 탐색하세요. 이 플러그인들이 이 가이드에서 설명한 패키지를 어떻게 사용하는지, 그리고 설정 검증 및 상태 관리와 같은 더 완전한 기능을 어떻게 추가하는지 확인할 수 있습니다.

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

이 예시에서는 tctl auth sign 명령을 사용하여 플러그인의 자격 증명을 가져왔습니다. 프로덕션 사용 시, 자격 증명 도용 위험을 줄이기 위해 머신 및 워크로드 아이덴티티를 통해 단기 자격 증명을 프로비저닝하는 것을 권장합니다. 자세한 내용은 머신 및 워크로드 아이덴티티 문서를 참조하세요.