Permalink
Fetching contributors…
Cannot retrieve contributors at this time
152 lines (121 sloc) 4.76 KB

Managing Resource Permissions using the Policy API

{project_name} leverages the UMA Protection API to allow resource servers to manage permissions for their users. In addition to the Resource and Permission APIs, {project_name} provides a Policy API from where permissions can be set to resources by resource servers on behalf of their users.

The Policy API is available at:

http://${host}:${port}/auth/realms/${realm_name}/authz/protection/uma-policy/{resource_id}

This API is protected by a bearer token that must represent a consent granted by the user to the resource server to manage permissions on his behalf. The bearer token can be a regular access token obtained from the token endpoint using:

  • Resource Owner Password Credentials Grant Type

  • Token Exchange, in order to exchange an access token granted to some client (public client) for a token where audience is the resource server

Associating a Permission with a Resource

To associate a permission with a specific resource you must send a HTTP POST request as follows:

curl -X POST \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{resource_id} \
  -H 'Authorization: Bearer '$access_token \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"name": "Any people manager",
	"description": "Allow access to any people manager",
	"scopes": ["read"],
	"roles": ["people-manager"]
}'

In the example above we are creating and associating a new permission to a resource represented by resource_id where any user with a role people-manager should be granted with the read scope.

You can also create policies using other access control mechanisms, such as using groups:

curl -X POST \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{resource_id} \
  -H 'Authorization: Bearer '$access_token \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"name": "Any people manager",
	"description": "Allow access to any people manager",
	"scopes": ["read"],
	"groups": ["/Managers/People Managers"]
}'

Or a specific client:

curl -X POST \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{resource_id} \
  -H 'Authorization: Bearer '$access_token \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"name": "Any people manager",
	"description": "Allow access to any people manager",
	"scopes": ["read"],
	"clients": ["my-client"]
}'

Or even using a custom policy using JavaScript:

curl -X POST \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{resource_id} \
  -H 'Authorization: Bearer '$access_token \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"name": "Any people manager",
	"description": "Allow access to any people manager",
	"scopes": ["read"],
	"condition": "if (isPeopleManager()) {$evaluation.grant()}"
}'

It is also possible to set any combination of these access control mechanisms.

To update an existing permission, send an HTTP PUT request as follows:

curl -X PUT \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{permission_id} \
  -H 'Authorization: Bearer '$access_token \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "21eb3fed-02d7-4b5a-9102-29f3f09b6de2",
    "name": "Any people manager",
    "description": "Allow access to any people manager",
    "type": "uma",
    "scopes": [
        "album:view"
    ],
    "logic": "POSITIVE",
    "decisionStrategy": "UNANIMOUS",
    "owner": "7e22131a-aa57-4f5f-b1db-6e82babcd322",
    "roles": [
        "user"
    ]
}'

Removing a Permission

To remove a permission associated with a resource, send an HTTP DELETE request as follows:

curl -X DELETE \
  http://localhost:8180/auth/realms/photoz/authz/protection/uma-policy/{permission_id} \
  -H 'Authorization: Bearer '$access_token

Querying Permission

To query the permissions associated with a resource, send an HTTP GET request as follows:

http://${host}:${post}/auth/realms/${realm}/authz/protection/uma-policy?resource={resource_id}

To query the permissions given its name, send an HTTP GET request as follows:

http://${host}:${post}/auth/realms/${realm}/authz/protection/uma-policy?name=Any people manager

To query the permissions associated with a specific scope, send an HTTP GET request as follows:

http://${host}:${post}/auth/realms/${realm}/authz/protection/uma-policy?scope=read

To query all permissions, send an HTTP GET request as follows:

http://${host}:${post}/auth/realms/${realm}/authz/protection/uma-policy

When querying the server for permissions use parameters first and max results to limit the result.