Quickstart

Introduction

Abbey is an access governance platform that helps you automate access requests and approvals, making it easier for people to get access to resources like AWS S3 or Google Groups. This helps you get access to the resources you need, when you need it.

This tutorial teaches you how to get Abbey up and running, define time-bound access policies, and go through the request/approval flow for getting access to a resource.

Before you start

1. Create an Abbey Account - keep this page open, you'll need it for the rest of the tutorial!

2. Log into your GitHub account

Check the Demo Site

Go to Abbey Demo Site, login, and you'll see the following screen below

Step 1: Clone this Repo in Git

First, we'll create a new repo in your GitHub account based off our quickstart template repo.

1. Go to our Quickstart on Gitub

2. Click on Use this template

   
3. Click on Create a new repository to create the repository

4. Fill out the Repository name

5. Click Create repository

Step 2: Connect Abbey to your Repo

To use Abbey for access requests, you'll need to connect Abbey to your GitHub.

Create a Connection

1. Go to the Abbey App (app.abbey.io)

2. Go to the Settings > Version Control page and click ➕Create a Connection

   
3. Choose a name for your connection, then click Create. You'll be redirected to GitHub to install Abbey on your GitHub account.

   
4. In the Github App Permissions screen, choose either All Repositories or Only select repositories with the repository you created earlier in Step 1 selected

   

5. Once you click Install & Authorize, you'll be redirected back to the Abbey App, and your connection will be created 🎉

Step 3: Configure Permissions for Abbey

Create an Abbey Token

1. Go to Abbey API Tokens via Settings -> API Tokens in the Abbey app

2. Click on the + New API Token

3. Enter a name for your new API token or leave as is

4. Configure the Expires At field or leave it blank to have the token never expire

5. Click Create to make the new key

6. Copy the key - you'll need this for the next step!

Add your Abbey token to Github

1. Navigate to the repo you created in your own GitHub account

2. Go to the Settings tab

3. Select Secrets and Variables -> Actions on the left side

4. Create a new Repository Secret

   
5. For the Name, enter in ABBEY_TOKEN

6. For the Secret, enter in the value of the Abbey API token you created in the last step.

   1. ⚠️ Make sure you don't have any newlines or spaces when copy/pasting this

7. Click Add Secret to finish adding the repository secret

Update Repo Permissions

Abbey needs a few permissions to operate in your GitHub repo.

1. Go to the Settings tab of the same repo you added the API token

2. Select Actions -> General on the left side

3. Scroll to the Workflow Permissions section

4. Select the Read and write permissions button

5. Click on Save in the Workflow Permissions section

   

Step 4: Configure your Grant Kit

We'll now edit the files within the cloned Github repo.

We recommend using Github's native code editor, but feel free to edit the files with whatever tools you prefer.

Grant Kits define who can approve an access request, how long that access should last, and what resource the request is granting access to.

The repository you cloned in the previous step contains the grant kit that we'll be modifying below to grant access to the demo site.

Configuring Output

Grant Kits rely on your GitHub account and repository name to output access changes, which we'll set through Terraform local variables. Update the locals block in main.tf with your account_name and repo_name

 locals {
  account_name = "" #CHANGEME
  repo_name = "" #CHANGEME
  ...
}

Configuring Reviewers

Workflow defines who should approve an access request.

Let's update the reviewers block by adding yourself as the reviewer by switching [email protected] with the email address you use to sign into Abbey.

 resource "abbey_grant_kit" "abbey_demo" {
   name = "Abbey_Demo_Site"
   ...
   workflow = {
     steps = [
       {
         reviewers = {
-          one_of = ["[email protected]"] # CHANGEME
+          one_of = ["[email protected]"]

Configuring Policies

Policies are used to define rules around access requests, such as time-based access or automatic approval if a user is on-call in PagerDuty.

Update the policy in policies/common/common.rego so that access to the Demo Site automatically expires after 1 hour, not 6 hours.

 allow[msg] {
-     functions.expire_after("6h")
+     functions.expire_after("1h")    
-     msg := "granting access for 6 hours"
+     msg := "granting access for 1 hour"
  }

Step 5: Deploy your Grant Kit

Now we're going to take the Grant Kit you modified in the previous step and deploy it to GitHub.

git push origin main

Abbey works with any CI system to deploy your grant kit through Terraform, and for this quickstart we use GitHub Actions - you can look at the Actions tab of your GitHub repo to see Terraform runs.

Step 6: Make an Access Request

We've now completed all the steps for an admin to automate access grants to the Abbey demo site.

Now let's go through the experience as an end user making a request for access.

1. Go to the Resources tab of the Abbey App

2. Find the grant kit with the name Abbey_Demo_Site

3. Click on the Request

4. Click on the Expire after dropdown to customize the time the access should last, otherwise skip to step 5

5. Enter in a reason, then hit Confirm to submit the request

Step 7: Approve an Access Request

For this grant kit, we've set ourselves as the reviewer to make things simple. In a real-world use-case you'd typically set a manager or another team as the approvers.

To approve the request:

1. Go to the Approvals tab of the Abbey App

2. Find the request you just made (there should only be one)

3. Click Approve to the right of the request

4. Enter in a reason, then hit Approve to submit

Step 8: Request Access to the Demo Site

Your access request has been approved, so go ahead and check out the Abbey Demo Site. You should see the following screen!

Wrap up

Congrats 🎉 In this guide, you were able to

• Create a Grant Kit defining access to the Abbey Demo Site

• Add yourself as a reviewer for access requests

• Configure a time-based policy for limiting access to 1 hour max

• Make, and approve, an access request for yourself to gain access to the Demo Site

There are a lot of moving pieces involved, so if you'd like to learn more you can

• 📚 Check out our How Abbey Works docs for a high level breakdown

• 👷 Get hands on with our Step-by-Step Tutorials that integrate other services like AWS, GCP, Azure and more