Check Access Control

In Permify, you can perform two different types access checks,

resource based authorization checks, structured in the following form: Can user U perform action Y in resource Z ?
subject based authorization checks, structured in the following form: Which resources can user U edit ?

In this section we’ll look at the resource based check request of Permify. You can find subject based access checks in Entity (Data) Filtering section.

Content

Example Check Requests
- Resource Based Access Check (Relationships)
- Attribute Based Access Check With Context Data
How Access Decisions Evaluated?
Latency & Performance
Parameters & Properties

Example Check requests

Resource Based Check (Relationships)

POST /v1/tenants/{tenant_id}/permissions/check

Go
Node
Python
cURL

cr, err: = client.Permission.Check(context.Background(), &v1.PermissionCheckRequest {
    TenantId: "t1",
    Metadata: &v1.PermissionCheckRequestMetadata {
        SnapToken: "",
        SchemaVersion: "",
        Depth: 20,
    },
    Entity: &v1.Entity {
        Type: "repository",
        Id: "1",
    },
    Permission: "edit",
    Subject: &v1.Subject {
        Type: "user",
        Id: "1",
    },

    if (cr.can === PermissionCheckResponse_Result.RESULT_ALLOWED) {
        // RESULT_ALLOWED
    } else {
        // RESULT_DENIED
    }
})

client.permission.check({
    tenantId: "t1", 
    metadata: {
        snapToken: "",
        schemaVersion: "",
        depth: 20
    },
    entity: {
        type: "repository",
        id: "1"
    },
    permission: "edit",
    subject: {
        type: "user",
        id: "1"
    }
}).then((response) => {
    if (response.can === PermissionCheckResponse_Result.RESULT_ALLOWED) {
        console.log("RESULT_ALLOWED")
    } else {
        console.log("RESULT_DENIED")
    }
})

with permify.ApiClient(configuration) as api_client:
    api_instance = permify.PermissionApi(api_client)
    tenant_id = 't1' 

    body = PermissionsCheckRequest(
        tenant_id=tenant_id,
        metadata={
            "snapToken": "",
            "schemaVersion": "",
            "depth": 20
        },
        entity={
            "type": "repository",
            "id": "1"
        },
        permission="edit",
        subject={
            "type": "user",
            "id": "1"
        }
    )

    try:
        api_response = api_instance.permissions_check(tenant_id, body)
        if api_response.can == PermissionCheckResponse.Result.RESULT_ALLOWED:
            print("RESULT_ALLOWED")
        else:
            print("RESULT_DENIED")
    except ApiException as e:
        print(f"Exception permissions_check: {e}")

curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/permissions/check' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metadata":{
    "snap_token": "",
    "schema_version": "",
    "depth": 20
  },
  "entity": {
    "type": "repository",
    "id": "1"
  },
  "permission": "edit",
  "subject": {
    "type": "user",
    "id": "1",
    "relation": ""
  },
}'

Attribute Based (ABAC) Check With Context Data

client.permission.check({
    tenantId: "t1",
    metadata: {
        snapToken: "",
        schemaVersion: "",
        depth: 20,
    },
    entity: {
        type: "organization",
        id: "1",
    },
    permission: "hr_manager",
    subject: {
        type: "user",
        id: "1",
    },
    context: {
        data: {
            ip_address: "192.158.1.38",
        },
    },
}).then((response) => {
    if (response.can === PermissionCheckResponse_Result.RESULT_ALLOWED) {
        console.log("RESULT_ALLOWED");
    } else {
        console.log("RESULT_DENIED");
    }
});

How Access Decisions Evaluated?

Access decisions are evaluated by stored relational tuples and your authorization model, Permify Schema. In high level, access of an subject related with the relationships or attributes created between the subject and the resource. You can define this data in Permify Schema then create and store them as relational tuples and attributes, which is basically forms your authorization data. Permify Engine to compute access decision in 2 steps,

Looking up authorization model for finding the given action’s ( edit, push, delete etc.) relations.
Walk over a graph of each relation to find whether given subject ( user or user set ) is related with the action.

Let’s turn back to above authorization question ( “Can the user 3 edit document 12 ?” ) to better understand how decision evaluation works. When Permify Engine receives this question it directly looks up to authorization model to find document ‍edit action. Let’s say we have a model as follows

entity user {}
        
entity organization {

    // organizational roles
    relation admin @user
    relation member @user
}

entity document {

    // represents documents parent organization
    relation parent @organization
    
    // represents owner of this document
    relation owner  @user
    
    // permissions
    action edit   = parent.admin or owner
    action delete = owner
} 

Which has a directed graph as follows: relational-tuples

As we can see above: only users with an admin role in an organization, which document:12 belongs, and owners of the document:12 can edit. Permify runs two concurrent queries for parent.admin and owner: Q1: Get the owners of the document:12. Q2: Get admins of the organization where document:12 belongs to. Since edit action consist or between owner and parent.admin, if Permify Engine found user:3 in results of one of these queries then it terminates the other ongoing queries and returns authorized true to the client. Rather than or, if we had an and relation then Permify Engine waits the results of these queries to returning a decision.

Latency & Performance

With the right architecture we expect 7-12 ms latency. Depending on your load, cache usage and architecture you can get up to 30ms. Permify implements several cache mechanisms in order to achieve low latency in scaled distributed systems. See more on the section Cache Mechanisims

Parameters & Properties

Path Parameters

tenant_id

string

required

Identifier of the tenant, if you are not using multi-tenancy (have only one tenant) use pre-inserted tenant t1 for this field. Required, and must match the pattern \“[a-zA-Z0-9-,]+\“, max 64 bytes.

Body

application/json

PermissionCheckRequest is the request message for the Check method in the Permission service.

metadata

object

PermissionCheckRequestMetadata metadata for the PermissionCheckRequest.

Show child attributes

entity

object

Entity represents an entity with a type and an identifier.

Show child attributes

permission

string

The action the user wants to perform on the resource

subject

object

Subject represents an entity subject with a type, an identifier, and a relation.

Show child attributes

context

object

Context encapsulates the information related to a single operation, including the tuples involved and the associated attributes.

Show child attributes

arguments

object[]

Additional arguments associated with this request.

Show child attributes

Response

A successful response.

PermissionCheckResponse is the response message for the Check method in the Permission service.

can

enum<string>

default:CHECK_RESULT_UNSPECIFIED

Enumerates results of a check operation.

CHECK_RESULT_UNSPECIFIED: Not specified check result. This is the default value.
CHECK_RESULT_ALLOWED: Represents a successful check (the check allowed the operation).
CHECK_RESULT_DENIED: Represents a failed check (the check denied the operation).

Available options:

CHECK_RESULT_UNSPECIFIED,

CHECK_RESULT_ALLOWED,

CHECK_RESULT_DENIED

metadata

object

PermissionCheckResponseMetadata metadata for the PermissionCheckResponse.

Show child attributes

API Documentation

Schema Service

Data Service

Permission Service

Tenancy Service

Bundle Service

Watch Service

Content

Example Check requests

Resource Based Check (Relationships)

Attribute Based (ABAC) Check With Context Data

How Access Decisions Evaluated?

Latency & Performance

Parameters & Properties

Path Parameters

Body

Response

API Documentation

Schema Service

Data Service

Permission Service

Tenancy Service

Bundle Service

Watch Service

​Content

​Example Check requests

​Resource Based Check (Relationships)

​Attribute Based (ABAC) Check With Context Data

​How Access Decisions Evaluated?

​Latency & Performance

​Parameters & Properties

Path Parameters

Body

Response

Content

Example Check requests

Resource Based Check (Relationships)

Attribute Based (ABAC) Check With Context Data

How Access Decisions Evaluated?

Latency & Performance

Parameters & Properties