
With Teleport Access Requests, you can assign Teleport users to less privileged roles by default and allow them to temporarily escalate their privileges. Reviewers can grant or deny Access Requests within your organization's existing communication workflows (e.g., Slack, email, and PagerDuty) using Access Request plugins.
You can use Teleport's API client library to build an Access Request plugin that integrates with your organization's unique workflows.
In this guide, we will explore a number of Teleport's API client libraries by showing you how to write a plugin that lets you manage Access Requests via Google Sheets. The plugin lists new Access Requests in a Google Sheets spreadsheet, with links to allow or deny each request. You can write the plugin in 260 lines of Go code.

The plugin we will build in this guide is intended as a learning tool. Do not connect it to your production Teleport cluster. Use a demo cluster instead.
Prerequisites
-
A running Teleport Enterprise cluster, including the Auth Service and Proxy Service. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 12.1.1, which you can download by visiting the customer portal.tctl versionTeleport Enterprise v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
Please use the latest version of Teleport Enterprise documentation.
- Go version 1.19+ installed on your workstation. See the Go download page. You do not need to be familiar with Go to complete this guide, though Go knowledge is required if you want to build your own Access Request plugin.
You will need the following in order to set up the demo plugin, which requires authenticating to the Google Sheets API:
- A Google Cloud project with permissions to create service accounts.
- A Google account that you will use to create a Google Sheets spreadsheet. We will grant permissions to edit the spreadsheet to the service account used for the plugin.
Even if you do not plan to set up the demo project, you can follow this guide to see which libraries, types, and functions you can use to develop an Access Request plugin.
The demo is a minimal working example, and you can see fully fledged plugins in
the
gravitational/teleport-plugins
repository on GitHub.
Step 1/7. Set up your Go project
The first step is to create a project directory and initialize a Go module for your project:
mkdir teleport-sheetscd teleport-sheetsgo mod init teleport-sheetsgo: creating new go.mod: module teleport-sheets
This creates a new file in your project directory, go.mod
, which Go's package
management system uses to fetch your plugin's dependencies.
Step 2/7. Set up the Google Sheets API
Access Request plugins typically communicate with two APIs. They receive Access Request events from the Teleport Auth Service's gRPC API, and use the data to interact with the API of your chosen messaging or collaboration tool.
In this section, we will enable the Google Sheets API, create a Google Cloud service account for the plugin, and use the service account to authenticate the plugin to Google Sheets.
Enable the Google Sheets API
Enable the Google Sheets API by visiting the following Google Cloud console URL:
https://console.cloud.google.com/apis/enableflow?apiid=sheets.googleapis.com
Ensure that your Google Cloud project is the one you intend to use.
Click Next > Enable.
Create a Google Cloud service account for the plugin
Visit the following Google Cloud console URL:
https://console.cloud.google.com/iam-admin/serviceaccounts
Click Create Service Account.
For Service account name, enter "Teleport Google Sheets Plugin". Google Cloud will populate the Service account ID field for you.
Click Create and Continue. When prompted to grant roles to the service account, click Continue again. We will create our service account without roles. Skip the step to grant users access to the service account, clicking Done.
The console will take you to the Service accounts view. Click the name of the service account you just created, then click the Keys tab. Click Add Key, then Create new key. Leave the Key type as "JSON" and click Create.
Save your Google Cloud credentials file as credentials.json
in your Go project
directory.
Your plugin will use this JSON file to authenticate to Google Sheets.
Create a Google Sheets spreadsheet
Visit the following URL and make sure you are authenticated as the correct user:
Name your spreadsheet.
Give the plugin access to the spreadsheet by clicking Share. In the Add
people and groups field, enter
[email protected]_NAME.iam.gserviceaccount.com
, replacing
PROJECT_NAME
with the name of your project. Make sure that the service account
has "Editor" permissions. Click Share, then Share anyway when prompted
with a warning.
By authenticating to Google Sheets with the service account you created, the plugin will have access to modify your spreadsheet.
Next, ensure that the following is true within your spreadsheet:
- There is only one sheet
- The sheet includes the following columns:
ID | Created | User | Roles | Status | Link |
---|
After we write our Access Request plugin, it will populate the spreadsheet with data automatically.
Step 3/7. Set up Teleport RBAC
In this section, we will set up Teleport roles that enable creating and reviewing Access Requests, plus another Teleport role that can generate credentials for your Access Request plugin to authenticate to Teleport.
Create a user and role for the plugin
Teleport's Access Request plugins authenticate to your Teleport cluster as a user with permissions to list and read Access Requests. This way, plugins can retrieve Access Requests from the Teleport Auth Service and present them to reviewers.
Define a user and role called access-plugin
by adding the following content to
a file called 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
Create the user and role:
tctl create -f access-plugin.yaml
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 using tctl
from the Auth
Service host, you will already have impersonation privileges.
To grant your user impersonation privileges for access-plugin
, define a role
called access-plugin-impersonator
by pasting the following YAML document into
a file called access-plugin-impersonator.yaml
:
kind: role
version: v5
metadata:
name: access-plugin-impersonator
spec:
allow:
impersonate:
roles:
- access-plugin
users:
- access-plugin
Create the access-plugin-impersonator
role:
tctl create -f access-plugin-impersonator.yaml
Assign the access-plugin-impersonator
role to your Teleport user by running the following
commands, depending on whether you authenticate as a local Teleport user or via
the github
, saml
, or oidc
authentication connectors:
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
Edit out.yaml
, adding access-plugin-impersonator
to the list of existing roles:
roles:
- access
- auditor
- editor
+ - access-plugin-impersonator
Apply your changes:
tctl create -f out.yaml
Retrieve your github
configuration resource:
tctl get github/github --with-secrets > github.yaml
Edit github.yaml
, adding access-plugin-impersonator
to the
teams_to_roles
section. The team you will map to this role will depend on how
you have designed your organization's RBAC, but it should be the smallest team
possible within your organization. This team must also include your user.
Here is an example:
teams_to_roles:
- organization: octocats
team: admins
roles:
- access
+ - access-plugin-impersonator
Apply your changes:
tctl create -f github.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your saml
configuration resource:
tctl get --with-secrets saml/mysaml > saml.yaml
Edit saml.yaml
, adding access-plugin-impersonator
to the
attributes_to_roles
section. The attribute you will map to this role will
depend on how you have designed your organization's RBAC, but it should be the
smallest group possible within your organization. This group must also include
your user.
Here is an example:
attributes_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - access-plugin-impersonator
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your oidc
configuration resource:
tctl get oidc/myoidc --with-secrets > oidc.yaml
Edit oidc.yaml
, adding access-plugin-impersonator
to the
claims_to_roles
section. The claim you will map to this role will depend on
how you have designed your organization's RBAC, but it should be the smallest
group possible within your organization. This group must also include your
user.
Here is an example:
claims_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - access-plugin-impersonator
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Log out of your Teleport cluster and log in again to assume the new role.
You will now be able to generate signed certificates for the access-plugin
role and user.
Export the access plugin identity
You will use the tctl auth sign
command to request the credentials that the
access-plugin
needs to connect to your Teleport cluster.
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=auth.pem
Teleport's Access Request plugins listen for new and updated Access Requests by connecting to the Teleport Auth Service's gRPC endpoint over TLS.
The identity file, auth.pem
, includes both TLS and SSH credentials. Your
Access Request 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.
You will refer to this file later when configuring the plugin.
Set up Role Access Requests
In this guide, we will use our plugin to manage Role Access Requests. For this to work, we will set up Role Access Requests in your cluster.
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: 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
Create the roles you defined:
tctl create -f editor-request-rbac.yamlrole 'editor-reviewer' has been created
role 'editor-requester' has been created
Allow yourself to review requests by users with the editor-requester
role by
assigning yourself the editor-reviewer
role.
Assign the editor-reviewer
role to your Teleport user by running the following
commands, depending on whether you authenticate as a local Teleport user or via
the github
, saml
, or oidc
authentication connectors:
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
Edit out.yaml
, adding editor-reviewer
to the list of existing roles:
roles:
- access
- auditor
- editor
+ - editor-reviewer
Apply your changes:
tctl create -f out.yaml
Retrieve your github
configuration resource:
tctl get github/github --with-secrets > github.yaml
Edit github.yaml
, adding editor-reviewer
to the
teams_to_roles
section. The team you will map to this role will depend on how
you have designed your organization's RBAC, but it should be the smallest team
possible within your organization. This team must also include your user.
Here is an example:
teams_to_roles:
- organization: octocats
team: admins
roles:
- access
+ - editor-reviewer
Apply your changes:
tctl create -f github.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your saml
configuration resource:
tctl get --with-secrets saml/mysaml > saml.yaml
Edit saml.yaml
, adding editor-reviewer
to the
attributes_to_roles
section. The attribute you will map to this role will
depend on how you have designed your organization's RBAC, but it should be the
smallest group possible within your organization. This group must also include
your user.
Here is an example:
attributes_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - editor-reviewer
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your oidc
configuration resource:
tctl get oidc/myoidc --with-secrets > oidc.yaml
Edit oidc.yaml
, adding editor-reviewer
to the
claims_to_roles
section. The claim you will map to this role will depend on
how you have designed your organization's RBAC, but it should be the smallest
group possible within your organization. This group must also include your
user.
Here is an example:
claims_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - editor-reviewer
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Log out of your Teleport cluster and log in again to assume the new role.
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.
Step 4/7. Write the Access Request plugin
At this point, we have completed the preparatory steps required to run an Access Request plugin, including setting up your Teleport roles to support Role Access Requests and getting credentials for the APIs the plugin will authenticate to. Next, we will write the Access Request plugin.
Add imports
Create a file called main.go
in your project directory with the following
content:
package main
import (
"context"
"errors"
"fmt"
"strings"
"time"
"github.com/gravitational/teleport-plugins/lib"
"github.com/gravitational/teleport-plugins/lib/watcherjob"
"github.com/gravitational/teleport/api/client"
"github.com/gravitational/teleport/api/types"
"github.com/gravitational/trace"
"google.golang.org/api/option"
sheets "google.golang.org/api/sheets/v4"
"google.golang.org/grpc"
)
Here are the packages our Access Request plugin will import from Go's standard library:
Package | Description |
---|---|
context | Includes the context.Context type. context.Context is an abstraction for controlling long-running routines, such as connections to external services, that might fail or time out. Programs can cancel contexts or assign them timeouts and metadata. |
errors | Working with errors. |
fmt | Formatting data for printing, strings, or errors. |
time | Dealing with time. We will use this to define a timeout for connecting to the Auth Service. |
strings | Manipulating strings. |
The plugin imports the following third-party code:
Package | Description |
---|---|
github.com/gravitational/teleport-plugins/lib | Code shared between Teleport plugins, e.g., to run a background job for retrieving new events from the Teleport Auth Service. |
github.com/gravitational/teleport-plugins/lib/watcherjob | A library for writing programs that listen for audit events from the Auth Service. |
github.com/gravitational/teleport/api/client | A library for authenticating to the Auth Service's gRPC API and making requests. |
github.com/gravitational/teleport/api/types | Types used in the Auth Service API, e.g., Access Requests. |
github.com/gravitational/trace | Presenting errors with more useful detail than the standard library provides. |
google.golang.org/api/option | Settings for configuring Google API clients. |
google.golang.org/api/sheets/v4 | The Google Sheets API client library, aliased as sheets in our program. |
google.golang.org/grpc | The gRPC client and server library. |
Make some initial declarations
After the import
block, add the following declarations:
const (
proxyAddr string = ""
initTimeout = time.Duration(30) * time.Second
spreadSheetID string = ""
)
var requestStates = map[types.RequestState]string{
types.RequestState_APPROVED: "APPROVED",
types.RequestState_DENIED: "DENIED",
types.RequestState_PENDING: "PENDING",
types.RequestState_NONE: "NONE",
}
type googleSheetsPlugin struct {
sheetsClient *sheets.SpreadsheetsService
teleportClient *client.Client
}
proxyAddr
indicates the hostname and port of your Teleport Proxy Service or
Teleport Enterprise Cloud tenant. Assign it to the address of your own Proxy
Service, e.g., mytenant.teleport.sh:443
.
initTimeout
is the maximum time we will wait to connect to the Auth Service,
in this case, 30 seconds.
Assign spreadSheetID
to the ID of the spreadsheet you created earlier. To find
the spreadsheet ID, visit your spreadsheet in Google Drive. The ID will be in
the URL path segment called SPREADSHEET_ID
below:
https://docs.google.com/spreadsheets/d/SPREADHSEET_ID/edit#gid=0
Access Requests have one of four states: approved, denied, pending, and none.
Later in the guide, we will need a way to map these states to strings that we
can write to our Google Sheets spreadsheet. We obtain the request states from
Teleport's types
library and map them to strings in the requestStates
map.
googleSheetsPlugin
is a struct type that contains the API clients for the
Teleport Auth Service and Google Sheets. We will explain later why we use a
struct to organize these two clients, instead of, say, two separate variables.
Prepare row data
Whether creating a new row of the spreadsheet or updating an existing one, we
need a way to extract data from an Access Request in order to provide it to
Google Sheets. Below the googleSheetsPlugin
type declaration, add the
following functions:
func stringPtr(s string) *string { return &s }
func (g *googleSheetsPlugin) makeRowData(ar types.AccessRequest) *sheets.RowData {
requestState, ok := requestStates[ar.GetState()]
// Could not find a state, but this is still a valid Access Request
if !ok {
requestState = requestStates[types.RequestState_NONE]
}
viewLink := fmt.Sprintf(
`=HYPERLINK("%v", "%v")`,
"https://"+proxyAddr+"/web/requests/"+ar.GetName(),
"View Access Request",
)
return &sheets.RowData{
Values: []*sheets.CellData{
&sheets.CellData{
UserEnteredValue: &sheets.ExtendedValue{
StringValue: stringPtr(ar.GetName()),
},
},
&sheets.CellData{
UserEnteredValue: &sheets.ExtendedValue{
StringValue: stringPtr(ar.GetCreationTime().String()),
},
},
&sheets.CellData{
UserEnteredValue: &sheets.ExtendedValue{
StringValue: stringPtr(ar.GetUser()),
},
},
&sheets.CellData{
UserEnteredValue: &sheets.ExtendedValue{
StringValue: stringPtr(strings.Join(ar.GetRoles(), ",")),
},
},
&sheets.CellData{
UserEnteredValue: &sheets.ExtendedValue{
StringValue: &requestState,
},
},
&sheets.CellData{
UserEnteredValue: &sheets.ExtendedValue{
FormulaValue: &viewLink,
},
},
},
}
}
The sheets.RowData
type makes extensive use of pointers to strings, so we
introduce a utility function called stringPtr
that returns the pointer to the
provided string. This makes it easier to assign the values of cells in the
sheets.RowData
using chains of function calls.
makeRowData
is a method of the googleSheetsPlugin
type. (The *
before
googleSheetsPlugin
indicates that the method receives a pointer to a
googleSheetsPlugin
.) It takes a types.AccessRequest
, which Teleport's API
library uses to represent the fields within an Access Request.
The Google Sheets client library defines a sheets.RowData
type that we
include in requests to update a spreadsheet. This function converts a
types.AccessRequest
into a *sheets.RowData
(another pointer).
When extracting the data, we use the types.AccessRequest.GetName()
method to
retrieve the ID of the Access Request as a string we can include in the
spreadsheet.
Users can review an Access Request by visiting a URL within the Teleport Web UI
that corresponds to the request's ID. makeRowData
assembles a =HYPERLINK
formula that we can insert into the spreadsheet as a link to this URL.
Next, we'll add two functions that call makeRowData
, one to create a new row
and one to update an existing row.
Create a row
Below makeRowData
, add the following:
func (g *googleSheetsPlugin) createRow(ar types.AccessRequest) error {
row := g.makeRowData(ar)
req := sheets.BatchUpdateSpreadsheetRequest{
Requests: []*sheets.Request{
{
AppendCells: &sheets.AppendCellsRequest{
Fields: "*",
Rows: []*sheets.RowData{
row,
},
},
},
},
}
resp, err := g.sheetsClient.BatchUpdate(spreadSheetID, &req).Do()
if err != nil {
return trace.Wrap(err)
}
if resp.HTTPStatusCode == 201 || resp.HTTPStatusCode == 200 {
fmt.Println("Successfully created a row")
} else {
fmt.Printf(
"Unexpected response code creating a row: %v\n",
resp.HTTPStatusCode,
)
}
return nil
}
createRow
submits a request to the Google Sheets API to create a new row based
on an incoming Access Request, using the data returned by makeRowData
. It
returns an error if the attempt to create a row failed.
It assembles a sheets.BatchUpdateSpreadsheetRequest
and sends it to the Google
Sheets API using g.sheetsClient.BatchUpdate()
, returning errors encountered
while sending the request.
We log unexpected HTTP status codes without returning an error since these may be transient server-side issues. A production Access Request plugin would handle these situations in a more sophisticated way, e.g., storing the request so it can retry it later.
Update a row
The code for updating a row is similar to the code for creating a new row. Add
this function below createRow
:
func (g *googleSheetsPlugin) updateRow(ar types.AccessRequest, rowNum int64) error {
row := g.makeRowData(ar)
req := sheets.BatchUpdateSpreadsheetRequest{
Requests: []*sheets.Request{
{
UpdateCells: &sheets.UpdateCellsRequest{
Fields: "*",
Start: &sheets.GridCoordinate{
RowIndex: rowNum,
},
Rows: []*sheets.RowData{
row,
},
},
},
},
}
resp, err := g.sheetsClient.BatchUpdate(spreadSheetID, &req).Do()
if err != nil {
return trace.Wrap(err)
}
if resp.HTTPStatusCode == 201 || resp.HTTPStatusCode == 200 {
fmt.Println("Successfully updated a row")
} else {
fmt.Printf(
"Unexpected response code updating a row: %v\n",
resp.HTTPStatusCode,
)
}
return nil
}
The only difference between updateRow
and createRow
is that we send a
&sheets.UpdateCellsRequest
instead of a &sheets.AppendCellsRequest
. This
function takes the number of a row within the spreadsheet to update and sends a
request to update that row with information from the provided Access Request.
Determine where to update the spreadsheet
Below updateRow
, add this function:
func (g *googleSheetsPlugin) updateSpreadsheet(ar types.AccessRequest) error {
s, err := g.sheetsClient.Get(spreadSheetID).IncludeGridData(true).Do()
if err != nil {
return trace.Wrap(err)
}
if len(s.Sheets) != 1 {
return trace.Wrap(
errors.New("the spreadsheet must have a single sheet"),
)
}
for _, d := range s.Sheets[0].Data {
for i, r := range d.RowData {
if r.Values[0] != nil &&
r.Values[0].UserEnteredValue != nil &&
r.Values[0].UserEnteredValue.StringValue != nil &&
*r.Values[0].UserEnteredValue.StringValue == ar.GetName() {
if err := g.updateRow(ar, int64(i)); err != nil {
return trace.Wrap(err)
}
fmt.Println("Updated a spreadsheet row.")
}
}
}
return nil
}
updateSpreadSheet
takes a types.AccessRequest
, gets the latest data from
your spreadsheet, determines which row to update, and calls updateRow
accordingly. It uses linear search to look up the first column within each row
of the sheet and check whether that column matches the ID of the Access Request.
It then calls updateRow
with the Access Request and the row's number.
Handle incoming Access Requests
Next, we will determine whether to call updateSpreadsheet
or createRow
depending on whether an incoming Access Request event is a new Access Request or
an update to an existing one. Add the following function below
updateSpreadsheet
:
func (g *googleSheetsPlugin) handleEvent(ctx context.Context, event types.Event) error {
if event.Resource == nil {
return nil
}
r := event.Resource.(types.AccessRequest)
if r.GetState() == types.RequestState_PENDING {
return g.createRow(r)
}
return g.updateSpreadsheet(r)
}
handleEvent
checks whether an Access Request is in a pending state, i.e.,
whether the request is new. If so, we call createRow
. If not, we call
updateSpreadsheet
.
It is worth noting that the function takes any types.Event
, which includes
Access Requests but also other audit events, such as the creation of a
certificate. We will explain in the next section why we are using this function
signature for handleEvent
.
Run a watcher job
Now that we have a function that can handle incoming Teleport events, we will
add a function that calls our handler function when it receives an event. Add
the following below handleEvent
:
func (g *googleSheetsPlugin) run() error {
ctx := context.Background()
proc := lib.NewProcess(ctx)
watcherJob := watcherjob.NewJob(
g.teleportClient,
watcherjob.Config{
Watch: types.Watch{Kinds: []types.WatchKind{types.WatchKind{Kind: types.KindAccessRequest}}},
},
g.handleEvent,
)
proc.SpawnCriticalJob(watcherJob)
fmt.Println("Started the watcher job")
<-watcherJob.Done()
fmt.Println("The watcher job is finished")
return nil
}
The run
function starts a new background routine using lib.NewProcess(ctx)
.
This returns an implementation of the lib.Process
interface, which Access
Request plugins use to run jobs independently of the main program. This function
takes a Go context, an abstraction that Go libraries often use to control
long-running routines.
Next, run
calls watcherjob.NewJob
. A watcher job is an implementation of a
lib.ServiceJob
, a task for the lib.Process
to execute. In this case, the
lib.ServiceJob
listens for new events from the Teleport Auth Service and
executes code in response.
In watcherjob.NewJob
, we have configured the watcher job to use a Teleport
client (which we will create in the next section), as well as to watch only for
Access Request events.
Finally, by passing the g.handleEvent
method to watcherjob.NewJob
, we
instruct the watcher job to call g.handleEvent
whenever it receives an Access
Request. The function we pass to watcherjob.NewJob
must have the following
signature, which we implement in the handleEvent
method:
func (ctx context.Context, event types.Event) error
This is also why we define handleEvent
as a method of googleSheetsPlugin
,
since it means that we can include data about our API clients in this function
while adhering to the expected function signature (and without declaring more
global variables).
Finally, we begin the watcher job within our lib.Process
using
proc.SpawnCriticalJob
, and wait for the job to terminate. We do this by
receiving from a Go channel, which is a way for multiple concurrent routines
to communicate with one another.
Initialize the API clients
Now we have all the code we need to use the Teleport and Google Sheets API clients to listen for Access Request events and use them to maintain a spreadsheet. The final step is to start our program by initializing the API clients.
Add the following below the run
function we defined in the last section:
func main() {
ctx := context.Background()
svc, err := sheets.NewService(ctx, option.WithCredentialsFile("credentials.json"))
if err != nil {
panic(err)
}
ctx, cancel := context.WithTimeout(ctx, initTimeout)
defer cancel()
creds := client.LoadIdentityFile("auth.pem")
teleport, err := client.New(ctx, client.Config{
Addrs: []string{proxyAddr},
Credentials: []client.Credentials{creds},
DialOpts: []grpc.DialOption{
grpc.WithReturnConnectionError(),
},
})
if err != nil {
panic(err)
}
gs := googleSheetsPlugin{
sheetsClient: sheets.NewSpreadsheetsService(svc),
teleportClient: teleport,
}
if err := gs.run(); err != nil {
panic(err)
}
}
The main
function, the entrypoint to our program, initializes a
googleSheetsPlugin
and uses it run the plugin.
The function creates a Google Sheets API client by loading the credentials file
you downloaded earlier at the relative path credentials.json
.
client
is Teleport's library for setting up an API client. Our plugin does so
by calling client.LoadIdentityFile
to obtain a client.Credentials
. It then
uses the client.Credentials
to call client.New
, which connects to the
Teleport Proxy Service specified in the Addrs
field using the provided
identity file.
In this example, we are passing the grpc.WithReturnConnectionError()
function
call to client.New
, which instructs the gRPC client to return more detailed
connection errors.
This program does not validate your credentials or Teleport cluster address. Make sure that:
- The identity file you exported earlier does not have an expired TTL
- The value you supplied for the
proxyAddr
constant includes both the host and the web port of your Teleport Proxy Service, e.g.,mytenant.teleport.sh:443
Step 7/7. Test your plugin
Now that you have written your plugin, run it to forward Access Requests from your Teleport cluster to Google Sheets. Execute the following commands from within your project directory:
go getgo run main.go
Now that the plugin is running, create an Access Request:
A Teleport admin can create an Access Request for another user with tctl
:
tctl request create myuser --roles=editor
Users can use tsh
to create an Access Request and log in with approved roles:
tsh request create --roles=editorSeeking request approval... (id: 8f77d2d1-2bbf-4031-a300-58926237a807)
Users can request access using the Web UI by visiting the "Access Requests" tab and clicking "New Request":

You should see the new Access Request in your spreadsheet with the PENDING
state.
In your spreadsheet, click "View Access Request" next to your new request. Sign into the Teleport Web UI as your original user. When you submit your review, e.g., deny the request, the new status will appear within the spreadsheet.
Access Request plugins must not enable reviewing Access Requests via the plugin, and must always refer a reviewer to the Teleport Web UI to complete the review. Otherwise, an unauthorized party could spoof traffic to the plugin and escalate privileges.
Next steps
In this guide, we showed you how to set up an Access Request plugin using Teleport's API client libraries. To go beyond the minimal plugin we demonstrate in this guide, you can use the Teleport API to set up more sophisticated workflows that take full advantage of your communication and project management tools.
Use the common plugin base
The
common.BaseApp
type makes it easier to write an Access Request plugin based on a messaging
application like Discord or Slack, helping to ensure that your plugin implements
a full set of features.
Manage state
While the plugin we developed in this guide is stateless, updating Access
Request information by searching all rows of a spreadsheet, real-world Access
Request plugins typically need to manage state. You can use the
plugindata
package to make it easier for your Access Request plugin to do this.
Consult the examples
Explore the
gravitational/teleport-plugins
repository on GitHub for examples of plugins developed at Teleport. You can see
how these plugins use the packages we discuss in this guide, as well as how they
add more complete functionality like configuration validation and state
management.
Provision the plugin with short-lived credentials
In this example, we used the tctl auth sign
command to fetch credentials for
the plugin. For production usage, we recommend provisioning short-lived
credentials via Machine ID, which reduces the risk of these credentials becoming
stolen. View our Machine ID documentation to
learn more.