Skip to main content

Quickstart

About AuthZ

Beta

Pangea’s AuthZ service enables authorization to be defined outside of your code, providing a safer and more secure application for your users.

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 initial token will be created.
  3. Configure the token for use with the AuthZ service.
  4. Set any desired settings in the Vault Settings page.

Add AuthZ to your app​

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 generating a symmetric key, encrypting a message, then decrypting it. 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_SERVICE_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

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

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
  1. 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.

pangea_domain = getenv("PANGEA_TOKEN", "aws.us.pangea.cloud")
pangea_authz_token = getenv("PANGEA_AUTHZ_TOKEN", "")
  1. 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.

authz = AuthZ(token=pangea_authz_token, config=PangeaConfig(domain=pangea_domain))
  1. 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.

folder_id = f"folder_{token_hex(8)}"
user_id = f"user_{token_hex(8)}"
  1. 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.

authz.tuple_create(
    [
        Tuple(
            resource=Resource(namespace="folder", id=folder_id),
            relation="<role>",
            subject=Subject(namespace="user", id=user_id),
        )
    ]
)
print(f"user '{user_id}' is a '<role>' for folder '{folder_id}'")
  1. This code snippet filters for the tuple that was created.

list_response = authz.tuple_list(filter=TupleListFilter(resource_namespace="folder", resource_id=folder_id))
  1. 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 an expected true statement, which you defined earlier.

check_response = authz.check(
    resource=Resource(namespace="folder", id=folder_id),
    action="<role>",
    subject=Subject(namespace="user", id=user_id),
)
  1. 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.

check_response = authz.check(
    resource=Resource(namespace="folder", id=folder_id),
    action="<other_role>",
    subject=Subject(namespace="user", id=user_id),
)
  1. 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.

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

Code sample​

The code sample below is a usable, copy & paste resource for this application that will work on its own. For best results, be sure to edit placeholder data in the request with your desired values, such as \<role>.


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

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

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

folder_id = f"folder_{token_hex(8)}"
user_id = f"user_{token_hex(8)}"

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

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

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

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

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

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 adding audit logging. Read more about the capabilities on our AuthZ Overview page.

Next steps​

  • Check out our Admin Guide if you have a specific 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