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

Abbey works with both GitHub and GitHub Enterprise (Cloud).

Check the Demo Site

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

No access to demo site

🏁 That's expected! You don't have access yet. This Quickstart will allow you to configure a Grant Kit for the demo site so you can request and approve access.

Step 1: Clone this Repo in Git

For this step, you'll be working in

• Github

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

Create new repository from abbey quickstart template repo

🏁 At this point, you should have a repository in your own GitHub account that is based off the Abbey Quickstart Repository

Step 2: Connect Abbey to your Repo

For this step, you'll be working in

• Abbey App

• GitHub

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 🎉

🏁 Congrats! You've now authorized Abbey to talk with the newly created GitHub repo in your personal account

At this point you should

1. Have a connection to GitHub under the Abbey Settings -> Version Control tab

2. Have created a repo into your own GitHub account based off the Abbey Labs Quickstart Repo

3. Have cloned the newly created repo into your own terminal to work with

Step 3: Configure Permissions for Abbey

For this step, you'll be working in

• Abbey App

• Github

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!

Create an Abbey API Token

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

   

   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

Save ABBEY_TOKEN as a Repository Secret

What should it look like?

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

   

   ⚠️ There are multiple Save buttons - make sure to click the Save button in the Workflow permissions section, not the others.

🏁 Great! Now you've allowed Abbey to interact with the new repository you just created to manage access requests.

Step 4: Configure your Grant Kit

For this step, you'll be working in

• GitHub Web IDE (github.dev)

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.

[Recommended] Using the github.dev web-based editor

Go to your repository on Github that you just created

1. Open main.tf in your repository

   
2. Press . or click on the arrow next to the pencil icon to select Open with... -> github.dev

   
3. This will open up the github.dev editor - you can make changes to your files here, and directly push them to your repository.

   

   

Using your own Terminal

1. Click on the <> Code dropdown

2. Copy the text under HTTPS starting with https://

3. Clone the repository in your development environment by running git clone followed by the https:// URL copied from the previous step in your terminal of choice.

Once you copy the URL of the new repo from GitHub, you should

1. Open your terminal (Terminal, iTerm, etc)

2. Type git clone followed by your repo

   1. Example: git clone https://github.com/alice/abbey-starter-kit-quickstart.git

3. cd to the directory via cd abbey-starter-kit-quickstart

More instructions can be found in the GitHub docs if you run into issues while cloning.

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

main.tf

 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 [e-mail] with the email address you use to sign into Abbey.

main.tf

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

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.

common.rego

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

🏁 Great job, you're almost there! Now your grant kit has been fully configured with updated reviewers, policies, and output. Double check that all the lines with #CHANGEME have been updated before moving on to the next step.

We'll commit and push these changes in the next step.

Step 5: Deploy your Grant Kit

For this step, you'll be working in

• GitHub Web IDE (github.dev)

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

[Recommended] Deploying through the github.dev editor

Once you make a change, there will be an icon on the left-side that will pop up. If this doesn't make sure your edits were in the github.dev editor and they were saved.

To submit those changes and deploy your grant kit:

1. Click on the icon circled above

2. Type a commit reason in the box with the label message

3. Click on Commit & Push

   

Deploying using your terminal

To deploy, push to your default branch from your terminal within your repository:

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.

🎉 Congrats! At this point, you should see your deployed grant kit under Abbey Resources. In the next step, we'll show you how to use the grant kit to get access to the demo site.

If it's not showing up, it likely has a configuration issue causing the deployment to fail - open up the Troubleshooting section below for common steps to resolve.

Troubleshooting

1. Open the Actions tab in your GitHub repository

2. Find the corresponding action run to the commit where you added the grant kit and see if it ran successfully. If it failed, open the run to see the failure exception.

   1. A failed run will have a ❌ next to it instead of ✅

A common deployment failure for grant kits is a misconfigured location field in the output block or bundle field in the policies block

• Double check it starts with github://

• Double check repository and username or org name is correct

• Double check for any extra : or /'s

If these don't solve the issue or the error message is unclear, you can always reach us at [e-mail] or in our Slack - we'd love to help!

Step 6: Make an Access Request

For this step, you'll be working in

• Abbey App

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

Make an Access Request

🎉 You just submitted your first access request using Abbey! In the next step, we'll approve the request and then you'll be able to access the demo site.

Step 7: Approve an Access Request

For this step, you'll be working in

• Abbey App

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

Approve an Access Request

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

And you can always reach us at [e-mail] or in our Slack - we'd love to chat!