tr33/Readme.md Secret

## Readme.md

      
    Raw
  

              Readme.md
            
          
    A simple API interface for Authorization Request & Response


## pdp-api-check.md

      
    Raw
  

              pdp-api-check.md
            
          
    Request: Check permissions

Check if a subject has a certain permission on a resource.
HTTP request

Authorization evaluation is requested by issuing a POST request with the policies input data.
A bearer token is required for authentication.
POST /v1/data/rebac/check
Authorization: Bearer token
Request body

Authorization request data is issued as JSON structure:
{
      "input": {
        "resourceType": "node",
        "resourceId": "test",
        "permission": "can_read",
        "subjectType": "user",
        "subjectId": "test"
      }
}

data parameters description


resourceType: the type of the resource object
resourceId: the resource objects identifier
permission: the requested permission to check
subjectType: the subjects type
subjectId: the subjects identifier

Optional data parameters

The following parameters are optional:

zookie: A token respresenting a Point-in-Time: the PDP/ReBAC will ensure that the request is evaluated with data newer than the presented zookie. If no zookie is given, the PDP will always evaluate on the latest data (and not use any caches).

Response

If successful, the PDP returns a 200 OK response code and an evaluation result document in the response body.
An successfull response always contains the following elements:

status: indicates whether the request was processed without errors and contains a valid authorization decision, OR if there were any errors. Possible values:

"success": authorization request successfully evaluated, no errors.
"error": Some errors occured during the evaluation or the input parameters were faulty. In this case, an element "error" is included.


allow: <true/false> gives the PDPs policy decision. true indicates "permission granted", false indicates "permission denied".

Additional elements:

policy: contains the conditions under which the decision depicted in the "allow" is valid.
zookie: a zookie which can be used for following requests to enable caching.
error: (only if status: error) containing error details.

Example

Request

Here is an example of the request.
POST /v1/data/rebac/check
Authorization: Bearer token

{
      "input": {
        "resourceType": "node",
        "resourceId": "test",
        "permission": "can_read",
        "subjectType": "user",
        "subjectId": "test"
      }
}


Example with a zookie in the request:
POST /v1/data/rebac/check
Authorization: Bearer token

{
      "input": {
        "resourceType": "node",
        "resourceId": "test",
        "permission": "can_read",
        "subjectType": "user",
        "subjectId": "test",
        "zookie": "GgkKBzkxNy45MTc="
      }
}

Response

Here is an example of the response:
HTTP/1.1 200 OK
Content-type: application/json

{
  "result": {
    "allow": true,
    "policy": {
      "permission": "can_read",
      "resourceId": "test",
      "resourceType": "node",
      "subjectId": "test",
      "subjectType": "user"
    },
    "status": "success",
    "zookie": "GgkKBzkyMC45MjA="
  }
}
Response (with errors)

Here is an example of a response with errors:
HTTP/1.1 200 OK
Content-type: application/json

{
  "result": {
    "error": "object definition `non_existing_type` not found",
    "status": "error"
  }
}

  
## pdp-api-delete-rebac.md

      
    Raw
  

              pdp-api-delete-rebac.md
            
          
    ReBAC: delete relationship

Delete a relationship between a resource and a subject or all subjects of a type.
The policy allows mass operations, depending on the given request parameters.
Note:
The request is idempotent, which means that repeated update-requests don't issue an error if the relationship already exists.
HTTP request

A bearer token is required for authentication.
POST /v1/data/rebac/delete
Authorization: Bearer token
Request body

The requested relationships to delete are issued as JSON structure.
Example request:
{  
      "input": {
        "resourceType": "node",
        "resourceId": "test-node",
        "relation": "owner",
        "subjectType": "user",
        "subjectId": "test-user"
        }
}

data parameters description


resourceType (required): the type of the resource object to delete
relation (required): the relationship to delete

optional parameters


resourceId (optional): the resource objects identifier
subjectType (optional, required when 'subjectId' given): the subjects type
subjectId (optional): the subjects identifier

Depending on the parameters provided, the following delete operations are possible:

resourceType + resourceId + relation + subjectType + subjectId => delete the relationship between one resource and one subject
resourceType + resourceId + relation + subjectType => delete all relationships 'relation' of a single resource to all subjects of a given subjectType
resourceType + resourceId + relation => delete all relationships 'relation' of a single resource
resourceType + relation  => delete all relationships 'relation' of all resources

Response

If successful, the PDP returns a 200 OK response code and an result document in the response body.
An successfull response always contains the following elements:


status: indicates whether the request was processed without errors , OR if there were any errors. Possible values:

"success": relationships successfully deleted, no errors.
"error": Errors occured during the processing. In this case, an element "error" is included.


zookie: a zookie which represents the point-in-time the operation was successful. The zookie can be used in following requests to utilize Zanzibar caching (and avoid the new-enemy-problem).


Additional elements:

error: (only if status: error) containing error details.

Example

Request

Here is an example of the request to delete the relationship node:test-node#owner@user:test-user
POST /v1/data/rebac/delete
Authorization: Bearer token

{  
      "input": {
        "resourceType": "node",
        "resourceId": "test-node",
        "relation": "owner",
        "subjectType": "user",
        "subjectId": "test-user"
        }
}


Another example to delete **all 'owner' relationships** of ```node:node-test``` to **all users**:

{  
      "input": {
        "resourceType": "node",
        "resourceId": "test-node",
        "relation": "owner",
        "subjectType": "user",
        "subjectId": "test-user"
        }
}


Response

Here is an example of the response:
HTTP/1.1 200 OK
Content-type: application/json

{
  "result": {
    "status": "success",
    "zookie": "GgkKBzkyMy45MjM="
  }
}
Response (with errors)

Here is an example of a response with errors:
HTTP/1.1 200 OK
Content-type: application/json

{
  "result": {
    "error": "invalid DeleteRelationshipsRequest.RelationshipFilter: value is required",
    "status": "error"
  }
}

  
## pdp-api-lookup-resources.md

      
    Raw
  

              pdp-api-lookup-resources.md
            
          
    Rebac: lookup resources

Perform a lookup of all resources of a particular kind on which the subject has the specified permission or the relation in which the subject exists.
HTTP request

Authorization evaluation is requested by issuing a POST request with the policies input data.
A bearer token is required for authentication.
POST /v1/data/rebac/resources
Authorization: Bearer token
Request body

Resource-lookup request data is issued as JSON structure:
{  
      "input": {
        "resourceType": "node",
        "permission": "can_read",
        "subjectType": "user",
        "subjectId": "user-test",
        }
}

data parameters description


resourceType: the type of the resource object
permission: the requested permission to check
subjectType: the subjects type
subjectId: the subjects identifier

Optional data parameters

The following parameters are optional:

zookie: A token respresenting a Point-in-Time: the PDP/ReBAC will ensure that the request is evaluated with data newer than the presented zookie. If no zookie is given, the PDP will always evaluate on the latest data (and not use any caches).

Response

If successful, the PDP returns a 200 OK response code and an evaluation result document in the response body.
An successfull response always contains the following elements:

status: indicates whether the request was processed without errors and contains a valid authorization decision, OR if there were any errors. Possible values:

"success": authorization request successfully evaluated, no errors.
"error": Some errors occured during the evaluation or the input parameters were faulty. In this case, an element "error" is included.


allow: <true/false> gives the PDPs policy decision. true indicates "permission granted", false indicates "permission denied".

Additional elements:

policy: contains the conditions under which the decision depicted in the "allow" is valid.
zookie: a zookie which can be used for following requests to enable zanzibar caching.
error: (only if status: error) containing error details.

The policy element contains the following attributes:

subjectType: the subjects type
subjectId: the subjects Id
permission: the permission or relation
resourceType: the resource type
resourceIds: a LIST of resource Ids
metadata: a structure containing metadata about the policy response

resourceCount: number of elements in resourceIds


Example

Request

Here is an example of the request.
POST /v1/data/rebac/resources
Authorization: Bearer token

{
      "input": {
        "resourceType": "node",
        "permission": "can_read",
        "subjectType": "user",
        "subjectId": "test-user"
      }
}


Example with a zookie in the request:
POST /v1/data/rebac/resources
Authorization: Bearer token

{
      "input": {
        "resourceType": "node",
        "permission": "can_read",
        "subjectType": "user",
        "subjectId": "test-user",
        "zookie": "GgkKBzkxNy45MTc="
      }
}

Response

Here is an example of the response:
HTTP/1.1 200 OK
Content-type: application/json

{
  "result": {
    "allow": true,
    "policy": {
      "subjectId": "test",
      "subjectType": "user"
      "permission": "can_read",
      "resourceType": "node",
      "resourceIds": [
        "test"
      ],
      "metadata": {
        "resourceCount": 1
      },
    },
    "status": "success",
    "zookie": "GgkKBzkyMC45MjA="
  }
}
Response (with errors)

Here is an example of a response with errors:
HTTP/1.1 200 OK
Content-type: application/json

{
  "result": {
    "error": "malformed request input, parameters missing",
    "status": "error"
  }
}

  
## pdp-api-lookup-subjects.md

      
    Raw
  

              pdp-api-lookup-subjects.md
            
          
    Zanzibar: lookup subjects

Perform a lookup of all subjects of a particular kind which have permissions/a relation to a certain resource.
This is the reverse operation of 'lookup resources'.
Lookup subjects can be used in form of a question like "which subjects of type 'user' have 'can_read' permission on object 'node:my_node'?"
HTTP request

Authorization evaluation is requested by issuing a POST request with the policies input data.
A bearer token is required for authentication.
POST /v1/data/rebac/subjects
Authorization: Bearer token
Request body

subject-lookup request data is issued as JSON structure:
{  
      "input": {
        "resourceType": "node",
        "resourceId": "test",
        "permission": "can_read",
        "subjectType": "user"
        }
}

data parameters description


resourceType: the type of the resource object
resourceId: the id of the resource object
permission: the requested permission or relation to lookup
subjectType: the subject type

Optional data parameters

The following parameters are optional:

zookie: A token respresenting a Point-in-Time: the PDP/Zanzibar will ensure that the request is evaluated with data newer than the presented zookie. If no zookie is given, the PDP will always evaluate on the latest data (and not use any caches).

Response

If successful, the PDP returns a 200 OK response code and an evaluation result document in the response body.
An successfull response always contains the following elements:

status: indicates whether the request was processed without errors and contains a valid authorization decision, OR if there were any errors. Possible values:

"success": authorization request successfully evaluated, no errors.
"error": Some errors occured during the evaluation or the input parameters were faulty. In this case, an element "error" is included.


allow: <true/false> gives the PDPs policy decision. true indicates "permission granted", false indicates "permission denied".

Additional elements:

policy: contains the conditions under which the decision depicted in the "allow" is valid.
zookie: a zookie which can be used for following requests to enable zanzibar caching.
error: (only if status: error) containing error details.

The policy element contains the following attributes:

resourceType: the resource type
resourceId: the subjects Id
permission: the permission or relation
subjectType: the subjects type
subjectIds: a LIST of subject ids
metadata: a structure containing metadata about the policy response

resourceCount: number of elements in subjectIds


Example

Request

Here is an example of the request.
POST /v1/data/rebac/subjects
Authorization: Bearer token

{
      "input": {
        "resourceType": "node",
        "resourceId": "test",
        "permission": "can_read",
        "subjectType": "user"
      }
}


Example with a zookie in the request, to make use of Zanzibar performance caches:
POST /v1/data/rebac/subjects
Authorization: Bearer token

{
      "input": {
        "resourceType": "node",
        "resourceId": "test",
        "permission": "can_read",
        "subjectType": "user",
        "zookie": "GgkKBzkxNy45MTc="
      }
}

Response

Here is an example of the response:
HTTP/1.1 200 OK
Content-type: application/json

{
  "result": {
    "allow": true,
    "policy": {
      "metadata": {
        "resourceCount": 3
      },
      "permission": "can_read",
      "resourceId": "test",
      "resourceType": "node",
      "subjectIds": [
        "sam",
        "system-admin",
        "system-viewer"
      ],
      "subjectType": "user"
    },
    "status": "success",
    "zookie": "GgYKBENLd0c="
  }
}
Response (with errors)

Here is an example of a response with errors:
HTTP/1.1 200 OK
Content-type: application/json

{
  "result": {
    "error": "malformed request input, parameters missing",
    "status": "error"
  }
}

  
## pdp-api-update-rebac.md

      
    Raw
  

              pdp-api-update-rebac.md
            
          
    ReBAC: Update relationship

Update one or more relationships between a resource and a subject, in the meaning of "Subject User-A has relationship owner of resource group-G".
Either update a single relationship, or multiple relationships in a transaction.
Note:
This request is idempotent, meaning that repeated update-requests don't issue an error if the relationship already exists.
HTTP request

A bearer token is required for authentication.
POST /v1/data/rebac/update
Authorization: Bearer token
Request body

The update/create request supports two modes:
* update a single relationship,or
* update list of new relationships
Mixing both modes is not allowed and results in an error.
Single relationship update

The new relationship data is created by providing the tupel data as a JSON structure:
{  
      "input": {
        "resourceType": "node",
        "resourceId": "test",
        "relation": "owner",
        "subjectType": "user",
        "subjectId": "test"
        }
}


multi-relationship update (transaction)

The new relationships are created by providing a list of relationships in the "updates" element of the input JSON structure:
{  
      "input": {
          "updates": [
            {"resourceType": "node",
             "resourceId": "node-1",
             "relation": "owner",
             "subjectType": "user",
             "subjectId": "test-1"},
            {"resourceType": "node-2",
             "resourceId": "test",
             "relation": "owner",
             "subjectType": "user",
             "subjectId": "test-2"},
          ]
}


The request is transactional, meaning either all elementy are successfully processed, or none.
data parameters description

single-mode


resourceType: the type of the resource object
resourceId: the resource objects identifier
relation: the relationship between subject an resource
subjectType: the subjects type
subjectId: the subjects identifier

multi-mode


updates: a list of one or more dictionary of the single-mode syntax

Optional data parameters

None.
Response

If successful, the PDP returns a 200 OK response code and an result document in the response body.
An successfull response always contains the following elements:


status: indicates whether the request was processed without errors , OR if there were any errors. Possible values:

"success": relationship successfully updated, no errors.
"error": Errors occured during the processing. In this case, an element "error" is included.


zookie: a zookie which represents the point-in-time the relationship was updated. The zookie can be used in following check-requests to safely utilize zanzibar caching (and avoid the new-enemy-problem).


Additional elements:

error: (only if status: error) containing error details.

Example

Request

Here is an example of the request (single-mode).
POST /v1/data/rebac/update
Authorization: Bearer token

{  
      "input": {
        "resourceType": "node",
        "resourceId": "test",
        "relation": "owner",
        "subjectType": "user",
        "subjectId": "test"
        }
}


Example with multi-mode:
POST /v1/data/rebac/update
Authorization: Bearer token

{  
      "input": {
          "updates": [
            {"resourceType": "node",
             "resourceId": "node-1",
             "relation": "owner",
             "subjectType": "user",
             "subjectId": "test-1"},
            {"resourceType": "node-2",
             "resourceId": "test",
             "relation": "owner",
             "subjectType": "user",
             "subjectId": "test-2"},
          ]
        }
}


Response

Here is an example of the response:
HTTP/1.1 200 OK
Content-type: application/json

{
  "result": {
    "status": "success",
    "zookie": "GgkKBzkyMy45MjM="
  }
}
Response (with errors)

Here is an example of a response with errors:
HTTP/1.1 200 OK
Content-type: application/json

{
  "result": {
    "error": "invalid WriteRelationshipsRequest.Updates[0]: embedded message failed validation | caused by: invalid RelationshipUpdate.Relationship: embedded message failed validation | caused by: invalid Relationship.Relation: value does not match regex pattern \"^[a-z][a-z0-9_]{1,62}[a-z0-9]$\"",
    "status": "error"
  }
}
No results found