Discord 접근 요청 플러그인 실행
이 가이드는 Teleport에서 접근 요청 메시지를 수신하도록 Discord를 설정하는 방법을 설명합니다. In Teleport Enterprise Cloud, Teleport manages the Discord integration for you, and you can enroll the Discord integration from the Teleport Web UI.
이 가이드는 Teleport에서 접근 요청 메시지를 수신하도록 Discord를 설정하는 방법을 설명합니다. Teleport의 Discord 통합은 접근 요청을 개인과 채널에 알립니다. 사용자는 Discord 내에서 접근 요청을 승인하거나 거부할 수 있으므로 생산성을 저해하지 않고 보안 모범 사례를 구현하기가 더 쉬워집니다.
이 통합은 Teleport Cloud에서 호스팅됩니다
In Teleport Enterprise Cloud, Teleport manages the Discord integration for you, and you can enroll the Discord integration from the Teleport Web UI.
Visit the Teleport Web UI and on the left sidebar, click Add New followed by Integration:
On the "Select Integration Type" menu, click the tile for your integration. You will see a page with instructions to set up the integration, as well as a form that you can use to configure the integration.
작동 방식#
Teleport Discord 플러그인은 Discord 서버와 Teleport Auth Service에 인증하고, Teleport Auth Service에서 접근 요청과 관련된 감사 이벤트를 수신합니다. 사용자가 접근 요청을 만들면 플러그인은 Discord에서 요청 검토자에게 메시지를 보내며, 각 검토자가 Teleport Web UI에서 요청을 검토할 수 있는 링크가 포함됩니다. 접근 요청의 대상 역할에 따라 플러그인이 알릴 검토자를 구성할 수 있습니다.
전제 조건#
-
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
tctlandtshclients.Installing `tctl` and `tsh` clients
-
Determine the version of your Teleport cluster. The
tctlandtshclients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at/v1/webapi/findand 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')" -
Follow the instructions for your platform to install
tctlandtshclients:
-
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.
- Discord 서버의 관리자 계정. 봇을 설치하려면 적어도 "manage server" 권한이 필요합니다.
- Discord 플러그인을 실행할 Linux 호스트 또는 Kubernetes 클러스터.
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/8단계. RBAC 리소스 정의#
Discord 플러그인을 설정하기 전에 Teleport 클러스터에서 역할 접근 요청을 활성화해야 합니다.
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.
2/8단계. Teleport Discord 플러그인 사용자 정의#
플러그인에 필요한 권한은 사전 설정된 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.
3/8단계. 접근 플러그인 아이덴티티 내보내기#
플러그인에 Teleport 아이덴티티 파일 접근 권한을 부여합니다. 유출될 경우 덜 위험한 단기 아이덴티티 파일을 생성하기 위해 Machine ID를 사용하는 것을 권장하지만, 데모 배포에서는 tctl로 더 오래 지속되는 아이덴티티 파일을 생성할 수 있습니다:
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-discord-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-discord-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-discord-identity
Once the Teleport credentials expire, you will need to renew them by running the
tctl auth sign command again.
4/8단계. Teleport Discord 플러그인 설치#
5/8단계. Discord 앱 등록#
Discord용 접근 요청 플러그인은 Teleport Auth Service에서 접근 요청 이벤트를 받아 Discord 메시지 형식으로 변환하고 Discord API로 보내 길드(Discord 서버)에 게시합니다. 이 작업을 위해 Discord API에 새 앱을 등록해야 합니다.
애플리케이션 만들기#
- https://discord.com/developers/applications를 방문하여 새 Discord 애플리케이션을 만듭니다. "New Application"을 클릭하고 애플리케이션 이름을 "Teleport"로 지정합니다.
- 애플리케이션 아이콘을 다운로드합니다.
- 애플리케이션 아이콘을 설정합니다.
애플리케이션 봇 만들기#
"Bot" 탭으로 이동하여 "Add Bot"을 선택합니다. 봇 아이콘으로 설정할 아바타를 다운로드할 수 있습니다. 이 봇은 Discord 서버 내에서만 사용되어야 하므로 "Public Bot" 토글을 해제합니다. 마지막으로 "Reset Token"을 눌러 새 토큰을 복사하고 안전한 곳에 저장합니다. 이 토큰은 Teleport 플러그인이 Discord API에 인증하는 데 사용됩니다.
Discord 서버에 애플리케이션 설치 및 권한 부여#
"OAuth2" 탭으로 이동하고 "URL Generator"를 열어 다음 권한을 확인합니다:
- bot
- View Channels
- Send Messages
생성된 URL을 복사하고 접근합니다. 원하는 Discord 서버에 애플리케이션을 설치하도록 선택합니다. 서버가 드롭다운 목록에 없는 경우 충분한 권한이 없는 것입니다. 서버 관리자에게 "manage server" 권한이 있는 역할을 부여하도록 요청합니다.
동일한 애플리케이션을 여러 Discord 서버에 설치할 수 있습니다. 이를 위해 OAuth URL에 여러 번 접근하고 다른 서버를 선택합니다. 앱을 설치하려면 Discord 서버의 관리자여야 합니다.
6/8단계. Teleport Discord 플러그인 구성#
이제 Teleport Discord 플러그인은 Teleport 클러스터 및 Discord API와 통신하는 데 필요한 자격 증명을 갖추었습니다. 이 단계에서는 이 자격 증명을 사용하도록 Discord 플러그인을 구성합니다. 또한 접근 요청 업데이트를 받을 때 올바른 Discord 채널에 알리도록 플러그인을 구성합니다.
구성 파일 만들기#
Teleport Discord 플러그인은 TOML 형식의 구성 파일을 사용합니다. 다음 명령을 실행하여 기본 구성을 생성합니다(구성 파일이 /etc/teleport-discord.toml에 없으면 플러그인이 실행되지 않습니다):
$ teleport-discord configure | sudo tee /etc/teleport-discord.toml > /dev/null
결과 구성 파일은 다음과 같습니다:
<div class="admonition note"><div class="admonition-title">Note</div><p>이 섹션의 내용은 원문 문서를 참조하세요. (<code>teleport-discord.toml</code>)</p></div>
Discord Helm chart는 플러그인을 구성하기 위해 YAML 값 파일을 사용합니다. 로컬 워크스테이션에서 다음 예시를 기반으로 teleport-discord-helm.yaml 파일을 만듭니다:
<div class="admonition note"><div class="admonition-title">Note</div><p>이 섹션의 내용은 원문 문서를 참조하세요. (<code>teleport-discord-helm.yaml</code>)</p></div>
구성 파일 편집#
Teleport Discord 플러그인에 만들어진 구성 파일을 열고 다음 필드를 업데이트합니다:
[teleport]
Discord 플러그인은 이 섹션을 사용하여 Teleport Auth Service에 연결합니다.
If you are providing credentials to the plugin using a tbot binary that runs
on a Linux server, make sure the value of identity is the same as the path of
the identity file you configured tbot to generate, /opt/machine-id/identity.
Configure the plugin to periodically reload the identity file, ensuring that it does not attempt to connect to the Teleport Auth Service with expired credentials.
Add the following to the teleport section of the configuration:
refresh_identity = true
[discord]
token: 이전에 저장한 봇 토큰을 이 필드에 붙여 넣습니다.
[role_to_recipients]
role_to_recipients 맵은 사용자가 특정 역할에 대한 접근을 요청할 때 Discord 플러그인이 알릴 채널을 구성합니다. Discord 플러그인이 Auth Service에서 접근 요청을 받으면 요청된 역할을 조회하고 알릴 Discord 채널을 확인합니다.
각 채널은 숫자 ID로 표시됩니다. 채널은 공개, 비공개 또는 사용자와 봇 간의 다이렉트 메시지일 수 있습니다. 봇이 알릴 채널의 숫자 ID를 확인하려면 아래 지침을 따르세요:
웹 브라우저에서 Discord를 열고 원하는 채널로 이동합니다.
웹 브라우저 URL은 다음과 같아야 합니다:
https://discord.com/channels/<guild ID>/<channel ID>
URL의 마지막 부분(마지막 / 이후 모두)을 복사합니다. 이것이 채널 ID입니다.
웹 브라우저에서 Discord를 열고 원하는 채널로 이동합니다.
채널 목록에서 "Create invite"를 선택하고 검색 필드에 "teleport"를 입력하여 Discord Teleport 봇을 초대합니다. 봇이 채널 멤버 목록에 나타나야 합니다.
웹 브라우저 URL은 다음과 같아야 합니다:
https://discord.com/channels/<guild ID>/<channel ID>
URL의 마지막 부분(마지막 / 이후 모두)을 복사합니다. 이것이 채널 ID입니다.
사용자 A와 Teleport 봇 간의 개인 대화의 채널 ID를 가져오려면 사용자 A가 Teleport 봇에게 다이렉트 메시지를 보냅니다. 그러면 사용자와 봇 간의 대화가 열립니다. 대화가 시작되면 사용자가 대화 페이지를 열 수 있습니다.
웹 브라우저 URL은 다음과 같아야 합니다:
https://discord.com/channels/@me/<channel ID>
URL의 마지막 부분(마지막 / 이후 모두)을 복사합니다. 이것이 채널 ID입니다.
role_to_recipients 맵에서 각 키는 Teleport 역할의 이름입니다. 각 값은 알릴 Discord 채널(또는 채널들)을 구성합니다.
role_to_recipients 맵에는 "*" 항목도 포함되어야 합니다. 이 항목은 주어진 역할 이름과 일치하는 다른 항목이 없을 때 플러그인이 조회합니다. 위의 예에서 dev 이외의 역할에 대한 요청은 security-team 채널에 알립니다.
다음을 role_to_recipients 구성에 추가하여 사용자가 editor 역할을 요청할 때 알리도록 Discord 플러그인을 구성합니다(YOUR-CHANNEL-ID를 유효한 채널 ID로 교체):
다음은 role_to_recipients 맵의 예입니다. 각 값은 단일 문자열 또는 문자열 배열일 수 있습니다:
[role_to_recipients]
"*" = "YOUR-CHANNEL-ID"
"editor" = "YOUR-CHANNEL-ID"
Helm chart에서 role_to_recipients 필드는 roleToRecipients라고 하며 키는 문자열이고 값은 문자열 배열인 다음 형식을 사용합니다:
roleToRecipients:
"*": ["YOUR-CHANNEL-ID"]
"editor": ["YOUR-CHANNEL-ID"]
최종 구성 파일은 다음과 유사해야 합니다:
<div class="admonition note"><div class="admonition-title">Note</div><p>이 섹션의 내용은 원문 문서를 참조하세요. (<code>teleport-discord.toml</code>)</p></div>
<div class="admonition note"><div class="admonition-title">Note</div><p>이 섹션의 내용은 원문 문서를 참조하세요. (<code>teleport-discord-helm.yaml</code>)</p></div>
7/8단계. Discord 앱 테스트#
Teleport가 실행 중이고 Discord 앱을 만들고 플러그인이 구성되면 플러그인을 실행하고 워크플로를 테스트할 수 있습니다.
플러그인 시작:
$ teleport-discord start
모든 것이 정상적으로 작동하면 로그 출력은 다음과 같아야 합니다:
$ teleport-discord start
INFO Starting Teleport Access Discord Plugin (=teleport.version=): discord/app.go:80
INFO Plugin is ready discord/app.go:101
플러그인 시작:
$ docker run -v <path-to-config>:/etc/teleport-discord.toml public.ecr.aws/gravitational/teleport-plugin-discord:(=teleport.version=) start
플러그인 설치:
$ helm upgrade --install teleport-plugin-discord teleport/teleport-plugin-discord --values teleport-discord-helm.yaml
플러그인 로그를 검사하려면 다음 명령을 사용합니다:
$ kubectl logs deploy/teleport-plugin-discord
디버그 로그는 teleport-discord-helm.yaml에서 log.severity를 DEBUG로 설정하고 위의 helm upgrade ... 명령을 다시 실행하여 활성화할 수 있습니다. 그런 다음 다음 명령으로 플러그인을 재시작할 수 있습니다:
$ kubectl rollout restart deployment teleport-plugin-discord
접근 요청을 만들고 다음 단계를 통해 플러그인이 예상대로 작동하는지 확인합니다.
접근 요청 만들기#
요청을 검토하도록 이전에 구성한 채널은 Discord에서 "Teleport"의 메시지를 받아 Teleport Web UI의 링크를 방문하여 요청을 승인하거나 거부할 수 있게 합니다.
요청 해결#
Once you receive an Access Request message, click the link to visit Teleport and approve or deny the request:
Reviewing from the command line
You can also review an Access Request from the command line:
요청이 해결되면 Discord 봇은 요청이 승인되었는지 거부되었는지에 따라 접근 요청 메시지를 ✅ 또는 ❌로 업데이트합니다.
Discord 플러그인이 채널에 접근 요청 알림을 게시할 때 채널에 접근할 수 있는 모든 사람이 알림을 보고 링크를 따를 수 있습니다. 사용자가 접근 요청을 검토하려면 Teleport 역할을 통해 권한이 부여되어야 하지만, 올바른 사용자가 올바른 요청을 검토하고 있는지 확인하기 위해 Teleport 감사 로그를 확인해야 합니다.
접근 요청 검토를 감사할 때 Teleport Web UI에서 Access Request Reviewed 유형의 이벤트를 확인합니다.
8/8단계. systemd 설정#
이 섹션은 Linux 호스트에서 Teleport Discord 플러그인을 실행하는 경우에만 해당됩니다.
프로덕션 환경에서는 systemd와 같은 초기화 시스템을 통해 Teleport 플러그인 데몬을 시작하는 것을 권장합니다. 다음은 systemd에 권장되는 Teleport 플러그인 서비스 유닛 파일입니다:
<div class="admonition note"><div class="admonition-title">Note</div><p>이 섹션의 내용은 원문 문서를 참조하세요. (<code>teleport-discord.service</code>)</p></div>
이것을 /usr/lib/systemd/system/ 또는 systemd에서 지원하는 다른 유닛 파일 로드 경로에 teleport-discord.service로 저장합니다.
플러그인을 활성화하고 시작합니다:
$ sudo systemctl enable teleport-discord
$ sudo systemctl start teleport-discord
문제 해결#
이 섹션의 내용은 원문 문서를 참조하세요. (access-plugin-troubleshooting.mdx)