libre.sh/keycloak-scim
2
0
Fork 0
Code Issues 14 Pull requests Releases Packages Activity Actions 6

[KEYCLOAK-7552] - Documentation for new Policy API

Browse source
This commit is contained in:
Pedro Igor 2018-06-12 14:23:53 -03:00
parent f326d7f6f2
commit 93a78acb35
4 changed files with 163 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
authorization_services/topics.adoc
View file

@ -90,9 +90,11 @@ include::topics/service-protection-protection-api.adoc[leveloffset=+2]
include::topics/service-protection-whatis-obtain-pat.adoc[leveloffset=+3]
include::topics/service-protection-resources-api-papi.adoc[leveloffset=+2]
include::topics/service-protection-resources-api-papi.adoc[leveloffset=+3]
include::topics/service-protection-permission-api-papi.adoc[leveloffset=+2]
include::topics/service-protection-permission-api-papi.adoc[leveloffset=+3]
include::topics/service-protection-policy-api.adoc[leveloffset=+3]
include::topics/service-rpt-overview.adoc[leveloffset=+2]

3
authorization_services/topics/service-authorization-discovery-document.adoc
View file

@ -25,7 +25,8 @@ As a result, you should get a response as follows:
"token_endpoint": "http://${host}:${post}/auth/realms/${realm}/protocol/openid-connect/token",
"token_introspection_endpoint": "http://${host}:${post}/auth/realms/${realm}/protocol/openid-connect/token/introspect",
"resource_registration_endpoint": "http://${host}:${post}/auth/realms/${realm}/authz/protection/resource_set",
"permission_endpoint": "http://${host}:${post}/auth/realms/${realm}/authz/protection/permission"
"permission_endpoint": "http://${host}:${post}/auth/realms/${realm}/authz/protection/permission",
"policy_endpoint": "http://${host}:${post}/auth/realms/${realm}/authz/protection/uma-policy"
}
```

151
authorization_services/topics/service-protection-policy-api.adoc Normal file
View file

@ -0,0 +1,151 @@
[[_service_authorization_uma_policy_api]]
= 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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
http://${host}:${post}/auth/realms/${realm}/authz/protection/uma-policy?scope=read
```
To query all permissions, send an HTTP GET request as follows:
```bash
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.

6
authorization_services/topics/service-protection-protection-api.adoc
View file

@ -12,5 +12,11 @@ With this endpoint, resource servers can manage their resources remotely and ena
In the UMA protocol, resource servers access this endpoint to create permission tickets. {project_name} also provides
endpoints to manage the state of permissions and query permissions.
* *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.
An important requirement for this API is that _only_ resource servers are allowed to access its endpoints using a special OAuth2 access token called a protection API token (PAT).
In UMA, a PAT is a token with the scope *uma_protection*.