Authorization #

By authorization, we mean asking if someone has permission to some resources.

We can check user's permission on multiple resources instead of one. The response will contain all resources that the user has permission to them.

In each request we need to send the user's resources and context parameters.

Context parameters are optional, actually we can use them in our policies to check a condition.

One of the context parameters is path. Some policies have tree field. For that policies, the request's path param must match with the tree field in the policy to apply them. Read more about it here.

Examples #

• To check if user with id abc has permission to project with id 4. It also includes the project's attributes (the resource attributes) as well.

curl --location --request POST 'localhost:4000/api/v1/gate/authorize' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "service_id":"{service_id}",
    "user_id":"abc",
    "permissions":[
        {
            "resource_attributes":[{"key":"owner_id","value":"61c9a2ffd45b6247b18b210f"}],
            "permission":"project:4",
            "scope":"write"
        }
    ]
}'

Parameters in the request:

• token: token should be a PAT if you are calling from a service.
• service_id: Your service's id.
• user_id: ID of the user who you want to check their permission. we can set X-USER-TOKEN header which should contain user's token instead of user_id parameter.
• user_scopes: This example doesn't contain this param. It's the users scopes which you want to grant to the user in permission checks. values should be equal to client scopes which you have already defined them for your client.
• X-USER-TOKEN Header: This example doesn't contain X-USER-TOKEN header, but when you provide it, you don't need to provide user_id and user_scopes fields.
  It should be token of the user who you want to authorize.
• permissions: array of permissions that you want to check.
  • resource_attributes: attributes for resource that you want to check the permission for them. Policies sometimes set some conditions based on resources attributes, we use attributes that you send in policy evaluations. Read more about it here
  • permission: The resource that you want to get permission for it. its format is as follows: service_type:service_id
  • scope: scope of the resource that you want to access.

The response will be as follows:

{
  "code": "shield.gate.success_evaluation",
  "data": {
    "permissions": []
  }
}

It means the user doesn't have permission to the project with ID 4.

The response could be like this we well:

{
  "code": "shield.gate.success_evaluation",
  "data": {
    "permissions": [
      "project:4"
    ]
  }
}

Which means user has permission to the project with id 4.

• To check if user with id abc has permission to proposal with id 2, including the tree path too:

curl --location --request POST 'localhost:4000/api/v1/gate/authorize' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "service_id":"{service_id}",
    "user_id":"abc",
    "context_params":[{
        "key":"path",
        "value":"dc=abc.com,state=fars,city=fasa"
    }],
    "permissions":[
        {
            "permission":"proposal:2",
            "scope":"write"
        }
    ]
}'

In the following request, we are sending path too. we create the path by the resource's attrs. we know that resource (in this case a proposal with id 2), is in fasa, so we set the state value to fasa in the path. In the policy we have a tree which its state value is {user.state}, so when we set the state on the path, the policy will check if user's state is equal to the resource's state, so applies the policy decision.

• The following request checks if user with id abc has permission to a resource of type product (without id). Use this type of requests to check if someone can create a new instance of a resource or to query all resources of that type in DB.

curl --location --request POST 'localhost:4000/api/v1/gate/authorize' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "service_id":"{service_id}",
    "user_id":"abc",
    "permissions":[
        {
            "permission":"product",
            "scope":"write"
        }
    ]
}'

• The following request checks if user with id abc can view all products.

curl --location --request POST 'localhost:4000/api/v1/gate/authorize' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "service_id":"{service_id}",
    "user_id":"abc",
    "permissions":[
        {
            "permission":"product",
            "scope":"read"
        }
    ]
}'

Next steps #

• Take a look at the authorization API