# 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](https://accounts.abbey.io/sign-up) - keep this page open, you'll need it for the rest of the tutorial!
2. Log into your [GitHub](https://github.com/) account
{% hint style="info" %}
Abbey works with both GitHub and GitHub Enterprise (Cloud).
{% endhint %}
## Check the Demo Site
Go to [Abbey Demo Site](https://app.abbey.io/demo), login, and you'll see the following screen below
No access to demo site
{% hint style="info" %}
:checkered\_flag: 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.
{% endhint %}
## Step 1: Clone this Repo in Git
{% hint style="info" %}
For this step, you'll be working in
* Github
{% endhint %}
First, we'll create a new repo in your GitHub account based off our quickstart template repo.
1. Go to our [Quickstart on Gitub](https://github.com/abbeylabs/abbey-starter-kit-quickstart)
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
{% hint style="info" %}
:checkered\_flag: At this point, you should have a repository in your own GitHub account that is based off the Abbey Quickstart Repository
{% endhint %}
## Step 2: Connect Abbey to your Repo
{% hint style="info" %}
For this step, you'll be working in
* Abbey App
* GitHub
{% endhint %}
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](https://app.abbey.io))
2. Go to the **Settings > Version Control** page and click :heavy\_plus\_sign:**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 :tada:
{% hint style="info" %}
:checkered\_flag: 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
{% endhint %}
## Step 3: Configure Permissions for Abbey
{% hint style="info" %}
For this step, you'll be working in
* Abbey App
* Github
{% endhint %}
### 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. :warning: 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.
{% hint style="info" %}
:checkered\_flag: Great! Now you've allowed Abbey to interact with the new repository you just created to manage access requests.
{% endhint %}
## Step 4: Configure your Grant Kit
{% hint style="info" %}
For this step, you'll be working in
* GitHub Web IDE (github.dev)
{% endhint %}
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](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) 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`
{% code title="main.tf" %}
```hcl
locals {
account_name = "" #CHANGEME
repo_name = "" #CHANGEME
...
}
```
{% endcode %}
### Configuring Reviewers
Workflow defines who should approve an access request.
Let's update the `reviewers` block by adding yourself as the reviewer by switching `replace-me@example.com` with the email address you use to sign into Abbey.
{% code title="main.tf" %}
```diff
resource "abbey_grant_kit" "abbey_demo" {
name = "Abbey_Demo_Site"
...
workflow = {
steps = [
{
reviewers = {
- one_of = ["replace-me@example.com"] # CHANGEME
+ one_of = ["alice@example.com"]
```
{% endcode %}
### 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.
{% hint style="info" %}
:checkered\_flag: 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.
{% endhint %}
## Step 5: Deploy your Grant Kit
{% hint style="info" %}
For this step, you'll be working in
* GitHub Web IDE (github.dev)
{% endhint %}
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:
```sh
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.
{% hint style="info" %}
:tada: 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.
{% endhint %}
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 :x: next to it instead of :white\_check\_mark:
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 or in our [Slack](https://join.slack.com/t/abbey-io/shared_invite/zt-28t1taumd-mI7Kg4pN0X9RYkcTB7NkIw) - we'd love to help!
## Step 6: Make an Access Request
{% hint style="info" %}
For this step, you'll be working in
* Abbey App
{% endhint %}
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
{% hint style="info" %}
:tada: 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.
{% endhint %}
## Step 7: Approve an Access Request
{% hint style="info" %}
For this step, you'll be working in
* Abbey App
{% endhint %}
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](https://app.abbey.io/demo). You should see the following screen!
## Wrap up
Congrats :tada: 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
* :books: Check out our [how-abbey-works](https://docs.abbey.io/how-abbey-works "mention") docs for a high level breakdown
* :construction\_worker: Get hands on with our [tutorials](https://docs.abbey.io/getting-started/tutorials "mention") that integrate other services like AWS, GCP, Azure and more
