diff --git a/authorization_services/topics.adoc b/authorization_services/topics.adoc index ec0e7c8f4c..770831d457 100644 --- a/authorization_services/topics.adoc +++ b/authorization_services/topics.adoc @@ -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] diff --git a/authorization_services/topics/service-authorization-discovery-document.adoc b/authorization_services/topics/service-authorization-discovery-document.adoc index f7abaf83b1..b276ba788c 100644 --- a/authorization_services/topics/service-authorization-discovery-document.adoc +++ b/authorization_services/topics/service-authorization-discovery-document.adoc @@ -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" } ``` diff --git a/authorization_services/topics/service-protection-policy-api.adoc b/authorization_services/topics/service-protection-policy-api.adoc new file mode 100644 index 0000000000..0743a3a661 --- /dev/null +++ b/authorization_services/topics/service-protection-policy-api.adoc @@ -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. diff --git a/authorization_services/topics/service-protection-protection-api.adoc b/authorization_services/topics/service-protection-protection-api.adoc index 652eae4bac..e135408789 100644 --- a/authorization_services/topics/service-protection-protection-api.adoc +++ b/authorization_services/topics/service-protection-protection-api.adoc @@ -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*.