Skip to main content

Getting Started

This page is designed to give a step-by-step process for getting ready to integrate AuthZ into your app. It has detailed information on setting up the AuthZ service in the Pangea User Console. If you already have those tasks completed, you can view the Overview page for a rundown of the steps necessary in configuring AuthZ for your needs, or check out our Quickstart page for how to integrate it into your app.

Create a token​

The first task is to create a token to use with AuthZ. It is generally a good idea to have a separate token for each enabled service to limit exposure if a token ever becomes compromised.

To enable the AuthZ service and create a token:

  1. Click AuthZ on the left-hand navigation. A dialog with details about authorization will appear. Click Next.
  2. You will be prompted to create a token to access the AuthZ service. There is also an Enable Vault button. It is highly recommended that you store your token in the Pangea Vault for added security.
note

If you click Enable Vault, a modal displays describing Vault features. Click Done to close the modal and return to the AuthZ modal.

  1. Type a Token name and select an Expiration Date, or just keep the default values. Once you are finished configuring your token, click Next.
  2. An additional dialog of example schemas displays. Select Blank Schema and then click Done.

The AuthZ Overview page should display.

Define your AuthZ schema​

The next step in setting up AuthZ is to define your AuthZ schema. This includes defining various resource types, relationships between resource types, permissions for each type, and roles as combinations of these permissions that can be allocated to users. You can configure your AuthZ schema under Resource Types and Roles & Access settings in the Pangea User Console.

Define your AuthZ data​

You can map your application data to your AuthZ schema under Assigned Roles & Relations in the Pangea User Console, or by using the AuthZ APIs. The assigned roles and relations are expressed via tuples, describing the relationships between subjects and resources.

For example, the following tuple received at the /v1/tuple/list endpoint describes a role assignment in a role-based access control (RBAC) implementation. The user, specified via an ID as it exists in your application, is assigned a relationship of type role and inherits all the permissions associated with that role in the AuthZ schema:

RBAC role assignment
{
  "resource": {
    "type": "role"
  },
  "relation": "admin",
  "subject": {
    "type": "user",
    "id": "Daniel"
  }
}

Then, you can extend your AuthZ configuration with the relationship-based access control (ReBAC) paradigm by defining resource-specific roles and relationships. For example, the following tuple represents a relationship in which a user is the author of a blog post. Every permission you assigned to the blog post author role for the blog post resource type will automatically be assigned to the user for this particular blog post. Both the subject and the resource are specified via unique identifiers existing in the application data:

ReBAC resource-specific role assignment
{
  "resource": {
    "type": "blog_post",
    "id": "cats"
  },
  "relation": "author",
  "subject": {
    "type": "user",
    "id": "Rachel"
  }
}

The ReBAC implementation can also describe arbitrary relationships between non-user resource types. For example, a folder could be a parent of a file, or a blog post could be a parent of an image:

ReBAC resource-specific relationship
{
  "resource": {
    "type": "image",
    "id": "cat"
  },
  "relation": "parent",
  "subject": {
    "type": "blog_post",
    "id": "cats"
  }
}

Verify your AuthZ configuration​

Your authorization (AuthZ) schema and data must be properly configured to grant intended access for your subjects to your resources. You can test whether your configuration works as expected using the Playground page in the Pangea User Console.

You can also use the AuthZ APIs directly to explore your AuthZ configuration. For example, you can use the /v1/check endpoint to check whether a subject can act on a resource:

check permissions
curl -sSLX POST 'https://authz.aws.us.pangea.cloud/v1/check' \
-H "Authorization: Bearer $PANGEA_AUTHZ_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
  "resource": {
    "type": "blog_post"
  },
  "action": "delete",
  "subject": {
    "type": "user",
    "id": "Paige"
  }
}'
response
{
  "result": {
    "allowed": false,
    "depth": 0,
    "schema_id": "pzs_o7ik5dy2dfexd3wqnrisxp2zvaex4bul",
    "schema_version": 1
  },
  "status": "Success",
  "summary": "Denied",
  ...
}

Integrate AuthZ into your app​

The final step is to integrate AuthZ into your app. We have created SDKs to help you. We also created a Quickstart guide that will help you understand the various parts of the code as well as how to apply them. If you have any trouble, feel free to reach out to our

Pangea Discourse community and someone will be glad to help you.

Was this article helpful?

Contact us