Overview

To ensure a resource’s security, integrity, and performance, as well as prevent its data from unauthorized use, you can consider limiting access to resources your Cloudentity client application deals with. In Cloudentity, it can be done by configuring a permission system. This is a tenant-wide configuration—once set, it covers all applications and workspaces within a tenant, so there’s no need to create an individual permission system for every workspace.

However, your tenant isn’t limited by a single permission system. You can create as many permission systems, as you need: for example, per an identity pool or application-dedicated and enable individual policies for each one.

Cloudentity’s Permission Systems facilitate permission checking and handling access to resources using the Google Zanzibar-inspired database with fine-grained permissions.

For a permission system to run, you must set up a schema—the outline of how the access is to be granted. The schema connects objects: a resource—the target to be accessed, and a subject—what or who will access the resource. In the example below, the schema defines the application’s permissions toward the email address.

In a Nutshell

Let’s say a permission system schema holds the following:

• Email address as resource

• Reader as relation

• Read as permission

• Application as subject

The schema delineates the access to the resource and the level of this access. The resource-subject connection is determined by relations, which are characterized by permissions. In our example, we see that the application is the reader for the email address, and the reader has the read permission.

With a schema like this, you don’t have to look for attributes assigned to the subject. Instead, you make an exact check: whether the application can read the email address.

Then, the permission system looks for the path email address > read > reader > application. If this path exists, the application can read the email address, and you get true in the response. Otherwise, the response is false.

This option is available with the feature flag. Contact the Cloudentity Sales team to request it.

Create a Permission System

1. Select Permission Systems on the left navigation panel.

   Click the Settings button and select Permission Systems in the drop-down, if you’re within a workspace.

2. Click + CREATE SYSTEM in the Permission Systems section.

3. Set the permission system name, description, and prefix . Click Create.

   Prefix

   By default, the prefix combines your tenant name and the name of your permission system. You can modify the prefix at the permission system creation step. Once the permission system is all set, use the prefix value exactly as you see it under the Configuration tab.

4. Click your newly created permission system tile. Proceed with the steps specified under the Quickstart tab.

Create a Token

1. Go to the Tokens tab. Click + ADD TOKEN.

2. Set the token name and description. Click Create.

   Save Your Token API Key

   The API key value is displayed only once, at the token creation step.

   An API key is automatically generated for your new token. The API key is required for further work with your permission system. Copy the API key. Make sure it’s stored securely.

   At any time, you can generate a new token along with the matching API key. Any subsequent token usage requires switching the zed context. Read Further Steps for details.

Apply a Schema

1. Copy the schema value.

2. Go to the Schema tab. Paste the schema copied to the code block. Save your changes.

The template given below illustrates a basic schema to be created from scratch. It includes a subject type = user, a resource type = post, the relations, and permissions. Based on the schema, you’ll add and handle actual subjects and resources to the permission system data table.

You can modify the schema according to your requirements, replacing the $-variables with the actual values.

Use the schema language reference for advanced guidance.

Schema Template

definition $PREFIX/user {}

definition $PREFIX/post {
   relation reader: $PREFIX/user
   relation writer: $PREFIX/user

   permission read = reader + writer
   permission write = writer
}

Store Relationships

Now you can record the actual values to your permission system data table.

Call the endpoint provided in the Store relationships block. Cloudentity generates the request_url value for your tenant with the $PERMISSION_SYSTEM_ID retrieved.

The resource and subject IDs are your target resources (for example, post, organization, or whatever else) and actual users or applications to whom you grant permissions.

The WriteRelationsResponse response includes the revision value. Save this value for the Check Permissions step and for further operations with your permission system.

Store Relationships CURL Template

curl -X POST "https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/api/permissions/$TENANT_ID/system/systems/$PERMISSION_SYSTEM_ID/relationships" \
-H "X-Api-Key: $API_KEY" \
-d '{ "updates": [{
"operation": "upsert",
"relation": "writer",
"resource_id": "$RESOURCE_ID",
"resource_type": "$PREFIX/post",
"subject_id": "$SUBJECT_ID",
"subject_type": "$PREFIX/user"
}] }'

Check Permissions

Once the schema is applied and relationships stored, you can check permissions. For this, make a test call with the cURL provided in the Check permissions Quickstart block.

Or use the template below, replacing the $-variables with your custom values, if any, and calling your response_url.

Check Permissions CURL Template

curl -X POST "https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/api/permissions/$TENANT_ID/system/systems/$PERMISSION_SYSTEM_ID/check" \
   -H "X-Api-Key: $API_KEY" \
   -d '{
       "revision": "$REVISION_VALUE",
       "permission": "read",
       "resource_id": "$RESOURCE_ID",
       "resource_type": "$PREFIX/post",
       "subject_id": "$SUBJECT_ID",
       "subject_type": "$PREFIX/user"
   }'

Variable Reference

CLICK TO UNFOLD

• $API_KEY: The API key generated for the token you’ve created at the first step. Store it for any further calls.

• $PREFIX: Your permission system prefix set at the permission system creation step. It correlates the schema objects with the permission system.

• $PERMISSION_SYSTEM_ID: Your permission system identifier. You can find it in the response URL parameter generated for your permission system within the Quickstart blocks or in the address bar when you’re on the permission system page.

• $RESOURCE_ID: The resource identifier. It defines what is to be accessed by the subject.

• $SUBJECT_ID: The identifier of the subject. It defines who or what has permissions relating to the target resource.

• $REVISION_VALUE: The revision value you’ve obtained with the WriteRelationsResponse parameter upon the Store Relationships step.

Further Steps

Once your permission system is all set, it’s available for further management. With Cloudentity permission system APIs cover the full range of operations to handle permissions from creation through checks to removal, including:

• Lookup resources to get the list of resources that have any subject assigned.

• Lookup subjects to get the list of subjects with access to resources.

• Handle token, including its update when the existing token isn’t available.

You can also generate a new token with the matching API key under the Tokens tab in your permission system settings. To use the new token, switch zed context: run zed context set acp grpc.$REGION_ID.authz.cloudentity.io:443 $API_KEY.

Cloudentity Permission System uses SpiceDB as authorization data storage. SpiceDB SDK languages are also supported. When you’re employing SpiceDB SDK, use grpc.$REGION_ID.authz.cloudentity.io:443.

The Check it out blog post explains how permission systems work in detail.