libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

[KEYCLOAK-3546] - A lot of fixes and improvements to docs from srehorn.

Browse source
This commit is contained in:
Pedro Igor 2016-09-09 00:53:39 -03:00
parent 71dc41c73f
commit 6ec0ed632e
48 changed files with 375 additions and 367 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
topics/enforcer/authorization-context.adoc
View file

@ -1,20 +1,20 @@
== Obtaining the Authorization Context
When policy enforcement is enabled, the permissions obtained from the server are available through `org.keycloak.AuthorizationContext`.
This class provides a few methods from where you can obtain permissions and check whether a permission was granted for a particular resource or scope.
This class provides several methods from where you can use to obtain permissions and check whether a permission was granted for a particular resource or scope.
Obtaining the Authorization Context in a Servlet Container
```java
HttpServletRequest request = // obtain javax.servlet.http.HttpServletRequest
HttpServletRequest request = ... // obtain javax.servlet.http.HttpServletRequest
KeycloakSecurityContext keycloakSecurityContext = (KeycloakSecurityContext) request.getAttribute(KeycloakSecurityContext.class.getName());
AuthorizationContext authzContext = keycloakSecurityContext.getAuthorizationContext();
```
[NOTE]
Check the adapter configuration for more details about how you can obtain a `KeycloakSecurityContext`. The example above should be enough
to obtain it when running your application using any of the servlet containers supported by {{book.project.name}}.
to obtain the context when running an application using any of the servlet containers supported by {{book.project.name}}.
The authorization context may be very useful to give you even more control over the decisions taken and returned by the server. For instance, you can use it
The authorization context helps give you even more control over the decisions taken and returned by the server. For instance, you can use it
to build a dynamic menu where the items are hidden/shown depending on the permissions associated with a resource or scope.
```java
@ -34,7 +34,7 @@ if (authzContext.hasScopePermission("urn:project.com:project:create")) {
The `AuthorizationContext` represents one of the main capabilities of {{book.project.name}} {{book.project.module}}. From the examples above, you may notice that the protected resource is not
directly associated with the policies that govern them.
Let's take for example, a similar code using RBAC:
Consider some similar code using RBAC:
```java
if (User.hasRole('user')) {
@ -50,10 +50,9 @@ if (User.hasRole('project-manager')) {
}
```
Although they address the same requirements, they do it in different ways. While in RBAC roles implicitly define the resources they give access, when using {{book.project.name}} you may have
a much more clean and manageable code, where you code directly to your resources. No matter if you are using RBAC, ABAC, or any other BAC variant. Or you have the permission for a given resource or scope, or you don't.
Although both examples address the same requirements, they do it in different ways. In RBAC, roles only _implicitly_ define access for their resources. With {{book.project.name}} you gain the capability to create more manageable code that focuses directly on your resources whether you are using RBAC, ABAC, or any other BAC variant. Either you have the permission for a given resource or scope, or you don't.
Now, suppose our security requirements have changed and beside project managers, PMOs can also create new projects.
Now, suppose your security requirements have changed and beside project managers, PMOs can also create new projects.
When using {{book.project.name}} you don't even need to change your application code to address that new requirement. Given that your application is already based on the resource and scope identifier,
you just need to change the permissions or policies associated with a particular resource. In this case, we would change the permissions and policies associated with the `Project Resource`.
Security requirements change, but with {{book.project.name}} you don't need to change your application code to address new requirements. Once your application is based on the resource and scope identifier,
you need only change the configuration of the permissions or policies associated with a particular resource in the authorization server. In this case, we would change the permissions and policies associated with the `Project Resource` and/or the scope `urn:project.com:project:create`.

51
topics/enforcer/js-adapter.adoc
View file

@ -1,7 +1,7 @@
== JavaScript Integration
The {{book.project.name}} Server comes with a Javascript library you can use to interact with a resource server protected by a policy enforcer. This library is based on the https://keycloak.gitbooks.io/securing-client-applications-guide/content/topics/oidc/javascript-adapter.html[Keycloak JavaScript Adapter], which means your client
should be using it to authenticate against a {{book.project.name}} Server.
The {{book.project.name}} Server comes with a JavaScript library you can use to interact with a resource server protected by a policy enforcer.
This library is based on the https://keycloak.gitbooks.io/securing-client-applications-guide/content/topics/oidc/javascript-adapter.html[Keycloak JavaScript Adapter], which can be integrated to allow your client to obtain permissions from a {{book.project.name}} Server.
You can obtain this library from a running {{book.project.name}} Server instance by including the following `script` tag in your web page:
@ -11,36 +11,39 @@ You can obtain this library from a running {{book.project.name}} Server instance
Once you do that, you can create a `KeycloakAuthorization` instance as follows:
```javascript
var keycloak = // obtain a Keycloak instance from keycloak.js library
var keycloak = ... // obtain a Keycloak instance from keycloak.js library
var authorization = new KeycloakAuthorization(keycloak);
```
The *keycloak-authz.js* library provides two main functionalities:
The *keycloak-authz.js* library provides two main features:
* Handle responses from a resource server protected by a link:overview.html[{{book.project.name}} Policy Enforcer] and obtain a RPT with the necessary permissions to gain access to
the protected resources on the resource server
* Handle responses from a resource server protected by a link:overview.html[{{book.project.name}} Policy Enforcer] and obtain a requesting party token (RPT) with the necessary permissions to gain access to
the protected resources on the resource server.
** In this case, the library can handle whatever authorization protocol the resource server is using: link:../service/authorization/authorization-api.html[UMA] or link:../service/entitlement/entitlement-api.html[Entitlements].
* Obtain permissions from a {{book.project.name}} Server using the link:../service/entitlement/entitlement-api.html[Entitlement API]
In both cases, the library allows you to easily interact with both resource server and {{book.project.name}} {{book.project.module}} in order to obtain tokens with the
necessary permissions that your client can use as bearer tokens to access the protected resources on a resource server.
In both cases, the library allows you to easily interact with both resource server and {{book.project.name}} {{book.project.module}} to obtain tokens with
permissions your client can use as bearer tokens to access the protected resources on a resource server.
=== Handling Authorization Responses from a Resource Server
If a resource server is protected by a policy enforcer, it will respond to client requests based on the permissions carried along with a link:keycloak-enforcement-bearer.html[bearer token].
Usually, when you try to access a resource server with a bearer token that is lacking permissions to access a protected resource, the resource server
Typically, when you try to access a resource server with a bearer token that is lacking permissions to access a protected resource, the resource server
will respond with a *401* status code and a `WWW-Authenticate` header.
The value of the `WWW-Authenticate` header depends on the authorization protocol in use by the resource server. Whatever protocol is in use, you can use a `KeycloakAuthorization` instance to
handle responses as follows:
```javascript
var wwwAuthenticateHeader = // extract WWW-Authenticate Header from the response in case of a 401 status code
var wwwAuthenticateHeader = ... // extract WWW-Authenticate Header from the response in case of a 401 status code
authorization.authorize(wwwAuthenticateHeader).then(function (rpt) {
// onGrant callback function. If authorization was successful you'll receive a RPT with the necessary permissions to access the resource server
// onGrant callback function.
// If authorization was successful you'll receive a RPT
// with the necessary permissions to access the resource server
}, function () {
// onDeny callback function. Called when the authorization request is denied by the server
// onDeny callback function.
// Called when the authorization request is denied by the server
}, function () {
// onError callback function. Called when the server responds unexpectedly
});
@ -48,32 +51,34 @@ authorization.authorize(wwwAuthenticateHeader).then(function (rpt) {
The `authorize` function is completely asynchronous and supports a few callback functions in order to receive notifications from the server:
* `onGrant`, is the first argument of the function. If authorization was successful and the server returned a RPT with the requested permissions, the callback will receive the RPT
* `onDeny`, is the second argument of the function. Only called if the server has denied the authorization request
* `onError`, is the third argument of the function. Only called if the server responds unexpectedly
* `onGrant` - the first argument of the function. If authorization was successful and the server returned an RPT with the requested permissions, the callback will receive the RPT
* `onDeny` - the second argument of the function. Only called if the server has denied the authorization request
* `onError` - the third argument of the function. Only called if the server responds unexpectedly
Most applications would use the `onGrant` callback to retry a request after a 401 response. Where subsequent requests should include the RPT as a bearer token.
Most applications should use the `onGrant` callback to retry a request after a 401 response. Subsequent requests should include the RPT as a bearer token for retries.
=== Obtaining Entitlements
The keycloak-authz.js provides a `entitlement` function that you can use to obtain a RPT from the server using the Entitlement API.
The keycloak-authz.js library provides an `entitlement` function that you can use to obtain an RPT from the server using the Entitlement API.
```json
authorization.entitlement('my-resource-server-id').then(function (rpt) {
// onGrant callback function. If authorization was successful you'll receive a RPT with the necessary permissions to access the resource server
// onGrant callback function.
// If authorization was successful you'll receive a RPT
// with the necessary permissions to access the resource server
});
```
When using the `entitlement` function, you just need to provide the _client_id_ of the resource server you want to access.
When using the `entitlement` function, you need to provide the _client_id_ of the resource server you want to access.
The `entitlement` function is completely asynchronous and supports a few callback functions in order to receive notifications from the server:
* `onGrant`, is the first argument of the function. If authorization was successful and the server returned a RPT with the requested permissions, the callback will receive the RPT
* `onDeny`, is the second argument of the function. Only called if the server has denied the authorization request
* `onError`, is the third argument of the function. Only called if the server responds unexpectedly
* `onGrant` - the first argument of the function. If authorization was successful and the server returned an RPT with the requested permissions, the callback will receive the RPT
* `onDeny` - the second argument of the function. Only called if the server has denied the authorization request
* `onError` - the third argument of the function. Only called if the server responds unexpectedly
=== Obtaining the RPT
If you have already obtained a RPT using any of the authorization functions provided by the library, you can always obtain the RPT as follows:
If you have already obtained a RPT using any of the authorization functions provided by the library, you can always obtain the RPT as follows from the authorization object (assuming that it has been initialized by one of the techniques shown earlier):
```javascript
var rpt = authorization.rpt;

4
topics/enforcer/keycloak-enforcement-bearer.adoc
View file

@ -11,7 +11,7 @@ Authorization: Bearer ${RPT}
...
```
Where you should have a *keycloak.json* file in your application similar to the following:
In this example, you would have a *keycloak.json* file in your application similar to the following:
.Example of WEB-INF/keycloak.json with the bearer-only configuration option
```json
@ -40,7 +40,7 @@ HTTP/1.1 401 Unauthorized
WWW-Authenticate: KC_ETT realm="photoz-restful-api",as_uri="http://localhost:8080/auth/realms/photoz/authz/entitlement"
```
Once the a client receives a response from the server, it should check the status code and `WWW-Authenticate` header in order to obtain
Once a client receives a response from the server, it should check the status code and `WWW-Authenticate` header in order to obtain
a RPT from a {{book.project.name}} Server.

23
topics/enforcer/keycloak-enforcement-filter.adoc
View file

@ -2,13 +2,12 @@
You can enforce authorization decisions to your applications if you are using {{book.project.name}} OIDC Adapters.
When you enable policy enforcement to your {{book.project.name}} application, the corresponding adapter is going to intercept
every single request to your application and enforce the authorization decisions obtained from the server.
When you enable policy enforcement to your {{book.project.name}} application, the corresponding adapter will intercept all requests to your application and enforce the authorization decisions obtained from the server.
Policy enforcement is strongly based on your application's paths and the link:../resource/overview.html[Resources] you created to a resource server using the {{book.project.name}} Administration Console. By default,
when you create a resource server, {{book.project.name}} creates a link:../resource-server/default-config.html[Default Configuration] to your resource server so you can enable policy enforcement very quickly.
Policy enforcement is strongly linked to your application's paths and the link:../resource/overview.html[Resources] you created for a resource server using the {{book.project.name}} Administration Console. By default,
when you create a resource server, {{book.project.name}} creates a link:../resource-server/default-config.html[Default Configuration] for your resource server so you can enable policy enforcement very quickly.
The default configuration allows access for every single resource in your application as long as the authenticated user belongs to the same realm as the resource server being protected.
The default configuration allows access for all resources in your application provided the authenticated user belongs to the same realm as the resource server being protected.
=== Policy Enforcement Configuration
@ -73,8 +72,8 @@ for all resources associated with the resource server being protected. In this c
+
** *user-managed-access*
+
Tells the adapter to use the UMA protocol. If set, the adapter will ask the server for permission tickets and return them to clients accordingly with UMA specification. If not set,
the adapter will just rely on the RPT sent to the server to actually enforce permissions.
Tells the adapter to use the UMA protocol. If set, the adapter will ask the server for permission tickets and return them to clients according to the UMA specification. If not set,
the adapter will just rely on the requesting party token (RPT) sent to the server to actually enforce permissions.
+
** *enforcement-mode*
+
@ -94,7 +93,7 @@ Completely disables the evaluation of policies and allow access to any resource.
+
** *on-deny-redirect-to*
+
Defines an URL to where a client request should be redirected to when an access denied message is obtained from the server. By default, the adapter responds with a 403 HTTP status code..
Defines a URL where a client request should be redirected when an "access denied" message is obtained from the server. By default, the adapter responds with a 403 HTTP status code.
+
** *paths*
+
@ -102,11 +101,11 @@ Specify the paths to protect.
+
*** *name*
+
The name of a resource in the server that must be associated with a given path. When used in conjunction with a *path*, the policy enforcer will ignore the resource's *URI* property and will use the path you provided instead.
The name of a resource in the server that is to be associated with a given path. When used in conjunction with a *path*, the policy enforcer will ignore the resource's *URI* property and will use the path you provided instead.
*** *path*
+
A URI relative to the application's context path. If this option is provided, the policy enforcer will query the server for a resource with a *URI* with the same value. This option is REQUIRED.
Right now, we support some very basic logic for path matching. Examples of valid paths are:
Right now, we support very basic logic for path matching. Examples of valid paths are:
+
**** Wildcards: `/*`
**** Suffix: `/*.html`
@ -115,7 +114,7 @@ Right now, we support some very basic logic for path matching. Examples of valid
**** Exact match: /resource
+
*** *methods*
The HTTP methods to protect and how they are associated with the scopes for a given resource in the server.
The HTTP methods (aka "verbs" e.g., GET, POST, PATCH) to protect and how they are associated with the scopes for a given resource in the server.
+
**** *method*
+
@ -124,4 +123,4 @@ The name of the HTTP method.
**** *scopes*
+
An array of strings with the scopes associated with the method. When you associate scopes with a specific method, the client trying to access a protected resource (or path) must provide
a RPT that grants permission to all scopes here specified. For instance, if you define a method _POST_ with a scope _create_, the RPT must contain a permission granting access to the _create_ scope when performing a POST to the path.
an RPT that grants permission to all scopes specified in the list. For instance, if you define a method _POST_ with a scope _create_, the RPT must contain a permission granting access to the _create_ scope when performing a POST to the path.

6
topics/enforcer/overview.adoc
View file

@ -1,7 +1,7 @@
== Policy Enforcers
PEP is a design pattern and as such you can implement it in different ways. {{book.project.name}} provides all the necessary means
to implement PEPs for different platforms, environments and using different programming languages. After all, {{book.project.name}} {{book.project.module}} is
fully RESTFUL-based, leveraging OAuth2 authorization capabilities to also support fine-grained authorization using a centralized authorization server.
Policy Enforcement Point (PEP) is a design pattern and as such you can implement it in different ways. {{book.project.name}} provides all the necessary means
to implement PEPs for different platforms, environments, and even different programming languages. {{book.project.name}} {{book.project.module}} presents a RESTful API,
and leverages OAuth2 authorization capabilities for fine-grained authorization using a centralized authorization server.
image:../../images/pep-pattern-diagram.png[alt="PEP Overview"]

6
topics/example/overview.adoc
View file

@ -15,7 +15,7 @@ cd ${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz
Or you can get them from https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz[GitHub].
For each example is provided a `README` file with instructions about how to build, deploy and test the example.
Each example has a `README` file with instructions about how to build, deploy, and test the example.
Here is a brief description of each of them:
@ -24,11 +24,11 @@ Here is a brief description of each of them:
|Name |Description
| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/servlet-authz[hello-world-authz-service]
| A single page application which is protected by a policy enforcer that decides whether an user can access that page or not based on the permissions obtained from a Keycloak Server.
| A single page application which is protected by a policy enforcer that decides whether a user can access that page or not based on the permissions obtained from a Keycloak Server.
| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/servlet-authz[photoz]
| A simple application based on HTML5+AngularJS+JAX-RS that demonstrates how to enable fine-grained permissions to RESTFul based services and HTML5 clients.
| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/servlet-authz[servlet-authz]
| A simple Servlet-based application that demonstrates how to enable fine-grained authorization to a JBoss Servlet Application.
| A simple Servlet-based application that demonstrates how to enable fine-grained authorization to a JBoss/Wildfly Servlet Application.
|===

12
topics/getting-started/hello-world/create-realm.adoc
View file

@ -7,23 +7,23 @@ The first step is to create a realm. The realm we are about to create is very si
* A single client application, which we're going to turn into a link:../../overview/terminology.html[Resource Server] and enable
the authorization services
Create a realm with a name *hello-world-authz*. Once created, you should be able to see a page like that.
Create a realm with a name *hello-world-authz*. Once created, you should see a page similar to the following:
.Realm hello-world-authz
image:../../../images/getting-started/hello-world/create-realm.png[alt="Realm hello-world-authz"]
After creating the realm, you should also create a single user. For that, click on the `Users` left menu item. This will bring you
to the user list page. On the right side of the empty user list, you should see an `Add User` button. Click that to start creating the new user.
Next, create a single user in your newly-created realm. Click on the `Users` left menu item. This will bring you
to the user list page. On the right side of the empty user list, you should see an `Add User` button. Click that to start creating the new user with the username of *alice*.
Fill in the fields as shown below and click `Save`.
.Add User
image:../../../images/getting-started/hello-world/create-user.png[alt="Add User"]
Let's set a password for the *alice* user. Click on the `Credentials` tab. This will bring you to the `Credentials` page.
Next, set a password for the *alice* user by clicking on the `Credentials` tab to display the `Credentials` page.
.Set User Password
image:../../../images/getting-started/hello-world/reset-user-pwd.png[alt="Set User Password"]
Fill in the `New Password` and `Password Confirmation` fields with a password and click on the `Temporary` switch to turn it `OFF`. For last,
click on the `Reset Password` button to reset the user's password.
Fill in the `New Password` and `Password Confirmation` fields with a password and click the `Temporary` switch to turn it `OFF`. Lastly,
click on the `Reset Password` button to set the user's password.

16
topics/getting-started/hello-world/create-resource-server.adoc
View file

@ -1,25 +1,25 @@
== Enabling Authorization Services
You can enable authorization services to any existing client application using the OpenID Connect Protocol. However, in this guide we are
going to create a new one from scratch.
You can enable authorization services in any existing client application configured to use the OpenID Connect Protocol. However, in this guide we are
going to create a new client from scratch.
Click on the `Clients` left menu item to start creating a new client application and fill in the fields as shown below:
.Create Client Application
image:../../../images/getting-started/hello-world/create-client.png[alt="Create Client Application"]
Click on the `Save` button to create the client. This should bring you the `Client Details` page.
Click on the `Save` button to create the client. This should display the `Client Details` page.
.Client Details
image:../../../images/getting-started/hello-world/enable-authz.png[alt="Client Details"]
In this page, click on the `Authorization Services Enabled` switch and turn it `ON`. After that click on the `Save` button.
When you do that, a new `Authorization` tab will show up. Click on this tab and you should see a page like that.
In this page, click the `Authorization Enabled` switch and turn it `ON`, then click the `Save` button.
After saving, a new `Authorization` tab will show up in the tab set for the client. Click on this tab and you should see a page similar to the following:
.Authorization Settings
image:../../../images/getting-started/hello-world/authz-settings.png[alt="Authorization Settings"]
When you enable authorization services to a client application, {{book.project.name}} defines some link:../../resource-server/default-config.html[Default Settings] to
your application.
When you enable authorization services for a client application, {{book.project.name}} automatically creates several link:../../resource-server/default-config.html[Default Settings] for
your client authorization configuration.
For more details about authorization configuration, please take a look at link:../../resource-server/enable-authorization.html[Enabling Authorization Services].
For more details about authorization configuration, please see link:../../resource-server/enable-authorization.html[Enabling Authorization Services].

38
topics/getting-started/hello-world/deploy.adoc
View file

@ -1,7 +1,6 @@
== Build, Deploy and Test
Now that the *hello-world-authz-service* is properly configured and authorization services are enabled, we can deploy it to
the server and see the results.
Now that the *hello-world-authz-service* resource server (client) is properly configured and authorization services are enabled, we can deploy it to the server and see the results.
=== Generating the Adapter Configuration
@ -11,7 +10,7 @@ click on the *hello-world-authz-service* client application. This will bring you
.Client Details
image:../../../images/getting-started/hello-world/enable-authz.png[alt="Client Details"]
Click on the `Installation Tab`. In this tab select `Keycloak OIDC JSON` as the format option. This will bring you the adapter config using a JSON format.
Click on the `Installation Tab`. From the `Format Option` dropdown, select `Keycloak OIDC JSON`. This will display the adapter configuration in JSON format. Copy the contents to the clipboard and create a file or use the `Download` button.
.Adapter Configuration
image:../../../images/getting-started/hello-world/adapter-config.png[alt="Adapter Configuration"]
@ -20,7 +19,7 @@ Now, go to the *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/hello-world-authz-ser
you just obtained from the {{book.project.name}} Administration Console.
By default, the policy enforcer responds with a `403` status code when the user lacks permissions to access protected resources on the resource server. However, you can also provide a
URL to where you want redirect your users to. For that, change the *keycloak.json* file you just updated and replace the `policy-enforcer` configuration with the following:
redirection URL for unauthorized users. To customize this, change the *keycloak.json* file you just updated and replace the `policy-enforcer` configuration with the following:
```json
"policy-enforcer": {
@ -28,11 +27,11 @@ URL to where you want redirect your users to. For that, change the *keycloak.jso
}
```
That last configuration tells the policy enforcer to redirect users to a `/hello-world-authz-service/error.jsp` page in case they dom't have the necessary permissions to access a protected resource.
That last configuration tells the policy enforcer to redirect users to a `/hello-world-authz-service/error.jsp` page if they don't have the necessary permissions to access a protected resource, rather than an unhelpful `403 Unauthrorized` message.
=== Build and Deploy the Application
For last, got to the *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/hello-world-authz-service/* and execute the following command:
Lastly, go to the *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/hello-world-authz-service/* and execute the following command:
```bash
mvn clean package wildfly:deploy
@ -47,37 +46,38 @@ The first page you should see is the {{book.project.name}} Login Page.
.Login Page
image:../../../images/getting-started/hello-world/login-page.png[alt="Login Page"]
Try to login as *alice*. After the authentication you should see a page as follows:
Try to login as *alice* using the password you set up for that user. After authenticating, you should see a page as follows:
.Hello World Authz Main Page
image:../../../images/getting-started/hello-world/main-page.png[alt="Hello World Authz Main Page"]
The link:../../resource-server/default-config.html[Default Settings] defined by {{book.project.name}} when you enable authorization services to a client application provides a simple
policy that only grants access to users belonging to the realm of the client.
The link:../../resource-server/default-config.html[Default Settings] defined by {{book.project.name}} when you enable authorization services for a client application provide a simple
policy that always grant access to the resources protected by this policy.
You can start playing around by changing the default permissions and policies and check how your application will behave. Or even create new policies using the different
You can start playing around by changing the default permissions and policies and check how your application will behave, or even create new policies using the different
link:../../policy/overview.html[Policy Types] provided by {{book.project.name}}.
There are a plenty of things you can do now to test this application. For instance, try to change the `Default Policy` as follows:
There are a plenty of things you can do now to test this application. For instance, you can change the default policy by clicking on the `Authorization` tab for the client, then `Policies` tab, then click on `Default Policy` in the list to allow you to change it as follows:
```js
// let's see what happens when we call $evaluation.deny()
$evaluation.grant();
// The default value is $evaluation.grant(),
// let's see what happens when we change it to $evaluation.deny()
$evaluation.deny();
```
Now, try to logout from the application and log in again. You should no longer be able to access the application.
Now, logout from the demo application and log in again. You should no longer be able to access the application.
image:../../../images/getting-started/hello-world/access-denied-page.png[alt="Access Denied Page"]
Let's fix that now, but instead of changing the `Default Policy` code we are just going to change the `Logic` to `Negative`. That should bring back access to the application
as we are just negating the result of that policy, which is by default denying all requests for access. Again, before testing this change, please logout and log in again.
Let's fix that now, but instead of changing the `Default Policy` code we are just going to change the `Logic` to `Negative` using the dropdown control below the policy code text area.
That should re-enable access to the application as we are just negating the result of that policy, which is by default denying all requests for access. Again, before testing this change, be sure to logout and log in again.
=== Next Steps
There are a lot of other things you can do from now on, such as:
* Create a scope, define a policy and permission for it and check on the application side if the user is allowed to perform some action (or anything else represented by the scope you created)
* Create different types of policies such as link:../../policy/role-policy.adoc[Role-Based], link:../../policy/user-policy.adoc[User-Based], link:../../policy/time-policy.adoc[Time-Based], link:../../policy/aggregated-policy.adoc[Aggregated Policies], link:../../policy/drools-policy.adoc[Drools-Based]. And associate these policies with the `Default Permission`
* Create a scope, define a policy and permission for it, and check on the application side if the user is allowed to perform some action (or anything else represented by the scope you created)
* Create different types of policies such as link:../../policy/role-policy.adoc[Role-Based], link:../../policy/user-policy.adoc[User-Based], link:../../policy/time-policy.adoc[Time-Based], link:../../policy/aggregated-policy.adoc[Aggregated Policies], link:../../policy/drools-policy.adoc[Drools-Based], and associate these policies with the `Default Permission`
* Apply multiple policies to the `Default Permission` and check behavior. For instance, try to mix multiple policies and change the `Decision Strategy` accordingly
* Checkout the link:../../enforcer/authorization-context.adoc[Obtaining the Authorization Context] topic for more details about how to check for permissions inside your application
* Check out the link:../../enforcer/authorization-context.adoc[Obtaining the Authorization Context] topic for more details about how to check for permissions inside your application

12
topics/getting-started/hello-world/overview.adoc
View file

@ -1,12 +1,12 @@
== Hello World
The purpose of this guide is to get you up and running as quickly as possible so that you can play with and test drive various authorization features provided by {{book.project.name}}.
It relies heavily on the default database and server configuration that come out of the box and does not get into any complex deployment options.
If you want a more in depth discussion of any features or configuration options, you should consult the various other sections in this documentation.
This quick tour relies heavily on the default out-of-the-box database and server configuration and does not cover complex deployment options.
For more in-depth discussion of any features or configuration options, consult the appropriate detail sections for those features and options in this documentation.
From this guide you'll understand some key concepts around {{book.project.name}} {{book.project.module}}:
* How to enable fine-grained authorization to a client application ?
* How to turn a client application into a resource server, whose resources are protected ?
* How to define permissions and authorization policies to govern access to the protected resources ?
* How to enable policy enforcement to your application ?
* Enabling fine-grained authorization to a client application
* Configuring a client application to be a resource server, with protected resources
* Defining permissions and authorization policies to govern access to protected resources
* Enabling policy enforcement in your applications

10
topics/getting-started/overview.adoc
View file

@ -4,17 +4,17 @@ All tutorials are based on the *{{book.project.name}} Demo Distribution*.
* *keycloak-demo-{{book.project.version}}.[zip|tar.gz]*
To unpack this file run the _unzip_ or _gunzip_ and _tar_ utilities. During this guide we'll reference the directory you have unpacked
To unpack this file run the _unzip_ or _gunzip_ and _tar_ utilities. During this guide we'll reference the directory where you have unpacked
the demo distribution as *${KEYCLOAK_DEMO_SERVER_DIR}*.
[NOTE]
This guide assumes that you are already familiar with {{book.project.name}} and that you are able to install and boot a {{book.project.name}} Server. For more information, please follow the intrusctions https://keycloak.gitbooks.io/getting-started-tutorials/content/[here].
This guide assumes that you are already familiar with {{book.project.name}} and that you are able to install and boot a {{book.project.name}} Server. For more information, please follow the instructions https://keycloak.gitbooks.io/getting-started-tutorials/content/[here].
Make sure you have a {{book.project.name}} instance up and running on http://localhost:8080/auth[http://localhost:8080/auth]. If everything is OK, you should be able to login to the
_Administration Console_ and get a page like that:
Make sure you have a {{book.project.name}} instance up and running, the default configuration is http://localhost:8080/auth[http://localhost:8080/auth]. If everything is OK, you should be able to login to the
_Administration Console_ and see a page similar to this:
.{{book.project.name}} Administration Console
image:../../images/getting-started/kc-start-page.png[alt="Keycloak Administration Console"]
All source code for the getting started tutorials can be obtained from the demo distributions. The authorization related examples
All source code for the getting started tutorials can be obtained from the demo distributions. The authorization-related examples
are located at *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz*.

4
topics/overview/architecture.adoc
View file

@ -2,11 +2,11 @@
image:../../images/authz-arch-overview.png[alt="Keycloak AuthZ Architecture Overview"]
From a design perspective, the {{book.project.module}} are based on a well defined set of authorization patterns providing a:
From a design perspective, the {{book.project.module}} are based on a well-defined set of authorization patterns providing these capabilities:
* **Policy Administration Point (PAP)**
+
Provides a set of UIs based on {{book.project.name}} Administration Console to manage resource servers, resources, scopes, permissions and policies.
Provides a set of UIs based on {{book.project.name}} Administration Console to manage resource servers, resources, scopes, permissions, and policies.
Part of this also accomplished remotely through the use of the link:../service/protection/protection-api.adoc[Protection API].
+

28
topics/overview/overview.adoc
View file

@ -1,6 +1,6 @@
== Overview
{{book.project.name}} supports fine-grained authorization policies with a mix and match of different access control
{{book.project.name}} supports fine-grained authorization policies and is able to mix and match different access control
mechanisms such as:
* **Attribute-based Access Control**
@ -12,28 +12,28 @@ mechanisms such as:
** Using JBoss Drools
* **Support for custom ACMs through a Policy Provider SPI**
Being based on a set of administrative UIs and a RESTful API, {{book.project.name}} provides the necessary means to create permissions
for your protected resources and scopes, associate these permissions with authorization policies and enforce authorization
decisions in your application and services.
{{book.project.name}} is based on a set of administrative UIs and a RESTful API, and provides the necessary means to create permissions
for your protected resources and scopes, associate these permissions with authorization policies, and enforce authorization
decisions in your applications and services.
Resource servers (the application or service serving protected resources) usually rely on some kind of information to decide whether access to a protected resource should be granted or not. For RESTful-based resource servers,
that information is usually obtained from a security token, usually sent as a bearer token on every single request to the server. For web applications that rely on a session to
authenticate their users, that information is usually stored into user's session and retrieved from there on every single request.
Resource servers (applications or services serving protected resources) usually rely on some kind of information to decide if access should be granted to a protected resource. For RESTful-based resource servers,
that information is usually obtained from a security token, usually sent as a bearer token on every request to the server. For web applications that rely on a session to
authenticate their users, that information is usually stored in a user's session and retrieved from there on every single request.
Usually, resource servers only perform authorization decisions based on _Role-based Access Control_ or _RBAC_, where the roles granted to the user trying to access protected resources are
Frequently, resource servers only perform authorization decisions based on _Role-based Access Control_ or _RBAC_, where the roles granted to the user trying to access protected resources are
checked against the roles mapped to these same resources. While roles are very useful and used by applications, they also have a few limitations:
* Resources and roles are tight coupled and changes to roles (add, remove or change it's access context) may impact several resources
* Resources and roles are tightly coupled and changes to roles (such as adding, removing or changing an access context) may impact several resources
* Changes to your security requirements may imply deep changes to application code to reflect these changes
* Depending on your application size, role management may become a problem and error-prone
* It is not the most flexible access control mechanism. Roles do not represent who you are and lack context information. If you have it, you can do something.
* Depending on your application size, role management may become difficult and error-prone
* It is not the most flexible access control mechanism. Roles do not represent who you are and lack context information. If you have a role, you can do something.
Considering that today we need to consider a very heterogeneous environment, where users are distributed across different regions, with different local policies,
using different devices and with a high demand for information sharing, {{book.project.name}} Authorization Services can help you to improve the authorization capabilities of your application and services by providing:
Considering that today we need to consider a heterogeneous environments, where users are distributed across different regions, with different local policies,
using different devices, and with a high demand for information sharing, {{book.project.name}} Authorization Services can help you improve the authorization capabilities of your applications and services by providing:
* Resource protection using fine-grained authorization policies and different access control mechanisms
* Centralized Resource, Permission and Policy Management
* Centralized Policy Decision Point
* REST security based on a set of REST-based Authorization Services
* Authorization Workflows and User-Managed Access
* The necessary means to avoid code replication across projects(and redeploys) and quickly adapt to changes in your security requirements
* The infrastructure to help avoid code replication across projects (and redeploys) and quickly adapt to changes in your security requirements

61
topics/overview/terminology.adoc
View file

@ -4,13 +4,13 @@ Before going further, it is important to understand some terms and concepts intr
==== Resource Server
If you are familiar with OAuth2, a Resource Server is the server hosting the protected resources and capable of accepting and responding to protected resource requests.
Per OAuth2 terminology, a Resource Server is the server hosting the protected resources and capable of accepting and responding to protected resource requests.
Resource servers usually rely on some kind of information to decide whether access to a protected resource should be granted or not. For RESTful-based resource servers,
that information is usually obtained from a security token, usually sent as a bearer token on every single request to the server. For web applications that rely on a session to
authenticate their users, that information is usually stored into user's session and retrieved from there on every single request.
that information is usually carried in a security token, typically sent as a bearer token along with every request to the server. Web applications that rely on a session to
authenticate their users usually store that information in the user's session and retrieve it from there on every request.
In Keycloak, any *confidential* client application may act as a resource server. Whose resources and their respective scopes are
In Keycloak, any *confidential* client application may act as a resource server. This client's resources and their respective scopes are
protected and ruled by a set of authorization policies.
==== Resource
@ -18,13 +18,12 @@ protected and ruled by a set of authorization policies.
A resource is part of the assets of an application and the organization. It can be a set of one or more endpoints, a classic web resource such as an HTML page, and so on.
In authorization policy terminology, a resource is the _object_ being protected.
Every single resource has a unique identifier, where a resource may also be used to represent a single
or a set of resources. For instance, you may want to manage a _Banking Account Resource_ that represents and defines a set of authorization policies for all banking accounts.
But you may also have a _Alice Banking Account_, which represents a single resource owned by a single customer, which may have its own set of authorization policies.
Every single resource has a unique identifier which may represent a single resource or a set of resources. For instance, you may want to manage a _Banking Account Resource_ that represents and defines a set of authorization policies for all banking accounts.
But you may also have a different resource named _Alice's Banking Account_, which represents a single resource owned by a single customer, which may have its own set of authorization policies.
==== Scope
A bounded extent of access that is possible to perform on a resource. In authorization policy
A resource's scope is a bounded extent of access that is possible to perform on a resource. In authorization policy
terminology, a scope is one of the potentially many _verbs_ that can logically apply to a resource.
It usually indicates what can be done with a given resource. Example of scopes are _view_,
@ -36,48 +35,48 @@ and permissions for those trying to access project's cost.
Consider this simple and very common permission:
A permission associates the object being protected with the policies that must be evaluated in order to decide whether or not access should be granted.
* *X* CAN DO *Y* ON RESOURCE *Z*
** where ...
*** *X* represents one or more Users, Roles, Groups or a combination of them. You can also use claims and context here ...
*** *Y* represents an action to be performed. Eg.: write, view, etc
*** *Z* represents a protected resource.
*** *Y* represents an action to be performed, e.g., "write", "view", etc
*** *Z* represents a protected resource, e.g., "/accounts".
A permission associates the object being protected and the policies that must be evaluated in order to decide whether access should be granted or not.
{{book.project.name}} provides a rich platform for building from the most simple to the more complex permissions. It provides great flexibility and helps to:
{{book.project.name}} provides a rich platform for building a range of permission strategies ranging from simple to very complex, rule-based dynamic permissions. It provides great flexibility and helps to:
* Reduce code refactoring and permission management costs
* Support a more flexible security model, helping you to easily adapt to changes to your security requirements
* Make changes at runtime given that applications only care about the resources and scopes being protect and not how they are actually protected
* Support a more flexible security model, helping you to easily adapt to changes in your security requirements
* Make changes at runtime -- applications only care about the resources and scopes being protected and not how they are actually protected
==== Policy
A policy defines the conditions that must be satisfied to grant access to an object. Different than permissions, you don't really specify the object being protected
but the conditions that must be satisfied to get access to a given object (eg.: resource, scope or both).
Policies are strongly related with the different _access control mechanism_ that you can use to actually protect your resources.
Within a policy you can use ABAC, RBAC, Context-based Access Control or any combination of these.
A policy defines the conditions that must be satisfied to grant access to an object. Different than permissions, you don't specify the object being protected
but the conditions that must be satisfied to get access to a given object (e.g., resource, scope, or both).
Policies are strongly related to the different _access control mechanisms_ that you can use to actually protect your resources.
With policies, you can implement strategies for ABAC, RBAC, Context-based Access Control or any combination of these.
Keycloak leverages the concept of policies and how you define them by providing the concept of *Aggregated Policies*, where you can build a "policy of policies" and still control the behavior of the evaluation.
Instead of writing a single and huge policy with all conditions that must be satisfied to get access to a given resource, policies in Keycloak follows the *divide-and-conquer* technique,
so you can create individual policies, reuse them on different permissions and build more complex policies by combining them into a single one.
Instead of writing a single and huge policy with all conditions that must be satisfied to get access to a given resource, the policies implementation in {{book.project.name}} {{book.project.module}} follows the *divide-and-conquer* technique.
That is, you can create individual policies, reuse them on different permissions, and build more complex policies by combining individual policies.
==== Policy Provider
Policy providers are responsible to support a specific policy type. Although {{book.project.name}} provides some built-in policies, backed by their corresponding
policy providers, nothing stops you to create your own policy types in order to better support your requirements or a specific use case.
Policy providers are implementations of specific policy types. {{book.project.name}} provides some built-in policies, backed by their corresponding
policy providers, and you are free to create your own policy types to support your specific requirements.
{{book.project.name}} provides a *SPI* (Service Provider Interface) that you can use to plug your own policy providers.
{{book.project.name}} provides a *SPI* (Service Provider Interface) that you can use to plug in your own policy provider implementations.
[[_permission_ticket]]
==== Permission Ticket
A Permission Ticket is a special type of token defined by the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification that provides an opaque structure whose form is determined by the authorization server. This
structure represents the resources and/or scopes being requested by a client as well the policies that must be applied to a request for authorization data (RPT).
A Permission Ticket is a special type of token defined by the https://docs.kantarainitiative.org/uma/rec-uma-core.html[OAuth2's User-Managed Access (UMA) Profile] specification that provides an opaque structure whose form is determined by the authorization server. This
structure represents the resources and/or scopes being requested by a client as well a the policies that must be applied to a request for authorization data (requesting party token or RPT).
In UMA, permission tickets are crucial to support *person-to-person sharing* and also *person-to-organization sharing*, introducing the possbility to cover from the most simple to the most complex
*authorization workflows*, where resource owners and resource servers may have complete control over their resources based on fine-grained policies that govern the access to these resources.
In UMA, permission tickets are crucial to support *person-to-person sharing* and also *person-to-organization sharing*. Using permission tickets for *authorization workflows* enables a range of scenarios from simple to complex,
where resource owners and resource servers have complete control over their resources based on fine-grained policies that govern the access to these resources.
During the UMA flow, permissions tickets are issued by the authorization server to a resource server, which in turn returns it back to the client trying to access a protected resource. Once the client
receives the ticket, it can request for a RPT (a final token holding authorization data) by sending the ticket back to the authorization server.
During the UMA flow, permission tickets are issued by the authorization server to a resource server, which in turn returns it back to the client trying to access a protected resource. Once the client
receives the ticket, it can make a request for a requesting party token (RPT) (a final token holding authorization data) by sending the ticket back to the authorization server.
For more details, take a look at link:../service/authorization/authorization-api.html[Authorization API] and https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification.
For more details, see link:../service/authorization/authorization-api.html[Authorization API] and the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification.

14
topics/permission/create-resource.adoc
View file

@ -2,7 +2,7 @@
A Resource-based permission defines a set of one or more resources to protect using a set of one or more authorization policies.
To create a new permission select the option *Resource-based* in the dropdown located in the right upper corner of the permission listing.
To create a new Resource-based permission, select the option *Resource-based* in the dropdown located in the right upper corner of the permission listing.
.Add Resource-Based Permission
image:../../images/permission/create-resource.png[alt="Add Resource-Based Permission"]
@ -12,11 +12,11 @@ image:../../images/permission/create-resource.png[alt="Add Resource-Based Permis
* *Name*
+
A human-readable and unique string describing the permission. We strongly suggest you to use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean
can identify them more easily and also know what they actually mean.
+
* *Description*
+
A string with more details about this policy
A string with more details about this permission.
[[_apply_resource_type]]
* *Apply To Resource Type*
@ -25,16 +25,16 @@ Specifies if this permission would be applied to all resources with a given type
+
** Resource Type
+
Defines the resource type to protect. When defined, this permission is going to be evaluated for all resources matching the type
Defines the resource type to protect. When defined, this permission is going to be evaluated for all resources matching the type.
+
* *Resources*
+
Defines a set of one or more resources to protect
Defines a set of one or more resources to protect.
* *Apply Policy*
+
Defines a set of one or more policies to associate with a permission
Defines a set of one or more policies to associate with a permission.
* *Decision Strategy*
+
The link:decision-strategy.html[Decision Strategy] for this permission
The link:decision-strategy.html[Decision Strategy] for this permission.

14
topics/permission/create-scope.adoc
View file

@ -4,7 +4,7 @@ A Scope-based permission defines a set of one or more scopes to protect using a
allows you to create permissions not only for a resource, but also for the scopes associated with it, providing more granularity when defining the permissions that govern your resources and the
actions that can be performed on them.
To create a new permission select the option *Scope-based* in the dropdown located in the right upper corner of the permission listing.
To create a new Scope-based permission, select the option *Scope-based* in the dropdown located in the right upper corner of the permission listing.
.Add Scope-Based Permission
image:../../images/permission/create-scope.png[alt="Add Scope-Based Permission"]
@ -14,24 +14,24 @@ image:../../images/permission/create-scope.png[alt="Add Scope-Based Permission"]
* *Name*
+
A human-readable and unique string describing the permission. We strongly suggest you to use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean
can identify them more easily and also know what they actually mean.
+
* *Description*
+
A string with more details about this permission
A string with more details about this permission.
+
* *Resource*
+
Restrict the scopes to those associated with the selected resource. If not selected all scopes would be available
Restrict the scopes to those associated with the selected resource. If not selected all scopes would be available.
+
* *Scopes*
+
Defines a set of one or more scopes to protect
Defines a set of one or more scopes to protect.
* *Apply Policy*
+
Defines a set of one or more policies to associate with a permission
Defines a set of one or more policies to associate with a permission.
* *Decision Strategy*
+
The link:decision-strategy.html[Decision Strategy] for this permission
The link:decision-strategy.html[Decision Strategy] for this permission.

6
topics/permission/decision-strategy.adoc
View file

@ -1,14 +1,14 @@
== Policy Decision Strategies
When associating policies to a permission, you may also define a decision strategy to decide how the outcome from the associated policies should be interpreted to build a final decision.
When associating policies to a permission, you may also define a decision strategy to specify how to evaluate the outcome of the associated policies to build a final decision.
* *Unanimous*
+
This is the default strategy if none is provided. In this case, _all_ policies must evaluate to a positive decision in order to the final decision be also positive.
This is the default strategy if none is provided. In this case, _all_ policies must evaluate to a positive decision in order for the final decision to be also positive.
+
* *Affirmative*
+
In this case, _at least one_ policy must evaluate to a positive decision in order to the final decision be also positive.
In this case, _at least one_ policy must evaluate to a positive decision in order for the final decision to be also positive.
+
* *Consensus*
+

4
topics/permission/overview.adoc
View file

@ -3,7 +3,7 @@
A permission associates the object being protected and the policies that must be evaluated in order to decide whether access should be granted or not.
After creating the resources you want to protect and the policies you want to use to actually protect these resources,
you can start managing permissions. For that, clicking on the *Permissions* tab when editing a resource server.
you can start managing permissions. For that, click on the *Permissions* tab when editing a resource server.
.Permissions
image:../../images/permission/view.png[alt="Permissions"]
@ -13,4 +13,4 @@ Permissions can be created to protect two main types of objects:
* *Resource*
* *Scope*
To create a permission, select the permission type you want to create from the dropdown located in the right upper corner of the permission listing.
To create a permission, select the permission type you want to create from the dropdown located in the right upper corner of the permission listing. The following sections describe these two types in more detail.

12
topics/permission/typed-resource-permission.adoc
View file

@ -1,18 +1,18 @@
== Typed Resource Permission
Resource permissions can also be used to define policies that must be applied to all resources with a given link:../resource/create.adoc#_type[Type]. This form of resource-based permission can be very handy when you have resources sharing very common access requirements and constraints.
Resource permissions can also be used to define policies that are to be applied to all resources with a given link:../resource/create.adoc#_type[Type]. This form of resource-based permission can be very handy when you have resources sharing very common access requirements and constraints.
Usually, resources within an application can be categorized (or typed) based on the data they encapsulate or the functionality they provide. For instance, a financial application manages different
banking accounts where each one belongs to a specific customer. Although they are different banking account, they usually share some very common security requirements and constraints, where those are globaly
defined by the banking organization. With typed resource permissions you may want to define some very common policies to all banking accounts:
Frequently, resources within an application can be categorized (or typed) based on the data they encapsulate or the functionality they provide. For instance, a financial application might manage different
banking accounts where each one belongs to a specific customer. Although they are different banking accounts, they share some common security requirements and constraints which are globally
defined by the banking organization. With typed resource permissions, you may want to define some common policies to apply to all banking accounts:
* Only the owner can manage his account
* Only allow access from the owner's country and/or region
* Enforce a specific authentication method
* And so forth ...
To create a typed resource permission, just click on link:./create-resource.adoc#_apply_resource_type[Apply to Resource Type] when creating a new resource permissions. Once you do that,
you should be able to specify the type that you want to protect as well the policies that must be applied in order to govern access to all resources with type you have provided.
To create a typed resource permission, click on link:./create-resource.adoc#_apply_resource_type[Apply to Resource Type] when creating a new resource-based permission. With `Apply to Resource Type` set to `On`,
you can specify the type that you want to protect as well the policies that are to be applied to govern access to all resources with type you have provided.
.Example of a Typed Resource Permission
image:../../images/typed-resource-perm-example.png[alt="Example of a Typed Resource Permission"]

12
topics/policy-evaluation-tool/overview.adoc
View file

@ -1,6 +1,6 @@
== Policy Evaluation Tool
When designing your policies, you can use an UI to simulate authorization requests and check how your policies are being evaluated.
When designing your policies, you can simulate authorization requests to check how your policies are being evaluated.
The *Policy Evaluation Tool* can be accessed by clicking the `Evaluate` tab when editing a resource server. There you may provide different inputs to simulate real authorization requests and check the effect of your policies.
@ -14,10 +14,12 @@ You can also click *Entitlement* button to obtain all permissions for the user y
=== Providing Contextual Information
The *Contextual Information* filters can be used to define additional attributes to the evaluation context, from where policies can
obtain these same attributes.
The *Contextual Information* filters can be used to define additional attributes to the evaluation context, so that policies can obtain these same attributes.
=== Providing the Permissions
The *Permissions* filters can be used to build an authorization request. There you can ask for permissions for a set of one or
more resources and scopes.
The *Permissions* filters can be used to build an authorization request. There you can ask for permissions for a set of one or more resources and scopes. In case you want
to simulate authorization requests based on all protected resources and scopes, click on the `Add` button without provide any `Resources` and `Scopes`.
When you've filled in the necessary values, click the `Evaluate` button to yield a result.

30
topics/policy/aggregated-policy.adoc
View file

@ -1,44 +1,44 @@
== Aggregated Policies
As mentioned before, Keycloak allows you to build a policy of policies, a concept that we call *Aggregated Policies*. Policy aggregation allows you to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the
As mentioned earlier, Keycloak allows you to build a policy of policies, a concept that we call *Aggregated Policies*. Policy aggregation allows you to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the
policies that are actually evaluated during the processing of authorization requests.
To create a new policy select the option *Aggregated* in the dropdown located in the right upper corner of the permission listing.
To create a new Aggregated policy, select the option *Aggregated* in the dropdown located in the right upper corner of the permission listing.
.Add Aggregated Policy
image:../../images/policy/create-aggregated.png[alt="Add Aggregated Policy"]
Let's suppose you have a resource called _Confidential Resource_ that can be accessed only by users from the _keycloak.org_ domain and within a IP address.
You may want to create a single policy with both conditions. However, you may want to reuse the domain part of this policy to apply to permissions despite the network.
Let's suppose you have a resource called _Confidential Resource_ that can be accessed only by users from the _keycloak.org_ domain and from a certain range of IP addresses.
You may want to create a single policy with both conditions. However, you may want to reuse the domain part of this policy to apply to permissions that operates regardless of originating network.
In this case, Keycloak allows you to create separated policies for both domain and network conditions and create another one based on
them. You can easily achieve that by using an *Aggregated Policy* that combines other policies and then apply this aggregated policy to any permission you want.
Keycloak allows you to create separate policies for both domain and network conditions and create a third policy based on
the combination of these two policies. With an *Aggregated Policy*, you can freely combine other policies and then apply the new aggregated policy to any permission you want.
[NOTE]
When creating aggregated policies, make sure you don't introduce a circular reference/dependency between policies. If you do so, Keycloak will not let you create or update the policy.
When creating aggregated policies, be mindful that you are not introducing a circular reference/dependency between policies. If a circular dependency is detected, Keycloak will not let you create or update the policy.
=== Configuration
* *Name*
+
A human-readable and unique string describing the policy. We strongly suggest you to use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean
A human-readable and unique string describing the policy. We strongly suggest that you use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean.
+
* *Description*
+
A string with more details about this policy
A string with more details about this policy.
+
* *Apply Policy*
+
Defines a set of one or more policies to associate with a policy
Defines a set of one or more policies to associate with a policy.
+
* *Decision Strategy*
+
The decision strategy for this permission
The decision strategy for this permission.
+
* *Logic*
+
The link:logic.html[logic] of this policy
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.
=== Decision Strategy for Aggregated Policies
@ -46,11 +46,11 @@ When creating aggregated policies, you can also define the decision strategy tha
* *Unanimous*
+
This is the default strategy if none is provided. In this case, _all_ policies must evaluate to a positive decision in order to the final decision be also positive.
This is the default strategy if none is provided. In this case, _all_ policies must evaluate to a positive decision in order for the final decision to be also positive.
+
* *Affirmative*
+
In this case, _at least one_ policy must evaluate to a positive decision in order to the final decision be also positive.
In this case, _at least one_ policy must evaluate to a positive decision in order for the final decision to be also positive.
+
* *Consensus*
+

30
topics/policy/drools-policy.adoc
View file

@ -1,9 +1,9 @@
== Drools-Based Policy
This type of policy allows you to define conditions for your permissions using Drools. It is one of the _Rule-Based_ policy types
supported by {{book.project.name}}, providing a lot of flexibility to write any policy based on the link:evaluation-api.adoc[Evaluation API].
This type of policy allows you to define conditions for your permissions using http://www.drools.org[Drools], which is a rule evaluation environment. It is one of the _Rule-Based_ policy types
supported by {{book.project.name}}, and provides flexibility to write any policy based on the link:evaluation-api.adoc[Evaluation API].
To create a new policy select the option *Drools* in the dropdown located in the right upper corner of the permission listing.
To create a new Drools-based policy, select the option *Drools* in the dropdown located in the right upper corner of the permission listing.
.Add Drools Policy
image:../../images/policy/create-drools.png[alt="Add Drools Policy"]
@ -12,44 +12,44 @@ image:../../images/policy/create-drools.png[alt="Add Drools Policy"]
* *Name*
+
A human-readable and unique string describing the policy. We strongly suggest you to use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean
A human-readable and unique string describing the policy. We strongly suggest that you use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean.
+
* *Description*
+
A string with more details about this policy
A string with more details about this policy.
+
* *Policy Maven Artifact*
+
A Maven GAV pointing to an artifact from where the rules would be loaded from. Once you have provided the GAV, you can click *Resolve* to load both *Module* and *Session* fields
A Maven groupId-artifactId-version (GAV) pointing to an artifact where the rules are defined. Once you have provided the GAV, you can click *Resolve* to load both *Module* and *Session* fields.
+
** Group Id
+
The groupId of the artifact
The groupId of the artifact.
+
** Artifact Id
+
The artifactId of the artifact
The artifactId of the artifact.
+
** Version
+
The version of the artifact
The version of the artifact.
+
* *Module*
+
The module used by this policy. You must provide a module in order to select a specific session from where rules will be loaded from
The module used by this policy. You must provide a module in order to select a specific session from where rules will be loaded from.
+
* *Session*
+
The session used by this policy. The session provides all the rules to evaluate when processing the policy
The session used by this policy. The session provides all the rules to evaluate when processing the policy.
+
* *Update Period*
+
Specifies an interval for scanning for artifact updates
Specifies an interval for scanning for artifact updates.
+
* *Logic*
+
The link:logic.html[logic] of this policy
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.
=== Examples
@ -87,4 +87,4 @@ rule "Authorize Using Identity Information"
end
```
For more details about what you can access from this interface, please take a look at link::/policy/evaluation-api.adoc[Evaluation API].
For more details about what you can access from the `org.keycloak.authorization.policy.evaluation.Evaluation` interface, see link:./evaluation-api.adoc[Evaluation API].

11
topics/policy/evaluation-api.adoc
View file

@ -1,7 +1,6 @@
== Evaluation API
When writing rule-based policies such as when you are using Javascript or JBoss Drools, {{book.project.name}} provides an *Evaluation API* from where you
can obtain useful information in order to decide whether a permission should be granted or not.
When writing rule-based policies using JavaScript or JBoss Drools, {{book.project.name}} provides an *Evaluation API* which provides useful information to help decide whether a permission should be granted or not.
This API consists of a few interfaces that provides you access to information such as:
@ -76,11 +75,11 @@ From this interface, policies can obtain:
* The authenticated `Identity`
* Information about the execution context and runtime environment
The `Identity` is built based on the OAuth2 Access Token that was sent along with the authorization request, from where you have access to all claims
extracted from the original token. For instance, if you are using a _Protocol Mapper_ to include a custom claim to a oAuth2 Access Token you can also access this claim
from a policy and use it to build your conditions
The `Identity` is built based on the OAuth2 Access Token that was sent along with the authorization request, and this construct has access to all claims
extracted from the original token. For instance, if you are using a _Protocol Mapper_ to include a custom claim in a OAuth2 Access Token you can also access this claim
from a policy and use it to build your conditions.
The `EvaluationContext` also gives you access to attributes related with both execution and runtime environment. For now, there only a few built-in attributes.
The `EvaluationContext` also gives you access to attributes related to both the execution and runtime environments. For now, there only a few built-in attributes.
.Execution and Runtime Attributes
|===

18
topics/policy/js-policy.adoc
View file

@ -1,9 +1,9 @@
== JavaScript-Based Policy
This type of policy allows you to define conditions for your permissions using JavaScript. It is one of the _Rule-Based_ policy types
supported by {{book.project.name}}, providing lot of flexibility to write any policy based on the link:evaluation-api.adoc[Evaluation API].
supported by {{book.project.name}}, and provides flexibility to write any policy based on the link:evaluation-api.adoc[Evaluation API].
To create a new policy select the option *JavaScript* in the dropdown located in the right upper corner of the permission listing.
To create a new JavaScript-based policy, select the option *JavaScript* in the dropdown located in the right upper corner of the permission listing.
.Add JavaScript Policy
image:../../images/policy/create-js.png[alt="Add JavaScript Policy"]
@ -12,20 +12,20 @@ image:../../images/policy/create-js.png[alt="Add JavaScript Policy"]
* *Name*
+
A human-readable and unique string describing the policy. We strongly suggest you to use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean
A human-readable and unique string describing the policy. We strongly suggest that you use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean.
+
* *Description*
+
A string with more details about this policy
A string with more details about this policy.
+
* *Code*
+
The JavaScript code providing the conditions for this policy
The JavaScript code providing the conditions for this policy.
+
* *Logic*
+
The link:logic.html[logic] of this policy
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.
=== Examples
@ -41,7 +41,7 @@ if (contextAttributes.containsValue('kc.client.network.ip_address', '127.0.0.1')
}
```
You can even use RBAC if you want to:
You can also use RBAC:
```javascript
var identity = $evaluation.getIdentity();
@ -65,4 +65,4 @@ if (identity.hasRole('admin') || email.endsWith('@keycloak.org')) {
```
When writing your own rules, keep in mind that the *$evaluation* object is just a object implementing *org.keycloak.authorization.policy.evaluation.Evaluation*. For more details about what you can access from this interface,
please take a look at link:evaluation-api.adoc[Evaluation API].
see link:evaluation-api.adoc[Evaluation API].

6
topics/policy/overview.adoc
View file

@ -1,12 +1,12 @@
== Managing Policies
As mentioned before, policies define the conditions that must satisfied before granting access to an object.
As mentioned earlier, policies define the conditions that must be satisfied before granting access to an object.
You can view all policies associated with a resource server by clicking on the *Policy* tab when editing a resource server.
.Policies
image:../../images/policy/view.png[alt="Policies"]
On this tab, you'll find the list of policies and options to create and edit a policy.
On this tab, you'll find the list of policies as well as options to create and edit a policy.
To create a new policy, select a policy type in the dropdown `Create policy` located in the right upper corner of the policy listing.
To create a new policy, select a policy type in the dropdown `Create policy` located in the right upper corner of the policy listing. Details about each policy type are described in this section.

10
topics/policy/role-policy-required-role.adoc
View file

@ -1,13 +1,13 @@
== Defining a Role as Required
When creating a role-based policy, you may mark a specific role as `Required`. When you do that, the policy will only grant access
if the user asking for access is granted with *all* the *required* roles. Both realm and client roles can be configured as such.
When creating a role-based policy, you may mark a specific role as `Required`. When you do that, the policy will grant access
only if the user asking for access is granted with *all* the *required* roles. Both realm and client roles can be configured as such.
.Example of Required Role
image:../../images/policy/create-role.png[alt="Example of Required Role"]
To mark a role as required, just mark the `Required` checkbox on the corresponding role you want configure as required.
To mark a role as required, mark the `Required` checkbox on the role you want to configure as required.
Required roles can be very handy when your policy defines multiple roles but only a subset of them are mandatory. In this case, you can mix realm and client roles to enable an
even more fine-grained RBAC model to your application. For instance, you may have policies specific for a client and require a specific a client role associated with that client. Or you can just
enforce that access is only granted based on the presence of a specific realm role. Or even have both approaches within the same policy.
even more fine-grained RBAC model for your application. For instance, you may have policies specific for a client and require a specific client role associated with that client. Or you can just
enforce that access is granted only in the presence of a specific realm role. Or even have both approaches within the same policy.

16
topics/policy/role-policy.adoc
View file

@ -4,14 +4,14 @@ This type of policy allows you to define conditions for your permissions where o
to access an object.
By default, roles added to this policy are not marked as required and the policy will grant access if the user asking for access has any of these roles. However, {{book.project.name}} also allows you
to mark a specific role as link:role-policy-required-role.adoc[required] in case you want to enforce the presence of a role. You can even mix required and non-required roles, regardles if they are realm
to mark a specific role as link:role-policy-required-role.adoc[required] in case you want to enforce the presence of a role. You can even mix required and non-required roles, regardless of whether they are realm
or client roles.
Role policies can be very useful when you need a more restricted RBAC, where specific roles must be present in order to grant access to an object. For instance,
you may enforce that an user must consent to letting a client application (which is acting on his behalf) access his resources. Here you can benefit from {{book.project.name}} Client Scope Mapping to
Role policies can be very useful when you need a more restricted role-based access control (RBAC), where specific roles must be present in order to grant access to an object. For instance,
you may enforce that a user must consent to letting a client application (which is acting on his behalf) access his resources. Here you can benefit from {{book.project.name}} Client Scope Mapping to
enable consent pages or even enforce clients to explicitly provide a scope when obtaining access tokens from a {{book.project.name}} server.
To create a new policy select the option *Role-Based* in the dropdown located in the right upper corner of the permission listing.
To create a new Role-based policy, select the option *Role-Based* in the dropdown located in the right upper corner of the permission listing.
.Add Role-Based Policy
image:../../images/policy/create-role.png[alt="Add Role-Based Policy"]
@ -20,12 +20,12 @@ image:../../images/policy/create-role.png[alt="Add Role-Based Policy"]
* *Name*
+
A human-readable and unique string describing the policy. We strongly suggest you to use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean
A human-readable and unique string describing the policy. We strongly suggest that you use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean.
+
* *Description*
+
A string with more details about this policy
A string with more details about this policy.
+
* *Realm Roles*
+
@ -37,4 +37,4 @@ Specifies which *client* role(s) are allowed by this policy. To enable this fiel
+
* *Logic*
+
The link:logic.html[logic] of this policy
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.

26
topics/policy/time-policy.adoc
View file

@ -2,7 +2,7 @@
This type of policy allows you to define time conditions for your permissions.
To create a new policy select the option *Time* in the dropdown located in the right upper corner of the permission listing.
To create a new Time-based policy, select the option *Time* in the dropdown located in the right upper corner of the permission listing.
.Add Time Policy
image:../../images/policy/create-time.png[alt="Add Time Policy"]
@ -11,44 +11,44 @@ image:../../images/policy/create-time.png[alt="Add Time Policy"]
* *Name*
+
A human-readable and unique string describing the policy. We strongly suggest you to use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean
A human-readable and unique string describing the policy. We strongly suggest that you use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean.
+
* *Description*
+
A string with more details about this policy
A string with more details about this policy.
+
* *Not Before*
+
Defines the time before which the policy MUST NOT be granted. Only granted if current date/time is after or equal to this value
Defines the time before which the policy MUST NOT be granted. Permission is granted only if the current date/time is after or equal to this value.
+
+
* *Not On or After*
+
Defines the time after which the policy MUST NOT be granted. Only granted if current date/time is before or equal to this value
Defines the time after which the policy MUST NOT be granted. Permission is granted only if the current date/time is before or equal to this value.
+
* *Day of Month*
+
Defines the day of month which policy MUST be granted. You can also provide a range by filling the second field with the day of month before/equal which the policy MUST be granted. In this case, the policy would be granted if current day of month is between or equal to the two values you provided.
Defines the day of month which the policy MUST be granted. You can also provide a range by filling the second field. In this case, permission is granted only if current day of month is between or equal to the two values you provided.
+
* *Month*
+
Defines the month which policy MUST be granted. You can also provide a range by filling the second field with the month before/equal which the policy MUST be granted. In this case, the policy would be granted if current month is between or equal to the two values you provided.
Defines the month which the policy MUST be granted. You can also provide a range by filling the second field. In this case, permission is granted only if current month is between or equal to the two values you provided.
+
* *Year*
+
Defines the year which policy MUST be granted. You can also provide a range by filling the second field with the year before/equal which the policy MUST be granted. In this case, the policy would be granted if current year is between or equal to the two values you provided.
Defines the year which the policy MUST be granted. You can also provide a range by filling the second field. In this case, permission is granted only if current year is between or equal to the two values you provided.
+
* *Hour*
+
Defines the hour which policy MUST be granted. You can also provide a range by filling the second field with the hour before/equal which the policy MUST be granted. In this case, the policy would be granted if current hour is between or equal to the two values you provided.
Defines the hour which the policy MUST be granted. You can also provide a range by filling the second field. In this case, permission is granted only if current hour is between or equal to the two values you provided.
+
* *Minute*
+
Defines the minute which policy MUST be granted. You can also provide a range by filling the second field with the minute before/equal which the policy MUST be granted. In this case, the policy would be granted if current minute is between or equal to the two values you provided.
Defines the minute which the policy MUST be granted. You can also provide a range by filling the second field. In this case, permission is granted only if current minute is between or equal to the two values you provided.
+
* *Logic*
+
The link:logic.html[logic] of this policy
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.
In order to the policy evaluate to a _GRANT_, all conditions that you defined must be true. Keycloak will perform an _AND_ with the outcome from each one of the conditions you have defined.
Permissions are only granted if all conditions are satisfied. {{book.project.name}} will perform an _AND_ based on the outcome of each condition.

12
topics/policy/user-policy.adoc
View file

@ -3,7 +3,7 @@
This type of policy allows you to define conditions for your permissions where only a set of one or more users is allowed
to access an object.
To create a new policy select the option *User-Based* in the dropdown located in the right upper corner of the permission listing.
To create a new User-based policy, select the option *User-Based* in the dropdown located in the right upper corner of the permission listing.
.Add User-Based Policy
image:../../images/policy/create-user.png[alt="Add User-Based Policy"]
@ -12,17 +12,17 @@ image:../../images/policy/create-user.png[alt="Add User-Based Policy"]
* *Name*
+
A human-readable and unique string describing the policy. We strongly suggest you to use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean
A human-readable and unique string describing the policy. We strongly suggest that you use names that are closely related with your business and security requirements, so you
can identify them more easily and also know what they actually mean.
+
* *Description*
+
A string with more details about this policy
A string with more details about this policy.
+
* *Users*
+
Specifies which user(s) are allowed by this policy
Specifies which user(s) are allowed by this policy.
+
* *Logic*
+
The link:logic.html[logic] of this policy
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.

8
topics/resource-server/create-client.adoc
View file

@ -10,16 +10,16 @@ In this page, click on the `Create` button on the right.
.Create Client
image:../../images/resource-server/client-create.png[alt="Create Client"]
In this page, fill in the fields as follows:
Fill in the fields as follows:
* Enter in the `Client ID` of the client. For insance, _my-resource-server_.
* Enter in the `Root URL` for your application. For instance:
* Enter the `Client ID` of the client. For example, _my-resource-server_.
* Enter the `Root URL` for your application. For instance:
+
```bash
http://${host}:${port}/my-resource-server
```
Finally, click `Save`. This will create the client and bring you to the client `Settings` tab.
Finally, click `Save`. This will create the client and bring you to the client `Settings` tab. You should see a page similar to this:
.Client Settings
image:../../images/resource-server/client-enable-authz.png[alt="Client Settings"]

16
topics/resource-server/default-config.adoc
View file

@ -1,11 +1,11 @@
== Default Configuration
When you create a resource server, {{book.project.name}} creates a default configuration to your newly created resource server.
When you create a resource server, {{book.project.name}} creates a default configuration for your newly created resource server.
The default configuration consists of:
* A default protected resource representing all resources in your application.
* A policy that grants access only for users within the same _realm_ as the resource server.
* A policy that always grants access to the resources protected by this policy.
* A permission that governs access to all resources based on the default policy.
The default protected resource is called *Default Resource* and you can see it if you click on the `Resources` tab.
@ -13,12 +13,12 @@ The default protected resource is called *Default Resource* and you can see it i
.Default Resource
image:../../images/resource-server/default-resource.png[alt="Default Resource"]
This resource defines a `Type` `urn:my-resource-server:resources:default` and an `URI` `/*`. Here, the `URI` field defines a
This resource defines a `Type` namely `urn:my-resource-server:resources:default` and a `URI` `/*`. Here, the `URI` field defines a
wildcard pattern that tells {{book.project.name}} that this resource represents all the paths in your application. In other words,
when enabling link:../enforcer/overview.html[Policy Enforcement] to your application, all the permissions associated with the resource
when enabling link:../enforcer/overview.html[Policy Enforcement] for your application, all the permissions associated with the resource
will be checked before granting access.
The `Type` aforementioned defines a value that can be used to create link:../permission/typed-resource-permission.adoc[Typed Resource Permissions] that must be applied
The `Type` mentioned earlier defines a value that can be used to create link:../permission/typed-resource-permission.adoc[Typed Resource Permissions] that must be applied
to the default resource or any other resource you create using the same type.
The default policy is called *Only From Realm Policy* and you can see it if you click on the `Policies` tab.
@ -26,14 +26,14 @@ The default policy is called *Only From Realm Policy* and you can see it if you
.Default Policy
image:../../images/resource-server/default-policy.png[alt="Default Policy"]
This policy is a link:../policy/js-policy.html[JavaScript-Based Policy] defining a condition that always grant access to the resources protected by this policy. If you click on this policy you'll see that it defines a rule as follows:
This policy is a link:../policy/js-policy.html[JavaScript-Based Policy] defining a condition that always grants access to the resources protected by this policy. If you click on this policy you'll see that it defines a rule as follows:
```js
// by default, grants any permission associated with this policy
$evaluation.grant();
```
For last, the default permission is called *Default Permission* and you can see it if you click on the `Permissions` tab.
Lastly, the default permission is called *Default Permission* and you can see it if you click on the `Permissions` tab.
.Default Permission
image:../../images/resource-server/default-permission.png[alt="Default Permission"]
@ -43,4 +43,4 @@ This permission is a link:../permission/overview.html[Resource-Based Permission]
== Post-Configuration Instructions
You are not forced to keep the default configuration if you don't want to. You can remove the default resource, policy and permission any time you want.
You are not forced to keep the default configuration if you don't want to. You can remove the default resource, policy, and permission definitions and introduce your own.

14
topics/resource-server/enable-authorization.adoc
View file

@ -1,12 +1,12 @@
== Enabling Authorization Services
To turn your client application into a resource server and enable fine-grained authorization, click on the `Authorization Services Enable` switch and turn it `ON`.
To turn your OIDC Client Application into a resource server and enable fine-grained authorization, click on the `Authorization Enabled` switch and turn it `ON`.
.Enabling Authorization Services
image:../../images/resource-server/client-enable-authz.png[alt="Enabling Authorization Services"]
Finally, click `Save`. When you do that,
a new `Authorization` tab will show up. Click on this tab and you should see a page like that.
Finally, click `Save`. When the save is complete,
a new `Authorization` tab will show up in the tab set for this client. Click on this tab and you should see a page similar to the following:
.Resource Server Settings
image:../../images/resource-server/authz-settings.png[alt="Resource Server Settings"]
@ -53,16 +53,16 @@ This is the default mode. Requests are denied by default even when there is no p
** *Permissive*
+
Requests are allowed even when there is no policy associated with a given resource.
+
** *Disabled*
+
Completely disables the evaluation of policies and allow access to any resource.
Completely disables the evaluation of policies and allows access to any resource.
+
* *Allow Remote Resource Management*
+
Should resources be managed remotely by the resource server? If false, resources can only be managed from this admin console.
Should resources be managed remotely by the resource server? If false, resources can be managed only from this admin console.
+
* *Export Settings*
+
In this section you can export all settings to a JSON file. It provides a single `Export` button that you can click to
download a JSON file containing every single configuration defined for a resource server: protected resources, scopes, permissions and policies.
In this section you can export the authorization configuration settings to a JSON file. Click the `Export` button to display the complete JSON configuration for you to download. The configuration contains everything defined for a resource server: protected resources, scopes, permissions and policies.

12
topics/resource-server/import-config.adoc
View file

@ -1,7 +1,7 @@
== Exporting and Importing Configuration
All the configuration defined for a resource server can be exported and downloaded. The resulting configuration file contains
every single configuration you defined for:
The configuration settings for a resource server can be exported and downloaded. The resulting configuration contains settings you've introduced for the resource server (client).
Import/Export is helpful when you would like to create an initial configuration for a resource server or to update an existing configuration. The configuration contains definitions for:
* Protected Resources and Scopes
* Policies
@ -17,11 +17,9 @@ In this page, you'll see a `Export Settings` section, which provides a single `E
.Export Settings
image:../../images/resource-server/authz-export.png[alt="Export Settings"]
The configuration is exported using a JSON format, which you can copy and paste or click on the `Download` button to download a file with the configuration being exported.
The configuration is exported in JSON format and displyed in a text area, which you can copy and paste. You may also click the `Download` button to download the configuration as a file.
=== Importing
To import a file with the configuration for your resource server, click on the `Select file`. It should open a dialog box from where you can select a file in your
filesystem with the configuration you want to import.
You can use this feature to both create an initial configuration for your resource server or to update the existing configuration.
To import a file with the configuration for a resource server, click on the `Select file` to open a file chooser dialog to select a file in your
filesystem containing the configuration you want to import.

2
topics/resource-server/overview.adoc
View file

@ -1,6 +1,6 @@
== Managing Resource Servers
If you are familiar with OAuth2, a Resource Server is the server hosting the protected resources and capable of accepting and responding to protected resource requests.
According to the OAuth2 specification, a Resource Server is the server hosting the protected resources and capable of accepting and responding to protected resource requests.
In {{book.project.name}}, resource servers are provided with a rich platform for enabling fine-grained authorization to their protected resources, where authorization decisions can be made
based on different access control mechanisms.

16
topics/resource/create.adoc
View file

@ -1,9 +1,9 @@
== Creating Resources
Create a resource is pretty straight forward and generic. The main thing you should care about is the granularity of the resources you create. In other words, resources can
Creating a resource is straightforward and generic. Your main concern is the granularity of the resources you create. In other words, resources can
be created to represent a set of one or more resources and the way you define them is crucial to start managing permissions.
To create a new resource click on the *Create* button in the right upper corner of the resource listing.
To create a new resource, click on the `Create` button in the right upper corner of the resource listing.
.Add Resource
image:../../images/resource/create.png[alt="Add Resource"]
@ -12,13 +12,13 @@ In {{book.project.name}}, a resource defines a small set of information that is
* *Name*
+
A human-readable and unique string describing a set of one or more resources.
A human-readable and unique string describing this resource.
[[_type]]
* *Type*
+
A string uniquely identifying the type of a set of one or more resources. Usually, the type is a URN that can be used to
group different resource instances.
A string uniquely identifying the type of a set of one or more resources. The type is a _string_ used to group different resource instances.
For example, the default type for the default resource that is automatically created is `urn:resource-server-name:resources:default`
[[_uri]]
* *URI*
@ -37,7 +37,7 @@ The type field of a resource may be used to group different resources together,
=== Resource Owners
Resources also have an owner. By default, resources are owned by the resource server.
However, resources can also be associated with your users, so you can create permissions based on the resource owner. For instance, only the resource owner is allowed to delete or update a given resource.
However, resources can also be associated with your users, so you can create permissions based on the resource owner. For example, only the resource owner is allowed to delete or update a given resource.
=== Managing Resources Remotely
@ -47,5 +47,5 @@ When using the Protection API, resource servers can be implemented to manage res
specify the user identifier to configure a resource as belonging to a specific user.
[NOTE]
{{book.project.name}} provides to resource servers completely control over its resources. In the future, we should be able to
allow users to control their own resources as well, approve authorization requests and manage permissions. Specially when using the UMA protocol.
{{book.project.name}} provides resource servers complete control over their resources. In the future, we should be able to
allow users to control their own resources as well, approve authorization requests and manage permissions, especially when using the UMA protocol.

4
topics/resource/overview.adoc
View file

@ -1,4 +1,4 @@
== Managing Resources and Scopes
Resource management is pretty straight forward and generic. After creating a resource server, you can start creating the resources and scopes that you want to protect.
Resources and scopes can be managed by clicking on the *Resource* and *Scope* tabs, respectively.
Resource management is straightforward and generic. After creating a resource server, you can start creating the resources and scopes that you want to protect.
Resources and scopes can be managed by clicking on the *Resource* and *Scope* tabs, respectively. Details about `Resources` and `Scopes` are described in this section

6
topics/resource/view.adoc
View file

@ -1,6 +1,6 @@
=== Viewing Resources
When you click on *Resource* tab, you'll be redirect to a page listing all the resources associated with a resource server.
When you click on *Resource* tab, you'll see a page that lists the resources associated with a resource server.
.Resources
image:../../images/resource/view.png[alt="Resources"]
@ -13,7 +13,7 @@ The resource list provides some very useful information about the protected reso
* Associated scopes, if any
* Associated permissions
From there you can also create a permission right away by clicking on `Create Permission` button for the resource you want to create the permission.
From this list, you can also directly create a permission by clicking on the `Create Permission` button for the resource you want to create the permission.
[NOTE]
Before creating permissions to your resources, make sure you already have any policy to associated with the permission.
Before creating permissions to your resources, make sure you have already defined the policies you want to associate with the permission.

6
topics/service/authorization/authorization-api-aapi.adoc
View file

@ -2,13 +2,13 @@
Client applications using the UMA protocol can use a specific endpoint to obtain a special security token called *Requesting Party Token* or *RPT*.
This token consists of all the permissions granted to an user as a result of the evaluation of the permissions and authorization policies associated with the resource(s) being requested.
With an RPT in hands, client applications can gain access to protected resources at the resource server.
With an RPT in hand, client applications can gain access to protected resources at the resource server.
```bash
http://${host}:${port}/auth/realms/${realm_name}/authz/authorize
```
When asking for a RPT, you need to provide two main things:
When asking for a RPT, you need to provide two things:
* A link:../protection/permission-api-papi.adoc[Permission Ticket] with the resources you want to access
* The link:./whatis-obtain-aat.adoc[AAT] (as a bearer token) representing user's identity and his consent to access authorization data on his behalf.
@ -28,7 +28,7 @@ As a result, you will get the following response from the server:
=== Requesting Party Token or RPT
A RPT is basically a https://tools.ietf.org/html/rfc7519[JSON Web Token (JWT)] digitally signed using https://www.rfc-editor.org/rfc/rfc7515.txt[JSON Web Signature (JWS)].
A RPT is a https://tools.ietf.org/html/rfc7519[JSON Web Token (JWT)] digitally signed using https://www.rfc-editor.org/rfc/rfc7515.txt[JSON Web Signature (JWS)].
The token is built based on the AAT sent by the client during the authorization process.
When you decode a RPT you will see something like that:

8
topics/service/authorization/whatis-obtain-aat.adoc
View file

@ -1,17 +1,17 @@
== What is a AAT and How to Obtain it ?
An *Authorization API Token* or *AAT* is a special OAuth2 Access Token with the scope *uma_authorization*. When you create an user, {{book.project.name}} automatically
An *Authorization API Token* or *AAT* is a special OAuth2 Access Token with the scope *uma_authorization*. When you create a user, {{book.project.name}} automatically
assigns a role _uma_authorization_ to the user. The _uma_authorization_ role is a _default realm role_ as you can see from this page.
.Default Role uma_authorization
image:../../../images/service/rs-uma-authorization-role.png[alt="Default Role uma_authorization "]
An AAT means that a client application is allowed to query the server for user permissions.
An AAT enables a client application to query the server for user permissions.
Client applications can obtain an AAT from {{book.project.name}} just like any other OAuth2 Access Token. Usually, client applications obtain AATs after the user is successfully
authenticated in {{book.project.name}}. By default the _authorizaton_code_ grant type is used to authenticate users and issue an OAuth2 Access Token to the client application acting on their behalf.
authenticated in {{book.project.name}}. By default, the _authorization_code_ grant type is used to authenticate users, and the server will issue an OAuth2 Access Token to the client application acting on their behalf.
For demonstrations purposes, the example below uses Resource Owner Password Credentials Grant Type to ask for a AAT.
For demonstration purposes, the example below uses Resource Owner Password Credentials Grant Type to request an AAT.
```bash
curl -X POST \

37
topics/service/client-api.adoc
View file

@ -1,6 +1,6 @@
== Authorization Client API
If you are using Java you can access all {{book.project.name}} {{book.project.module}} using a client API.
If you are using Java, you can access all {{book.project.name}} {{book.project.module}} using a Client API.
=== Maven Dependency
@ -46,18 +46,21 @@ Specify the credentials of the application. This is an object notation where the
=== Obtaining User Entitlements
Here is an example about how to obtain user entitlements:
Here is an example illustrating how to obtain user entitlements:
```java
// create a new instance based on the configuration define at keycloak-authz.json
// create a new instance based on the configuration defined in keycloak-authz.json
AuthzClient authzClient = AuthzClient.create();
// obtian a Entitlement API Token in order to get access to the Entitlement API.
// this token is just an access token issued to a client on behalf of an user with a scope kc_entitlement
// obtain an Entitlement API Token in order to get access to the Entitlement API.
// this token is just an access token issued to a client on behalf of an user
// with a scope = kc_entitlement
String eat = getEntitlementAPIToken(authzClient);
// send the entitlement request to the server in order to obtain a RPT with all permissions granted to the user
EntitlementResponse response = authzClient.entitlement(eat).getAll("hello-world-authz-service");
// send the entitlement request to the server in order to
// obtain an RPT with all permissions granted to the user
EntitlementResponse response = authzClient.entitlement(eat)
.getAll("hello-world-authz-service");
String rpt = response.getRpt();
System.out.println("You got a RPT: " + rpt);
@ -65,14 +68,15 @@ System.out.println("You got a RPT: " + rpt);
// now you can use the RPT to access protected resources on the resource server
```
Here is an example about how to obtain user entitlements given a set of one or more resource:
Here is an example illustrating how to obtain user entitlements for a set of one or more resources:
```java
// create a new instance based on the configuration define at keycloak-authz.json
// create a new instance based on the configuration defined in keycloak-authz.json
AuthzClient authzClient = AuthzClient.create();
// obtian a Entitlement API Token in order to get access to the Entitlement API.
// this token is just an access token issued to a client on behalf of an user with a scope kc_entitlement
// obtain an Entitlement API Token in order to get access to the Entitlement API.
// this token is just an access token issued to a client on behalf of an user
// with a scope = kc_entitlement
String eat = getEntitlementAPIToken(authzClient);
// create an entitlement request
@ -83,8 +87,10 @@ permission.setResourceSetName("Hello World Resource");
request.addPermission(permission);
// send the entitlement request to the server in order to obtain a RPT with all permissions granted to the user
EntitlementResponse response = authzClient.entitlement(eat).get("hello-world-authz-service", request);
// send the entitlement request to the server in order to obtain a RPT
// with all permissions granted to the user
EntitlementResponse response = authzClient.entitlement(eat)
.get("hello-world-authz-service", request);
String rpt = response.getRpt();
System.out.println("You got a RPT: " + rpt);
@ -93,7 +99,7 @@ System.out.println("You got a RPT: " + rpt);
=== Creating a Resource Using the Protection API
```java
// create a new instance based on the configuration define at keycloak-authz.json
// create a new instance based on the configuration defined in keycloak-authz.json
AuthzClient authzClient = AuthzClient.create();
// create a new resource representation with the information we want
@ -105,7 +111,8 @@ newResource.setType("urn:hello-world-authz:resources:example");
newResource.addScope(new ScopeRepresentation("urn:hello-world-authz:scopes:view"));
ProtectedResource resourceClient = authzClient.protection().resource();
Set<String> existingResource = resourceClient.findByFilter("name=" + newResource.getName());
Set<String> existingResource = resourceClient
.findByFilter("name=" + newResource.getName());
if (!existingResource.isEmpty()) {
resourceClient.delete(existingResource.iterator().next());

28
topics/service/entitlement/entitlement-api-aapi.adoc
View file

@ -1,8 +1,8 @@
== Requesting Entitlements
Client applications can use a specific endpoint to obtain a special security token called *Requesting Party Token* or *RPT*.
This token consists of all the entitlements(or permissions) for an user as a result of the evaluation of the permissions and authorization policies associated with the resource(s) being requested.
With an RPT in hands, client applications can gain access to protected resources at the resource server.
Client applications can use a specific endpoint to obtain a special security token called a *Requesting Party Token* or *RPT*.
This token consists of all the entitlements (or permissions) for a user as a result of the evaluation of the permissions and authorization policies associated with the resource(s) being requested.
With an RPT in hand, client applications can gain access to protected resources at the resource server.
```bash
http://${host}:${port}/auth/realms/${realm_name}/authz/entitlement
@ -10,7 +10,7 @@ http://${host}:${port}/auth/realms/${realm_name}/authz/entitlement
=== Obtaining Entitlements
The easiest way to obtain entitlements for a specific user is using an HTTP GET request.
The easiest way to obtain entitlements for a specific user is using an HTTP GET request. For example, using curl:
```bash
curl -X GET \
@ -19,9 +19,9 @@ curl -X GET \
```
[NOTE]
When asking for entitlements using this endpoint, you need to provide the access_token (as a bearer token) representing user's identity and his consent to access authorization data on his behalf.
When asking for entitlements using this endpoint, you need to provide the access_token (as a bearer token) representing a user's identity and his consent to access authorization data on his behalf.
Where *${resource_server_id}* is the *client_id* registered with the client application acting as a resource server.
In the curl example, *${resource_server_id}* is the *client_id* registered with the client application acting as a resource server.
As a result, you'll get a response from the server as follows:
@ -31,12 +31,12 @@ As a result, you'll get a response from the server as follows:
}
```
When using this method to obtain entitlements, the server is going to respond the requesting client with *all* entitlements for an user, based on the evaluation of the permissions and
authorization policies associated with all resources managed by the resource server.
Using this method to obtain entitlements, the server will respond to the requesting client with *all* entitlements for a user, based on the evaluation of the permissions and
authorization policies associated with the resources managed by the resource server.
=== Obtaining Entitlements for a Specific Set of Resources
The entitlements endpoint also allows you to obtain user's entitlements for a set of one or more resources.
The entitlements endpoint also allows you to obtain a user's entitlements for a set of one or more resources. For example, using curl:
```bash
curl -X POST -H "Authorization: Bearer ${access_token}" -d '{
@ -56,10 +56,10 @@ As a result, you'll get a response from the server as follows:
}
```
Unlike the GET version, the server is going to respond with a RPT holding the permissions granted during the evaluation of the permissions and authorization policies
associated with the resources being requested.
Unlike the GET version, the server is going to respond with an RPT holding the permissions granted during the evaluation of the permissions and authorization policies
associated with the resources being requested.
When asking for entitlements you can also specify the scopes you want to have access:
When asking for entitlements, you can also specify the scopes you want to have access. Using curl:
```bash
curl -X POST -H "Authorization: Bearer ${access_token}" -d '{
@ -76,10 +76,10 @@ curl -X POST -H "Authorization: Bearer ${access_token}" -d '{
=== Requesting Party Token or RPT
A RPT is basically a https://tools.ietf.org/html/rfc7519[JSON Web Token (JWT)] digitally signed using https://www.rfc-editor.org/rfc/rfc7515.txt[JSON Web Signature (JWS)].
A RPT is a https://tools.ietf.org/html/rfc7519[JSON Web Token (JWT)] digitally signed using https://www.rfc-editor.org/rfc/rfc7515.txt[JSON Web Signature (JWS)].
The token is built based on the access_token sent by the client during the authorization process.
When you decode a RPT you will see something like that:
When you decode a RPT, you will see a payload similar to the following:
```json
{

4
topics/service/entitlement/entitlement-api.adoc
View file

@ -3,7 +3,7 @@
The *Entitlement API* provides a 1-legged protocol for obtaining authorization data from the server, where the authorization data
represents the result of the evaluation of all permissions and authorization policies associated with the resources being requested.
Unlike the _Authorization API_, the Entitlement API is not UMA-compliant and don't require permission tickets.
Unlike the _Authorization API_, the Entitlement API is not UMA-compliant and doesn't require permission tickets.
The purpose of this API is provide a more lightweight API for obtaining authorization data, where the client in possession of a valid
OAuth2 Access Token is able to obtain the necessary authorization data on behalf of their users.
OAuth2 Access Token is able to obtain the necessary authorization data on behalf of its users.

6
topics/service/overview.adoc
View file

@ -1,6 +1,6 @@
== Authorization Services
Keycloak Authorization Services are based on OAuth2 and User-Managed Access (UMA).
{{book.project.name}} {{book.project.module}} are based on OAuth2's User-Managed Access (UMA) Profile.
In this section you'll learn about the different RESTful endpoints that you can interact with in order to enable fine-grained
authorization to your application and services.
This section describes the different RESTful endpoints that you can interact with in order to enable fine-grained authorization
to your application and services.

16
topics/service/protection/permission-api-papi.adoc
View file

@ -1,21 +1,21 @@
== Managing Permission Requests
Resources servers using the UMA protocol can use a specific endpoint to manage permission requests. This endpoint provides a UMA-compliant flow for registering permissions requests and obtaining a *Permission Ticket*.
Resource servers using the UMA protocol can use a specific endpoint to manage permission requests. This endpoint provides a UMA-compliant flow for registering permissions requests and obtaining a *Permission Ticket*.
```bash
http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission
```
A link:../../overview/terminology.adoc#_permission_ticket[Permission Ticket] is a special security token type representing a permission request. Accordingly with UMA specification, a permission ticket is:
A link:../../overview/terminology.adoc#_permission_ticket[Permission Ticket] is a special security token type representing a permission request. Per the UMA specification, a permission ticket is:
`A correlation handle that is conveyed from an authorization server to a resource server, from a resource server to a client, and ultimately from a client back to an authorization server, to enable the authorization server to assess the correct policies to apply to a request for authorization data.`
[NOTE]
_Permission ticket support is limited_.
When using UMA protocol, resource servers can register permission requests in the server in order to support authorization flows where a resource owner (the user that owns a resource being requested) can
approve access to his resources by third parties and do a lot of other stuff. This represents one of the main features of UMA specification, where resource owners can control their own resources
and the policies that govern them. Right now, our UMA implementation is very limited at this regard. We don't store permission tickets on the server and we are basically using UMA to provide API security and base our authorization offerings.
This situation should be temporary and in the future we plan to fully support UMA and cover other use cases.
In the full UMA protocol, resource servers can register permission requests in the server to support authorization flows where a resource owner (the user that owns a resource being requested) can
approve access to his resources by third parties among other things. This represents one of the main features of the UMA specification -- where resource owners can control their own resources
and the policies that govern them. Right now, the UMA implementation support is very limited in this regard. For example, the system doesn't store permission tickets on the server and we are basically using UMA to provide API security and base our authorization offerings.
This situation should be temporary. In the future, we plan to fully support UMA and cover other use cases.
In most cases, you won't need to deal with this endpoint directly. {{book.project.name}} provides a link:../enforcer/overview.html[Policy Enforcer] that enables UMA to your
resource server in order to obtain a permission ticket from the authorization server, return this ticket to client application and enforce authorization decisions based on a final RPT.
In most cases, you won't need to deal with this endpoint directly. {{book.project.name}} provides a link:../enforcer/overview.html[Policy Enforcer] that enables UMA for your
resource server so it can obtain a permission ticket from the authorization server, return this ticket to client application, and enforce authorization decisions based on a final requesting party token (RPT).

8
topics/service/protection/protection-api.adoc
View file

@ -4,11 +4,11 @@ The Protection API provides a UMA-compliant set of endpoints providing:
* *Resource Registration*
+
From this endpoint resource servers can manage their resources remotely and enable link::../../../../enforcer/overview.adoc[Policy Enforcers] to query the server for the resources that need protection.
With this endpoint, resource servers can manage their resources remotely and enable link::../../../../enforcer/overview.adoc[Policy Enforcers] to query the server for the resources that need protection.
* *Permission Registation*
* *Permission Registration*
+
When using UMA protocol, resource servers can access this endpoint to issue permission tickets.
In the UMA protocol, resource servers access this endpoint which issues permission tickets.
An important requirement for this API is that _only_ resource servers are supposed to access its endpoints using a special OAuth2 access token called *Protection API Token* or *PAT*.
An important requirement for this API is that _only_ resource servers are allowed to access its endpoints using a special OAuth2 access token called *Protection API Token* or *PAT*.
In UMA, a PAT is just a token with a scope *uma_protection*.

4
topics/service/protection/resources-api-papi.adoc
View file

@ -6,7 +6,7 @@ Resource servers can manage their resources remotely using a UMA-compliant endpo
http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set
```
This endpoint provides some registration operations as follows:
This endpoint provides registration operations outlined as follows (entire path omitted for clarity):
* Create resource set description: POST /resource_set
* Read resource set description: GET /resource_set/{_id}
@ -15,4 +15,4 @@ This endpoint provides some registration operations as follows:
* List resource set descriptions: GET /resource_set
* List resource set descriptions using a filter: GET /resource_set?filter=${filter}
For more details about the contract for each of these operations, please take a look at https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html[UMA Resource Set Registration].
For more details about the contract for each of these operations, please refer to https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html[UMA Resource Set Registration].

20
topics/service/protection/token-introspection.adoc
View file

@ -5,12 +5,12 @@ to enforce authorization decisions at the resource server side.
There are two main use cases where token introspection may help you:
* When clients applications need to check the token validity in order to obtain a new one with the same or even additional permissions
* When enforcing authorization decisions at the resource server side, specially when none of the built-in link:../../enforcer/overview.html[Policy Enforcers] fits to your application
* When client applications need to check the token validity in order to obtain a new one with the same or even additional permissions
* When enforcing authorization decisions at the resource server side, especially when none of the built-in link:../../enforcer/overview.html[Policy Enforcers] fits your application
=== Obtaining information about a RPT
=== Obtaining Information about a RPT
The token introspection is basically a https://tools.ietf.org/html/rfc7662[OAuth2 Token Introspection] compliant endpoint from where you can obtain information about a RPT.
The token introspection is essentially a https://tools.ietf.org/html/rfc7662[OAuth2 Token Introspection]-compliant endpoint from which you can obtain information about a RPT.
```bash
http://${host}:${port}/auth/realms/${realm_name}/protocol/openid-connect/token/introspect
@ -34,11 +34,11 @@ The introspection endpoint expects two parameters:
* *token_type_hint*
+
Use *requesting_party_token* as the value for this parameter. It indicates that you want to introspect a RPT
Use *requesting_party_token* as the value for this parameter. It indicates that you want to introspect a RPT.
+
* *token*
+
Use the token string, just like it was returned by the server during the authorization process, as the value for this parameter
Use the token string, just as it was returned by the server during the authorization process, as the value for this parameter.
As a result, the server should respond as follows:
@ -58,7 +58,7 @@ As a result, the server should respond as follows:
}
```
In case the RPT is not active, you should get this response instead:
If the RPT is not active, you will get this response instead:
```json
{
@ -66,15 +66,15 @@ In case the RPT is not active, you should get this response instead:
}
```
=== Do I Need to Invoke the Server Every Time I want to Introspect a RPT ?
=== Do I Need to Invoke the Server Every Time I want to Introspect a RPT?
Not really. Both link:../../service/authorization/authorization-api.html[Authorization] and link:../../service/entitlement/entitlement-api.html[Entitlement] APIs use the
https://tools.ietf.org/html/rfc7519[JSON Web Token (JWT)] specification as the default format for RPTs.
In case you want to validate these tokens without a remote call to the introspection endpoint you can decode the RPT and check for its validity locally. Once you decode the token,
If you want to validate these tokens without a call to the remote introspection endpoint, you can decode the RPT and check for its validity locally. Once you decode the token,
you can also use the permissions within the token to enforce authorization decisions.
This is pretty much what the link:../../enforcer/overview.html[Policy Enforcers] do, just make sure to:
This is essentially what the link:../../enforcer/overview.html[Policy Enforcers] do, just be sure to:
* Validate RPT's signature (based on realm's public key)
* Check for token validity based on its _exp_, _iat_ and _aud_ claims

16
topics/service/protection/whatis-obtain-pat.adoc
View file

@ -1,12 +1,12 @@
== What is a PAT and How to Obtain it ?
== What is a PAT and How to Obtain It?
A PAT is a special OAuth2 Access Token with the scope *uma_protection*. When you create a resource server, {{book.project.name}} automatically
creates a role _uma_protection_ for the corresponding client application and associated it with the client's service account.
A *Protection API Token* (PAT) is a special OAuth2 Access Token with a scope defined as *uma_protection*. When you create a resource server, {{book.project.name}} automatically
creates a role _uma_protection_ for the corresponding client application and associates it with the client's service account.
.Service Account granted with uma_protection role
.Service Account granted with *uma_protection* role
image:../../../images/service/rs-uma-protection-role.png[alt="Service Account granted with uma_protection role"]
Resource servers can obtain a PAT from {{book.project.name}} just like any other OAuth2 Access Token.
Resource servers can obtain a PAT from {{book.project.name}} just like any other OAuth2 Access Token. For example, using curl:
```bash
curl -X POST \
@ -16,11 +16,11 @@ curl -X POST \
"http://localhost:8080/auth/realms/${realm_name}/protocol/openid-connect/token"
```
In the example above, we are using the *client_credentials* grant type to obtain a PAT from the server. As a result, the server would return a response as follows:
The example above is using the *client_credentials* grant type to obtain a PAT from the server. As a result, the server would return a response similar to the following:
[NOTE]
{{book.project.name}} can authenticate your client application in different ways. We are using *client_credentials* grant type for the sake of
simplicity, which basically requires a _client_id_ and a _client_secret_. You can choose any other supported authentication method.
{{book.project.name}} can authenticate your client application in different ways. We are using *client_credentials* grant type for the sake of simplicity,
which basically requires a _client_id_ and a _client_secret_. You can choose any other supported authentication method.
```bash
{