Quickstart

Pangea’s AuthZ service enables authorization to be defined outside of your code, providing a safer and more secure application for your users. An important resource for understanding the concepts used in AuthZ is the Definitions section of the Overview page.

Configuring the AuthZ service

These steps are an overview of how to configure AuthZ for your application. For more information, and a complete set of step-by-step instructions, refer to our service documentation.

1. Navigate to the Pangea User Console .

2. Sign up to Pangea. As part of the sign up process, an Organization and a project will be created.

3. Activate the AuthZ service by selecting it in the left-hand navigation sidebar and following the prompts.

   note

   The examples below assume that you have activated your AuthZ service with the File Drive option.

4. Define your resource types and roles in your Authz schema.

5. Map your resource types and roles to instances of resources and subjects in your application data.

Add AuthZ to your app

Language

Python

JavaScript

Go

Java

C#

The steps below will walk you through the basics of integrating AuthZ with a Python app, including a completed code sample for getting started with creating and assigning roles and resources via tuples. For a more in-depth explanation of the sample app, you can visit our Python SDK.

Set your environment variables

Before starting to code, it is necessary to export your token and domain variables to your project if you have not already added them to your environment.

1. Open up a bash terminal window.
2. Type the following commands, replacing 'yourServiceDomain' and 'yourAccessToken' with your Domain and Default Token copied from the AuthZ page in the Pangea User Console.

export PANGEA_DOMAIN="yourServiceDomain"

export PANGEA_AUTHZ_TOKEN="yourAccessToken"

Writing the AuthZ code

1. In order to be ready to code, you must first install the Pangea SDK. To add the Pangea Python SDK to your project, you will need to run one of the following commands in your project root directory based on your preferred installation method.

Install SDK via pip:

pip3 install pangea-sdk

or

Install SDK via poetry:

poetry add pangea-sdk

2. Next, import the Pangea libraries into your code.

Python

Code Snippet Language

from os import getenv
from secrets import token_hex

from pangea.config import PangeaConfig
from pangea.services import AuthZ
from pangea.services.authz import Resource, Subject, Tuple, TupleListFilter

3. The following loads the client configuration while adding the token and domain from your environment variables so you can authenticate with Pangea. You can read more about how Pangea uses tokens on our Tokens page.

Python

Code Snippet Language

pangea_domain = getenv("PANGEA_TOKEN", "aws.us.pangea.cloud")
pangea_authz_token = getenv("PANGEA_AUTHZ_TOKEN", "")

4. Next you need to create an AuthZ API client by mapping the variables to their relevant objects and then wrapping it all with the authz string. This will simplify making API calls later.

Python

Code Snippet Language

authz = AuthZ(token=pangea_authz_token, config=PangeaConfig(domain=pangea_domain))

5. After creating an AuthZ client, you should load your resources to your app so that these can be mapped to AuthZ resources. The following is mock data that shows an example of how to do it.

Python

Code Snippet Language

folder_id = f"folder_{token_hex(8)}"
user_id = f"user_{token_hex(8)}"
role = "reader"
other_role = "editor"

6. After loading your data, you need to define relationships using a tuple. This sets the access levels of your subjects on your resources based on the permissions you allowed to each role or resource type in AuthZ in the Pangea User Console . You will need to replace the <role> placeholder text with a role from your app. The last line prints the relationship that was defined for verification purposes.

Python

Code Snippet Language

authz.tuple_create(
    [
        Tuple(
            resource=Resource(type="folder", id=folder_id),
            relation=role,
            subject=Subject(type="user", id=user_id),
        )
    ]
)
print(f"user '{user_id}' is a '<role>' for folder '{folder_id}'")

7. This code snippet filters for the tuple that was created.

Python

Code Snippet Language

list_response = authz.tuple_list(filter=TupleListFilter(resource_type="folder", resource_id=folder_id))

8. Now that you have created relationships between subjects and resources, you can perform checks to verify the actions available to that subject on a particular resource. This checks that a given user has an expected role for a resource and will return a true statement if so.

Python

Code Snippet Language

check_response = authz.check(
    resource=Resource(type="folder", id=folder_id),
    action=role,
    subject=Subject(type="user", id=user_id),
)

9. It is also important to check for negative responses to verify that the user is denied access to actions that they should not be able to perform, or resources they should not be able to view.

Python

Code Snippet Language

check_response = authz.check(
    resource=Resource(type="folder", id=folder_id),
    action=other_role,
    subject=Subject(type="user", id=user_id),
)

10. Finally, it is important to be able to remove access as well. This code snippet allows you to delete a tuple that provided the user a role and access to a resource.

Python

Code Snippet Language

authz.tuple_delete(
    [
        Tuple(
            resource=Resource(type="folder", id=folder_id),
            relation=role,
            subject=Subject(type="user", id=user_id),
        )
    ]
)

Complete code

Python

Code Snippet Language

from os import getenv
from secrets import token_hex

from pangea.config import PangeaConfig
from pangea.services import AuthZ
from pangea.services.authz import Resource, Subject, Tuple, TupleListFilter

# Load configuration from environment variables.
pangea_domain = getenv("PANGEA_DOMAIN", "aws.us.pangea.cloud")
pangea_authz_token = getenv("PANGEA_AUTHZ_TOKEN", "")

# Create an AuthZ API client.
authz = AuthZ(token=pangea_authz_token, config=PangeaConfig(domain=pangea_domain))

# Mock data.
folder_id = f"folder_{token_hex(8)}"
user_id = f"user_{token_hex(8)}"
role = "reader"
other_role = "editor"

# Create a tuple.
authz.tuple_create(
    [
        Tuple(
            resource=Resource(type="folder", id=folder_id),
            relation=role,
            subject=Subject(type="user", id=user_id),
        )
    ]
)
print(f"user '{user_id}' is a '{role}' for folder '{folder_id}'")

# Find the tuple that was just created.
list_response = authz.tuple_list(filter=TupleListFilter(resource_type="folder", resource_id=folder_id))
# @example
# list_response.result
# ⇒ tuples = [
# ⇒     Tuple(
# ⇒         resource=Resource(type="folder", id="folder_82fe59c0fcde13e9"),
# ⇒         relation="reader",
# ⇒         subject=Subject(type="user", id="user_ce0c2fb57043e65f", action=None),
# ⇒     )
# ⇒ ]

# Check permissions.
check_response = authz.check(
    resource=Resource(type="folder", id=folder_id),
    action=other_role,
    subject=Subject(type="user", id=user_id),
)
print(f"user '{user_id}' is a '{other_role}' for folder '{folder_id}': '{check_response.result.allowed}'")

# Check permissions.
check_response = authz.check(
    resource=Resource(type="folder", id=folder_id),
    action=role,
    subject=Subject(type="user", id=user_id),
)
print(f"user '{user_id}' is a '{role}' for folder '{folder_id}': '{check_response.result.allowed}'")

# Delete the tuple.
authz.tuple_delete(
    [
        Tuple(
            resource=Resource(type="folder", id=folder_id),
            relation=role,
            subject=Subject(type="user", id=user_id),
        )
    ]
)
check_response = authz.check(
    resource=Resource(type="folder", id=folder_id),
    action=role,
    subject=Subject(type="user", id=user_id),
)
print(f"user '{user_id}' is a '{role}' for folder '{folder_id}': '{check_response.result.allowed}'")

Improving your app

The purpose of this guide is to provide the minimum steps required to start coding with our AuthZ service, however there are additional features that can be added to this process, such as audit logging. Read more about the capabilities on our AuthZ Overview page.

Next steps

• Check out our Admin Guide if you have a specific configuration task you would like to complete.
• If you are feeling confident, you can browse our APIs or explore our Github repo, which has libraries for supported languages, SDKs, sample apps, etc.
• For any questions, you can connect with our Pangea Discourse or continue exploring our AuthZ documentation.

Was this article helpful?

Contact us