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

Merge pull request #7 from pedroigor/master

Browse source 
More doc
This commit is contained in:
Pedro Igor 2016-06-05 19:18:00 -03:00
commit 59341c6b32
49 changed files with 1314 additions and 307 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
SUMMARY.adoc
View file

@ -9,29 +9,39 @@
. link:topics/resource-server/overview.adoc[Managing Resource Servers]
.. link:topics/resource-server/view.adoc[Viewing Resource Servers]
.. link:topics/resource-server/create.adoc[Creating Resource Servers]
... link:topics/resource-server/uma-protection-scope.adoc[Defining uma_protection scope]
... link:topics/resource-server/uma-authz-entitlement-scope.adoc[Defining uma_authorization and kc_entitlement scopes]
.. link:topics/resource-server/policy-enforcement-mode.adoc[Policy Enforcement Modes]
.. link:topics/resource-server/configuring-entitlements.adoc[Configuring Entitlements]
.. link:topics/resource-server/import-export-configuration.adoc[Import/Export Authorization Configuration]
. link:topics/resource/overview.adoc[Managing Resources and Scopes]
.. link:topics/resource-server/defining-authz-scopes.adoc[Defining the AuthZ Services Scopes]
.. link:topics/resource-server/export-configuration.adoc[Exporting Resource Server Configuration]
. link:topics/resource/overview.adoc[Managing Resources]
.. link:topics/resource/view.adoc[Viewing Resources]
.. link:topics/resource/create.adoc[Creating Resources]
. link:topics/permission/overview.adoc[Managing Permissions]
.. link:topics/permission/view.adoc[Viewing Permissions]
.. link:topics/permission/create-resource.adoc[Creating Resource-based Permissions]
.. link:topics/permission/create-scope.adoc[Creating Scope-based Permissions]
.. link:topics/permission/policy-decision-strategy.adoc[Policy Decision Strategies]
. link:topics/policy/overview.adoc[Managing Policies]
.. link:topics/policy/view.adoc[Viewing Policies]
.. link:topics/policy/user-policy.adoc[User-Based Policy]
.. link:topics/policy/role-policy.adoc[Role-Based Policy]
.. link:topics/policy/js-policy.adoc[JavaScript-Based Policy]
.. link:topics/policy/drools-policy.adoc[Drools-Based Policy]
.. link:topics/policy/time-policy.adoc[Time-Based Policy]
.. link:topics/policy/aggregated-policy.adoc[Aggregated Policy]
.. link:topics/policy/logic.adoc[Positive and Negative Logic]
.. link:topics/policy/evaluation-api.adoc[Policy Evaluation API]
. link:topics/policy-evaluation-tool/overview.adoc[Evaluating and Testing Policies]
. link:topics/service/overview.adoc[Authorization Services]
.. link:topics/service/protection-api.adoc[The Protection API]
.. link:topics/service/authorization-api.adoc[The Authorization API]
.. link:topics/service/entitlement-api.adoc[The Entitlement API]
.. link:topics/service/protection-api.adoc[Protection API]
... link:topics/service/whatis-obtain-pat.adoc[What is a PAT and How to Obtain It]
... link:topics/service/resources-api-papi.adoc[Managing Resources]
... link:topics/service/permission-api-papi.adoc[Managing Permission Requests]
.. link:topics/service/authorization-api.adoc[Authorization API]
... link:topics/service/whatis-obtain-aat.adoc[What is a AAT and How to Obtain It]
... link:topics/service/authorization-api-aapi.adoc[Requesting Authorization Data and Token]
.. link:topics/service/entitlement-api.adoc[Entitlement API]
... link:topics/service/whatis-obtain-eat.adoc[What is a EAT and How to Obtain It]
... link:topics/service/entitlement-api-aapi.adoc[Requesting Entitlements]
.. link:topics/service/client-api.adoc[Authorization Client Java API]
. link:topics/enforcer/overview.adoc[Policy Enforcers]
.. link:topics/enforcer/jaxrs-enforcer.adoc[JAX-RS Policy Enforcer]
.. link:topics/enforcer/servlet-enforcer.adoc[Servlet Policy Enforcer]
.. link:topics/enforcer/client-api.adoc[Using the Authorization Client API]
.. link:topics/enforcer/keycloak-enforcement-filter.adoc[Keycloak Servlet Policy Enforcer]
.. link:topics/enforcer/bearer-enforcement-filter.adoc[Bearer Token Servlet Policy Enforcer]
. link:topics/example/overview.adoc[Examples]

BIN
images/policy-evaluation-tool.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 92 KiB

154
topics/enforcer/bearer-enforcement-filter.adoc Executable file
View file

@ -0,0 +1,154 @@
== Bearer Token Enforcement Filter
The *org.keycloak.authorization.policy.enforcer.servlet.BearerTokenEnforcementFilter* can be used to protect servlet applications providing
RESTful services. For instance, applications using JAX-RS.
This filter does not require that your application is configured with any {{book.project.name}} OIDC Adapter.
To configure it, change your web application descriptor (WEB-INF/web.xml) as follows:
```xml
<filter>
<filter-name>Keycloak Authorization Enforcer</filter-name>
<filter-class>org.keycloak.authorization.policy.enforcer.servlet.BearerTokenEnforcementFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Keycloak Authorization Enforcer</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
```
=== Configuration
The BearerTokenEnforcementFilter can be configured by a simple JSON file. The file can be as simple as:
```json
{
"client": {
"configurationUrl": "http://localhost:8080/auth/realms/{realm_name}/authz/uma_configuration",
"clientId": "{client_id}",
"clientSecret": "{client_secret}"
},
"enforcer": {}
}
```
Or a little more verbose if you want to manually define the resources being protected:
```json
{
"client": {
"configurationUrl": "http://localhost:8080/auth/realms/{realm_name}/authz/uma_configuration",
"clientId": "{client_id}",
"clientSecret": "{client_secret}"
},
"enforcer": {
"paths": [
{
"path" : "/someUri/*",
"methods" : [
{
"method": "GET",
"scopes" : ["urn:app.com:scopes:view"]
},
{
"method": "POST",
"scopes" : ["urn:app.com:scopes:create"]
}
]
},
{
"name" : "Some Resource",
"path" : "/usingPattern/{id}",
"methods" : [
{
"method": "DELETE",
"scopes" : ["urn:app.com:scopes:delete"]
}
]
},
{
"path" : "/exactMatch"
},
{
"name" : "Admin Resources",
"path" : "/usingWildCards/*"
}
]
}
}
```
The file with the enforcer configuration must be under your application's classpath as *keycloak-authz.json".
Here is a description of each configuration option:
* *client*
+
Specify the information about the resource server being protected
+
** *configurationUrl*
+
A URL pointing to a configuration endpoint. This is important for the automatic discovery of the services invoked during the authorization process.
+
** *clientId*
+
The id of the client acting as a resource server.
+
** *clientSecret*
+
The client secret.
+
* *enforcer*
+
Specify the configuration options to define how policies are actually enforced and optionally the paths you want to protect. If empty, the policy enforcer will query the server
for all resources associated with the resource server being protected. In this case, you need to make sure the resources are properly configured with a *uri* property that matches the paths
you want to protect.
+
** *paths*
+
Specify the paths to protect.
+
*** *name*
+
The name of a resource in the server that must be associated with a given path. If provided, the policy enforcer will ignore the resource's *uri* property and use the path you provided.
*** *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.
Right now, we support some very basic logic for path matching. Examples of valid paths are:
+
**** Wildcards: `/*`
**** Suffix: `/*.html`
**** Sub-paths: `/path/*`
**** Path parameters: /resource/{id}
**** Exact match: /resource
+
*** *methods*
The HTTP methods to protect and how they are associated with the scopes for a given resource in the server.
+
**** *method*
+
The name of the HTTP method.
+
**** *scopes*
+
An array of strings with the scopes associated with the method.
=== Container Specific Configuration
==== WildFly 10.0.0.Final
In order to make the filter available to your application at runtime, you must create a *META-INF/jboss-deployment-structure.xml* at the application root directory.
```xml
<jboss-deployment-structure>
<deployment>
<dependencies>
<module name="org.keycloak.keycloak-authz-servlet-enforcer" services="import"/>
<module name="org.jboss.resteasy.resteasy-jackson2-provider" services="import"/>
</dependencies>
<exclusions>
<module name="org.jboss.resteasy.resteasy-jackson-provider"/>
</exclusions>
</deployment>
</jboss-deployment-structure>

1
topics/enforcer/client-api.adoc
View file

@ -1 +0,0 @@
== Authorization Client API

156
topics/enforcer/keycloak-enforcement-filter.adoc Executable file
View file

@ -0,0 +1,156 @@
== Keycloak Adapter Enforcement Filter
The *org.keycloak.authorization.policy.enforcer.servlet.KeycloakAdapterEnforcementFilter* can be used to protect applications
using the {{book.project.name}} OpenID Connect Adapters.
[NOTE]
Before configuring this filter, make sure your application is properly configure to authenticate against a {{book.project.name}} Server. To use this filter,
you need the Keycloak OIDC Adapter properly configured and authenticating your users.
To configure it, change your web application descriptor (WEB-INF/web.xml) as follows:
```xml
<filter>
<filter-name>Keycloak Authorization Enforcer</filter-name>
<filter-class>org.keycloak.authorization.policy.enforcer.servlet.KeycloakAdapterEnforcementFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Keycloak Authorization Enforcer</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
```
=== Configuration
The _KeycloakAdapterEnforcementFilter_ can be configured by a simple JSON file. The file can be as simple as:
```json
{
"client": {
"configurationUrl": "http://localhost:8080/auth/realms/{realm_name}/authz/uma_configuration",
"clientId": "{client_id}",
"clientSecret": "{client_secret}"
},
"enforcer": {}
}
```
Or a little more verbose if you want to manually define the resources being protected:
```json
{
"client": {
"configurationUrl": "http://localhost:8080/auth/realms/{realm_name}/authz/uma_configuration",
"clientId": "{client_id}",
"clientSecret": "{client_secret}"
},
"enforcer": {
"paths": [
{
"path" : "/someUri/*",
"methods" : [
{
"method": "GET",
"scopes" : ["urn:app.com:scopes:view"]
},
{
"method": "POST",
"scopes" : ["urn:app.com:scopes:create"]
}
]
},
{
"name" : "Some Resource",
"path" : "/usingPattern/{id}",
"methods" : [
{
"method": "DELETE",
"scopes" : ["urn:app.com:scopes:delete"]
}
]
},
{
"path" : "/exactMatch"
},
{
"name" : "Admin Resources",
"path" : "/usingWildCards/*"
}
]
}
}
```
The file with the enforcer configuration must be under your application's classpath as *keycloak-authz.json".
Here is a description of each configuration option:
* *client*
+
Specify the information about the resource server being protected
+
** *configurationUrl*
+
A URL pointing to a configuration endpoint. This is important for the automatic discovery of the services invoked during the authorization process.
+
** *clientId*
+
The id of the client acting as a resource server.
+
** *clientSecret*
+
The client secret.
+
* *enforcer*
+
Specify the configuration options to define how policies are actually enforced and optionally the paths you want to protect. If empty, the policy enforcer will query the server
for all resources associated with the resource server being protected. In this case, you need to make sure the resources are properly configured with a *uri* property that matches the paths
you want to protect.
+
** *paths*
+
Specify the paths to protect.
+
*** *name*
+
The name of a resource in the server that must be associated with a given path. If provided, the policy enforcer will ignore the resource's *uri* property and use the path you provided.
*** *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.
Right now, we support some very basic logic for path matching. Examples of valid paths are:
+
**** Wildcards: `/*`
**** Suffix: `/*.html`
**** Sub-paths: `/path/*`
**** Path parameters: /resource/{id}
**** Exact match: /resource
+
*** *methods*
The HTTP methods to protect and how they are associated with the scopes for a given resource in the server.
+
**** *method*
+
The name of the HTTP method.
+
**** *scopes*
+
An array of strings with the scopes associated with the method.
=== Container Specific Configuration
==== WildFly 10.0.0.Final
In order to make the filter available to your application at runtime, you must create a *META-INF/jboss-deployment-structure.xml* at the application root directory.
```xml
<jboss-deployment-structure>
<deployment>
<dependencies>
<module name="org.keycloak.keycloak-authz-servlet-enforcer" services="import"/>
<module name="org.jboss.resteasy.resteasy-jackson2-provider" services="import"/>
</dependencies>
<exclusions>
<module name="org.jboss.resteasy.resteasy-jackson-provider"/>
</exclusions>
</deployment>
</jboss-deployment-structure>

5
topics/enforcer/overview.adoc
View file

@ -5,3 +5,8 @@ to implement PEPs for different platforms, environments and using different prog
fully RESTFUL-based, leveraging OAuth2 authorization capabilities to also support fine-grained authorization using a centralized authorization server.
image:../../images/pep-pattern-diagram.png[alt="PEP Overview"]
=== Download and Installation
The avaliable policy enforcers are distributed just like any other {{book.project.name}} Adapter. Please check this https://keycloak.gitbooks.io/securing-client-applications-guide/content/[documentation]
for more details about how to obtain and install these adapters accordingly with the platform you are using.

39
topics/enforcer/servlet-enforcer.adoc
View file

@ -1 +1,38 @@
== Servlet Policy Enforcer
== Servlet Enforcement Filter
The _Servlet Enforcement Filter_ implements a PEP that can be used to secure applications using the Servlet API. The are available
just like any other Keycloak OpenID Connect Adapter.
=== Keycloak Adapter Enforcement Filter
The *org.keycloak.authorization.policy.enforcer.servlet.KeycloakAdapterEnforcementFilter* can be used to protect applications
using the {{book.project.name}} OpenID Connect Adapters.
To configure it, change your web application descriptor (WEB-INF/web.xml) as follows:
```xml
<filter>
<filter-name>Keycloak Authorization Enforcer</filter-name>
<filter-class>org.keycloak.authorization.policy.enforcer.servlet.KeycloakAdapterEnforcementFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Keycloak Authorization Enforcer</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
```
In order to make it available to your application at runtime, you must create a *META-INF/jboss-deployment-structure.xml* at the application root directory. If you are using maven, this file can be placed under *src/main/webapp/META-INF/jboss-deployment-structure.xml*:
```xml
<jboss-deployment-structure>
<deployment>
<dependencies>
<module name="org.keycloak.keycloak-authz-servlet-enforcer" services="import"/>
<module name="org.jboss.resteasy.resteasy-jackson2-provider" services="import"/>
</dependencies>
<exclusions>
<module name="org.jboss.resteasy.resteasy-jackson-provider"/>
</exclusions>
</deployment>
</jboss-deployment-structure>

2
topics/getting-started/getting-started.adoc
View file

@ -12,3 +12,5 @@ Make sure you have a {{book.project.name}} instance up and running on http://loc
_Administration Console_ and get a page like that:
image:../../images/gs-keycloak-console-page.png[alt="Keycloak Administration Console"]
Source code for all examples can be obtained from *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/*.

20
topics/getting-started/hello-world-servlet-authz.adoc
View file

@ -19,7 +19,7 @@ The application we are about to create is a very simple. In a nutshell, it imple
* An _Administration Area_ that only administrators can access
* An _User Premium Area_ that only users with a premium plan can access
* A dynamic menu that is generated accordingly with the permissions issued by a {{book.project.name}} Server to an authenticated user
* A dynamic menu that is generated depending on the permissions granted an user
image:../../images/servlet-authz-app-structure.png[alt="Servlet Authz Application Structure"]
@ -318,14 +318,14 @@ The resource server configuration tells a lot about what we are really protectin
Fist of all, we define four resources:
* Admin Resource
* Protected Resource
* Premium Resource
* Main Page
* *Admin Resource*
* *Protected Resource*
* *Premium Resource*
* *Main Page*
As the name implies, each of these resources are related with the requirements we previously discussed, representing the different areas or group of resources we want to protect.
As you may notice, each of these resources (except Main Page) defines an *uri* property. This property represents the path we want to protect and they map directly, or indirectly by using a pattern,
As you may notice, each of these resources (except Main Page) defines an *uri* property. This property represents the path we want to protect and maps directly, or indirectly by using a pattern,
to the resources served by the application.
Let's take the _Protected Resource_ as an example:
@ -385,7 +385,7 @@ Aggregated policies are very useful in order to group related policies together
=== Configuring the Keycloak Enforcement Filter
Now that we have all the configuration for our resource server in place, we can configure the authorization enforcement filter to actually protected the resources.
Now that we have all the configuration for our resource server in place, we can configure the authorization enforcement filter to actually protect resources.
Just like any other Servlet Filter, you just need to include the following configuration in your web application descriptor (WEB-INF/web.xml):
@ -417,7 +417,7 @@ your application at runtime, you must create a *META-INF/jboss-deployment-struct
</jboss-deployment-structure>
```
For last, you need to create a *META-INF/keycloak-authz.json*. If you are using Maven, this file goes inside *src/main/resources*:
For last, you need to create a *META-INF/keycloak-authz.json* and put it in your application's classpath. If you are using Maven, this file goes inside *src/main/resources*:
```json
{
@ -432,7 +432,7 @@ For last, you need to create a *META-INF/keycloak-authz.json*. If you are using
=== Running and Using the Application
All the source code for this application is at *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/servlet-authz/*.
All the source code for this application is located at *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/servlet-authz/*.
There you can execute the following command to _deploy_ the application to the running server:
@ -443,8 +443,6 @@ That should be enough to get the application properly packaged and deployed to a
If the application was properly deployed, you can try to access it at http://localhost:8080/auth[http://localhost:8080/servlet-authz-app] and use the following credentials to login into the application:
If everything is correct, you will be redirect to Keycloak login page. You can login to the application with the following credentials:
* username: alice / password: alice (regular user)
* username: jdoe / password: jdoe (premium user)
* username: admin / password: admin (administrator)

17
topics/getting-started/hello-world.adoc
View file

@ -66,7 +66,7 @@ For this guide, we are going to create a *hello-world-authz* realm. Just import
"clients" : [
{
"clientId" : "hello-world-authz-service",
"secret" : "password",
"secret" : "secret",
"serviceAccountsEnabled" : true,
"enabled" : true,
"redirectUris" : [ "http://localhost:8080/hello-world-authz-service" ],
@ -178,7 +178,7 @@ The resource server was created based on the *hello-world-authz-service* client
```
What we did was basically tell {{book.project.name}} that we want that client application acting as a resource server, so we can start creating the resources we want to protect as well the permissions
and authorization policies we want to use to actually protect the resources.
and authorization policies we want to use to actually protect its resources.
The purpose of this guide is keep things simple to get you started, so our newly created resource server has a single protected resource, as defined by the following configuration:
@ -202,7 +202,7 @@ permission is the link between a resource and the policies(or conditions) we wan
In this example, we have a single policy *Only Special Users Policy*. This policy tells that only the specified users are allowed to access _something_ (we don't know what, yet. That is up to the permission).
[NOTE]
{{book.project.name}} provides a few link:../policy/overview.html[policy types] that you can start using out-of-the-box. There are policies for RBAC, time constraints or even rules written using JavaScript or JBoss Drools.
{{book.project.name}} provides a few link:../policy/overview.html[policy types] that you can start using out-of-the-box. There are policies for ABAC, RBAC, time constraints or even rules written using JavaScript or JBoss Drools.
The last step when protecting a resource is to define a permission. For that, we have defined a *Hello World Resource Permission* that links the resource we want to protect, _Hello World Resource_, with the
policy we want to apply to that resource, _Only Special Users Policy_.
@ -227,10 +227,7 @@ to an user as a result of the evaluation of the permissions and authorization po
Now that the *hello-world-authz* realm is properly configured with the resources we want to protected and their corresponding permissions and authorization policies, we can ask the server for what an user
is entitled to do. In other words, what are the permissions the user has.
The Entitlement API consists of a single endpoint. This endpoint expects an OAuth2 Access Token with a scope *kc_entitlement* representing the user identity and the identifier of the resource server we want to access. The *kc_entitlement*
scope is necessary to indicate that the user consented access to his authorization data from a given client application. The access token with a scope *kc_entitlement* is called *Entitlement API Token* or *EAT*.
In this case, for the sake of simplicity, our resource server *hello-world-authz-service* is also acting as a client application. What means that the user allowed this application to access his
In this case, for the sake of simplicity, our resource server *hello-world-authz-service* is also acting as a client application. Which means that the user allowed this application to access his
authorization data and obtain RPTs on his behalf.
The first step is obtain a EAT as follows:
@ -261,7 +258,7 @@ would get a response from the server as follows:
[NOTE]
Resource Owner Password Credentials Grant Type is only used here for demonstration purposes. In the real world, you'll usually obtain an access token using a more secure grant type such as _authorization_code_.
The idea here is demonstrate that you need to obtain an access token with the scope *kc_entitlement* prior to access the Entitlement API to ask for a RPT.
The idea here is demonstrate that you need to obtain an access token with the scope *kc_entitlement* prior to access the Entitlement API and ask for a RPT.
Finally, the last step is obtain a RPT from the Entitlement API as follows:
@ -316,7 +313,7 @@ Just like we did with _alice_, the server will return an EAT that we can use to
```
The reason for that is that the _Hello World Resource_ is protected by a _Only Special Users Policy_ that says that only _alice_ is allowed to access the resource. You can play around now by changing that policy to
include _jdoe_ as a valid user and see the results.
include _jdoe_ as a valid user and see the results, or you can create new policies and change the permission to use them.
== Enforcing Authorization Decisions
@ -344,7 +341,7 @@ When you decode a RPT you will see something like that:
}
```
The *permissions* claim lists all resource (and their respective scopes if any) permissions granted by the server. There is also a *accessToken* property holding the EAT that was used to issue the RPT.
The *permissions* claim consists of all the permissions granted by the server. There is also a *accessToken* property holding the EAT that was used to issue the RPT.
The RPT provides everything you need to enforce authorization decisions at the resource server side. That can be easily accomplished by:

56
topics/overview/architecture.adoc
View file

@ -28,10 +28,13 @@ Being based on {{book.project.name}} Authentication Server, you can obtain attri
=== The Authorization Process
Two main process define the necessary steps to understand how to use KC to enable fine-grained authorization to your applications:
Two main processes define the necessary steps to understand how to use KC to enable fine-grained authorization to your applications:
* *Resource Management*
* *Permission and Policy Management*
* *Policy Enforcement*
==== Resource Management
*Resource Management* involves all the necessary steps to define what is being protected.
@ -40,37 +43,48 @@ image:../../images/resource-mgmt-process.png[alt="Resource Management Overview"]
First, you need to tell to {{book.project.name}} what are you looking to protect, which usually represents a web application or a set of one or more services. See link:../overview/terminology.html[Terminology] for more information about
Resource Servers.
Resource Servers are managed using the {{book.project.name}} Administration Console, where you can enable any registered client application as a resource server and start managing the resources and scopes you want to protect.
Resource Servers are managed using the {{book.project.name}} Administration Console. There you can enable any registered client application as a resource server and start managing the resources and scopes you want to protect.
image:../../images/rs-r-scopes.png[alt="Resource Server Overview"]
A Resource can be a web page, a RESTFul resource, a file in your filesystem, an EJB, etc. They can represent a group of resources (just like a Class in Java) or they can represent a single and specific resource.
For instance, you may have a _Bank Account_ resource that represents all banking accounts define authorization policies that apply to all banking accounts. However
you may want to define specific policies for _Alice Account_, where only the owner is allowed to access some information or perform an operation.
For instance, you may have a _Bank Account_ resource that represents all banking accounts and use it to define the authorization policies that are common to all banking accounts. However,
you may want to define specific policies for _Alice Account_ (a resource instance that belongs to a customer), where only the owner is allowed to access some information or perform an operation.
Resources can be managed using {{book.project.name}} Administration Console or the link:../service/protection-api.html[Protection API]. In the latter case, resource servers are able to
manage their resources remotely.
Scopes usually represent the actions that can be performed on a resource, but they are not limited to that. You can also use scopes to represent a single or multiple attributes belonging to a resource.
Once you have your resource server and all the resources you want to protect configured, you can start working with the fun part: *Permission and Policy Management*.
==== Permission and Policy Management
*Permission and Policy Management* involves all the necessary steps to actually define the security and access requirements that govern your resources.
Once you have defined your resource server and all the resources you want to protect, you can start working with the fun part: *Permission and Policy Management*.
This process involves all the necessary steps to actually define the security and access requirements that govern your resources.
image:../../images/policy-mgmt-process.png[alt="Permission and Policy Management Overview"]
Policies define the conditions that must be satisfied to access or perform operations on something (resource or scope), but they are not tied with what they are protecting. They are generic and can be reused
to build permissions or even other more complex policies.
to build permissions or even more complex policies.
For instance, we may want to allow access to a group of resources only for users granted with a role "User Premium". In this case, we define a simple policy, based on Role-based Access Control (RBAC), that
tells exactly that.
For instance, we may want to allow access to a group of resources only for users granted with a role "User Premium". For that, we can just define a simple RBAC (Role-based Access Control).
{{book.project.name}} provides a few built-in policies covering the most common access control mechanisms. You can even create policies based on rules written using JavaScript or JBoss Drools.
{{book.project.name}} provides a few built-in policy types(and their respective policy providers) covering the most common access control mechanisms. You can even create policies based on rules written using JavaScript or JBoss Drools.
Once you have your policies defined, you can start defining your permissions. Differently than policies, permissions are tied coupled with the resource they are protecting. Here you specify
what you want to protect (resource or scope) and the policies that must be satisfied in order to _GRANT_ or _DENY_ that permission to someone asking for it.
==== Policy Enforcement
*Policy Enforcement* involves the necessary steps to actually enforce authorization decisions to a resource server. This is achieved by enabling a *Policy Enforcement Point* or PEP at the
resource server that is capable of communication with the authorization server, ask for authorization data and control access to protected resources based on the decisions and permissions returned
by the server.
image:../../images/pep-pattern-diagram.png[alt="PEP Overview"]
{{book.project.name}} provides some built-in link:../enforcer/overview.html[Policy Enforcers] implementations that you can use to protect your applications depending on the platform they are running on.
=== Authorization Services
@ -80,7 +94,7 @@ Authorization Services consist of the following RESTFul APIs:
* *Authorization API*
* *Entitlement API*
Each of these services provide a specific API covering the different steps involved in the process of authorization.
Each of these services provide a specific API covering the different steps involved in the authorization process.
==== Protection API
@ -90,19 +104,19 @@ for resource servers in order help them managing their resources and scopes. Onl
The operations provided by the Protection API can be organized in two main groups:
* Resource Management
* *Resource Management*
** Create Resource
** Delete Resource
** Find by Id
** Find All
** Find with filters (eg.: search by name, type or URI)
* Permission Management
* *Permission Management*
** Issue Permission Tickets
[NOTE]
By default, Remote Resource Management is enabled. But you can also disable that from the administration console.
By default, Remote Resource Management is enabled. You can change that using the {{book.project.name}} Administration Console and only allow resource management through the console.
The issuance of Permission Tickets by the Protection API is an important part of the whole authorization process. As we'll see later, they represent the permissions
When using the UMA protocol, the issuance of Permission Tickets by the Protection API is an important part of the whole authorization process. As we'll see later, they represent the permissions
being requested by client and that are sent to the server in order to obtain a final token with all permissions granted during the evaluation of the permissions and policies
associated with the resources and scopes being requested.
@ -111,12 +125,12 @@ For more information, see link:../service/protection-api.html[Protection API].
==== Authorization API
The *Authorization API* is also a https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA-compliant] endpoint providing a single operation that exchanges an ID Token and _Permission Ticket_
with a Requesting Party Token or RPT.
with a *Requesting Party Token* or *RPT*.
The RPT holds all permissions granted to a client and can be used to call a resource server in order to get access to its protected resources.
When asking a RPT you can also provide a previously issued RPT. In this case, the resulting RPT will consist of a union of the permissions from the previously RPT and the new ones
within a Permission Ticket.
When asking a RPT you can also provide a previously issued RPT. In this case, the resulting RPT will consist of the union of the permissions from the previously RPT and the new ones
within a permission ticket.
image:../../images/authz-calls.png[alt="Authorization API Overview"]
@ -124,8 +138,10 @@ For more information, see link:../service/authorization-api.html[Authorization A
=== Entitlement API
The *Entitlement API* provides a 1-legged protocol to issue RPTs. Differently than the_Authorization API, the Entitlement API only expects an ID Token and the resulting RPT
consists of all permissions granted based on all resources belonging to a resource server.
The *Entitlement API* provides a 1-legged protocol to issue RPTs. Unlink the_Authorization API, the Entitlement API only expects an ID Token.
From this API you can obtain all the entitlements or permissions for an user (based on the resources managed by a given resource server) or just the entitlements for a set of
one or more resources.
image:../../images/entitlement-calls.png[alt="Entitlement API Overview"]

9
topics/overview/overview.adoc
View file

@ -17,10 +17,11 @@ for your protected resources and scopes, associate these permissions with author
decisions in your application and services.
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, Keycloak Authorization Services can be used as great tool to:
using different devices and with a high demand for information sharing, Keycloak Authorization Services provides:
* Control your protected resources and the actions that can be performed on them with fine-grained authorization policies
* 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
* Avoid code replication across projects (and redeploys) and quickly adapt to changes in your requirements
* Auditing
* The necessary means to avoid code replication across projects(and redeploys) and quickly adapt to changes in your security requirements

22
topics/overview/terminology.adoc
View file

@ -1,11 +1,10 @@
== Terminology
Before going further, it is important to understand some terms and concepts introduced with {{book.project.name}} {{book.project.module}}.
Before going further, it is important to understand some terms and concepts introduced by {{book.project.name}} {{book.project.module}}.
==== Resource Server
If you are familiar with OAuth2, a Resource Server is the server hosting the protected resources, capable of accepting
and responding to protected resource requests.
If you are familiar with OAuth2, a Resource Server is the server hosting the protected resources, and which is 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
@ -16,8 +15,7 @@ protected and ruled by a set of authorization policies.
==== Resource
A resource is part of the assets of an application and the organization. It may be a single API
endpoint, a set of API endpoints, a classic web resource such as an HTML page, and so on.
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
@ -42,8 +40,22 @@ A single scope may be associated with zero or more resources.
==== Permission
Consider this simple and very common permission:
* *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.
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:
* Reduce code refactoring and permission management costs
* Support a more flexible security model where you can easily change
* Make changes at runtime given that applications only care about the resources and scopes being protect 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

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

@ -1,3 +1,34 @@
== Creating Resource-based Permissions
You can create permissions by selecting which type of permission you want to create: resource or scope.
A Resource-based permissions 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. In {{book.project.name}}, a resource-based permissions consist of the following information:
* *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
+
* *Description*
+
A string with more details about this policy
+
* *Apply To Resource Type*
+
Specifies if this permission would be applied to all resources with a given type. When you select this field, you'll be prompted to enter the resource type to protect.
+
** Resource Type
+
Defines the resource type to protect. When defined, this permissions is going to be evaluated for all resources matching the type
+
* *Resources*
+
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
* *Decision Strategy*
+
The decision strategy for this permission

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

@ -1,3 +1,32 @@
== Creating Scope-based Permissions
== Creating Resource-based Permissions
You can create permissions by selecting which type of permission you want to create: resource or scope.
A Scope-based permissions defines a set of one or more scopes to protect using a set of one or more authorization policies. Unlike the resource-based permissions, this permission type
allows you to create permissions not only for the resource, but also for the scopes associated with it, providing you more granularity when defining the permissions that rule 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. In {{book.project.name}}, a scope-based permissions consist of the following information:
* *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
+
* *Description*
+
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
+
* *Scopes*
+
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
* *Decision Strategy*
+
The decision strategy for this permission

16
topics/permission/overview.adoc
View file

@ -1,19 +1,9 @@
== Managing Permissions
As mentioned before, permissions define the object being protected, which can be a resource or scope, and the authorization policies
that must be evaluated in order to grant or deny the permission. Before creating a permission you must have the resources or scopes you want to protected, as well the policies you want to apply to the permission.
After creating the resources you want to protect and the policies you want to use to actually protect these resources,
you can start managing the permissions. For that, clicking on the *Permissions* tab when editing a resource server.
Permissions can be created to protect two main types of objects: *resource* and *scope*.
Permissions can be created to protect two main types of objects:
* *Resource*
+
In this case, the permission is associated with a set of one or more resources. Here you can define that only a specific
resource with a specific _name_ or _identifier_ is protected or even use a _type_ to protect any resource with a given type.
+
* *Scope*
+
In this case, the permission is associated with a set of one or more scopes. Where you may want to protect scopes associated with a specific resource or any scope regardless the resources they are associated.
*Resource-based* permissions are suitable for resource protection. There you you can define one or more resources to protect or even protect all resources with a given type.
*Scope-based* permissions are suitable for scope protection. There you you can define one or more scopes associated with a given resource or even protect scopes without specify a resource.

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

@ -1,5 +1,23 @@
== Policy Evaluation Tool
When designing your policies, you can use a UI to simulate authorization requests and check how your policies are being evaluated.
When designing your policies, you can use an UI to simulate authorization requests and 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.
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.
image:../../images/policy-evaluation-tool.png[alt="Policy Evaluation Tool"]
=== Providing Identity Information
The *Identity Information* filters can be used to specify the user asking for permissions.
You can also click *Entitlement* button to obtain all permissions for the user your selected.
=== 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.
=== 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.

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

@ -3,12 +3,35 @@
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
policies that are actually evaluated during the processing of authorization requests.
=== 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
+
* *Description*
+
A string with more details about this policy
+
* *Apply Policy*
+
Defines a set of one or more policies to associate with a policy
+
* *Decision Strategy*
+
The decision strategy for this permission
+
* *Logic*
+
The logic of this plicy
Let's suppose you have a resource called _Confidential Resource_ that can be accessed only by users with a _confidential_ role and from
a well known network. You may want to create a single policy, let's say using Javascript or Drools, with both conditions. However, you may want to reuse the _confidential_ role
part of this policy to apply to other permissions despite the network.
In this case, Keycloak allows you to create separate policies for both _confidential_ role and network conditions and create another one based on
them. You can easily achieve that by using a *Aggregate Policy* that combines other policies and then apply this aggregate policy to any permission you want.
them. You can easily achieve that by using a *Aggregated Policy* that combines other policies and then apply this 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.

85
topics/policy/drools-policy.adoc Normal file
View file

@ -0,0 +1,85 @@
== Drools-Based Policy
This type of policy allows you to define conditions for your permissions using Drools Rules. It is one of the _Rule-Based_ policy types
supported by {{book.project.name}}, giving to you a lot of flexibility to write any policy based on the link::/policy/evaluation-api.adoc[Evaluation API].
=== 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
+
* *Description*
+
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
+
** Group Id
+
The groupId of the artifact
+
** Artifact Id
+
The artifactId of the artifact
+
** Version
+
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
+
* *Session*
+
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
+
* *Logic*
+
The logic of this plicy
=== Examples
Here is a simple example of a Drools-Based policy that uses Attribute-Based Access Control (ABAC) to define a condition that evaluates to a GRANT
only if the authenticated user is the owner of the requested resource:
```javascript
import org.keycloak.authorization.policy.evaluation.Evaluation;
rule "Authorize Resource Owner"
dialect "mvel"
when
$evaluation : Evaluation(
$identity: context.identity,
$permission: permission,
$permission.resource != null && $permission.resource.owner.equals($identity.id)
)
then
$evaluation.grant();
end
```
You can even use another variant of ABAC to obtain attributes from the identity and define a condition accordingly:
```javascript
import org.keycloak.authorization.policy.evaluation.Evaluation;
rule "Authorize Using Identity Information"
dialect "mvel"
when
$evaluation : Evaluation(
$identity: context.identity,
identity.attributes.containsValue("someAttribute", "you_can_access")
)
then
$evaluation.grant();
end
```
For more details about what you can access from this interface, please take a look at link::/policy/evaluation-api.adoc[Evaluation API].

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

@ -40,3 +40,44 @@ public interface Evaluation {
```
For full instructions on using the Evaluation API refer to JavaDocs.
=== The Evaluation Context
The evaluation context provides useful information to policies during their evaluation.
```java
public interface EvaluationContext {
/**
* Returns the {@link Identity} that represents an entity (person or non-person) to which the permissions must be granted, or not.
*
* @return the identity to which the permissions must be granted, or not
*/
Identity getIdentity();
/**
* Returns all attributes within the current execution and runtime environment.
*
* @return the attributes within the current execution and runtime environment
*/
Attributes getAttributes();
}
```
From this interface, policies can obtain:
* The authenticated *Identity*
* Information about the execution context and runtime environment
Before evaluating policyes, {{book.project.name}} builds an *EvaluationContext* based on:
* All claims obtained from the OAuth2 Access Token that was sent along with the authorization request
+
In this case, the *Identity* object provides the same claims as define by the access token. For instance, if you are using a _Protocol Mapper_ to include custom claim
to a oAuth2 Access Token you can also access this claim from a policy and use it to build your conditions
+
* Some built-in environment attributes such as:
+
** kc.authz.context.time.date_time, holding the current time
** kc.authz.context.client.network.ip_address, holding the IP address of the client requesting permissions
** kc.authz.context.client.network.host, holding the host name of the client requesting permissions

50
topics/policy/js-policy.adoc Normal file
View file

@ -0,0 +1,50 @@
== 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}}, giving to you a lot of flexibility to write any policy based on the link::/policy/evaluation-api.adoc[Evaluation API].
=== 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
+
* *Description*
+
A string with more details about this policy
+
* *Code*
+
The JavaScript code providing the conditions for this policy
+
* *Logic*
+
The logic of this plicy
=== Examples
Here is a simple example of a JavaScript-Based policy that uses Attribute-Based Access Control (ABAC) to define a condition based on an attribute
obtained from the execution context:
```javascript
var context = $evaluation.getContext();
var contextAttributes = context.getAttributes();
if (contextAttributes.containsValue('kc.authz.context.client.network.ip_address', '127.0.0.1')) {
$evaluation.grant();
}
```
You can even use RBAC if you want to:
```javascript
var identity = $evaluation.getIdentity();
if (identity.hasRole('keycloak_user')) {
$evaluation.grant();
}
```
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::/policy/evaluation-api.adoc[Evaluation API].

31
topics/policy/overview.adoc
View file

@ -1,31 +1,8 @@
== Managing Policies
As mentioned before, policies define the conditions that must satisfied before granting access to a set of one or more resources.
As mentioned before, policies define the conditions that must satisfied before granting access to an object.
Keycloak provides some built-in implementations that you can use to create from the most simple to the more complex policy using different access control mechanisms.
You can view all policies associated with a resource server by clicking on the *Policy* tab when editing a resource server. On this tab, you'll find the list of policies
and options to create and edit a policy.
* *User-Based Policy*
+
Defines that only a set of one or more users are allowed to access a protected resource.
+
* *Role-Based Policy*
+
Defines that only a set of one or more roles are allowed to access a protected resource.
+
* *Time-Based Policy*
Defines that access to a protected resource is granted depending on time conditions.
+
* *Javascript-Based Policy*
+
A type of <literal>rule-based access control</literal> where you can use Javascript to write the policy conditions. With this policy
you have great flexibility to define from the more simple to most complex conditions.
+
* *Drools-Based Policy*
+
A type of <literal>rule-based access control</literal> where you can use JBoss Drools to define your policies. Here you can package policies as Maven artifacts
and get all the benefits of the rule engine provided by JBoss Drools.
+
* *Aggregated Policy*
+
Allows you to combine different policies into a single one. With this policy you can reuse existing policies and derive policies from them
accordingly with your requirements.
To create a new policy, select a policy type in the dropdown located in the right upper corner of the policy listing

23
topics/policy/role-policy.adoc Normal file
View file

@ -0,0 +1,23 @@
== Role-Based Policy
This type of policy allows you to define conditions for your permissions where only a set of one or more roles is allowed
to access an object.
=== 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
+
* *Description*
+
A string with more details about this policy
+
* *Roles*
+
Specifies which role(s) are allowed by this policy
+
* *Logic*
+
The logic of this plicy

25
topics/policy/time-policy.adoc Normal file
View file

@ -0,0 +1,25 @@
== Time-Based Policy
This type of policy allows you to define time conditions for your permissions.
* *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
+
* *Description*
+
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
+
+
* *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
+
* *Logic*
+
The logic of this plicy

23
topics/policy/user-policy.adoc Normal file
View file

@ -0,0 +1,23 @@
== User-Based Policy
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.
=== 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
+
* *Description*
+
A string with more details about this policy
+
* *Users*
+
Specifies which user(s) are allowed by this policy
+
* *Logic*
+
The logic of this plicy

4
topics/policy/view.adoc
View file

@ -1,4 +0,0 @@
== Viewing Policies
You can view all policies associated with a resource server by clicking on the *Policy* tab when editing a resource server. On this tab, you'll find the list of policies
and options to create and edit a policy.

6
topics/resource-server/configuring-entitlements.adoc
View file

@ -1,6 +0,0 @@
== Configuring Entitlements
Entitlements are very useful when you want to obtain all permissions for a specific user based on the resources managed by a resource server.
More on link:../service/entitlement-api.html[Entitlements] and link:../service/authorization-api.html[Incremental Authorization] later.
When configuring a resource server you may enable/disable entitlements by clicking the *Entitlements* switch.

40
topics/resource-server/create.adoc
View file

@ -1,18 +1,40 @@
== Creating Resource Servers
As mentioned before, everything is based on the existence of a resource server. And a resource server is basically a
*confidential* client application in {{book.project.name}}.
To create a resource server by by clicking on *Authorization* in the left menu bar. As a result, you'll be redirected
to the link::/resource-server/view.adoc[Viewing Resource Servers].
To enable a client application as a resource server you need to make sure:
On that page, click on *Create* button in the right upper corner of the table.
A resource server is basically a *confidential* client application in {{book.project.name}}. To enable a client application as a resource server you need to make sure:
* Your client application is configured as a *confidential* client.
* Your client application is configured with *Service Accounts*.
The reason why you need to use a confidential client and enable client credentials is that resource servers must be able to access the
_Protection API_ to manage their resources and issue _Permission Tickets_ for their clients. More about permission tickets later.
=== Creating the Resource Server Manually
In {{book.project.name}} Administration Console, resource servers can be managed by clicking the _Authorization_ menu item on the left side menu. There you have a
list of any existing resource server and options to create a new one.
If you have any client application with the characteristics above, they will be available for selection in the *Client* field. Just select a client application and
click on *Save*.
When creating a new resource server, you just need to select a client application from the _Client_ combobox. There are a few other configuration
options that you can provide, but the defaults should be enough to get started.
The default values for the other fields should be enough to get you started with. You can also change these options later when editing a resource server.
=== Importing a JSON file with the Resource Server Configuration
When creating a resource server, you can also import a JSON file with all the necessary configuration. For that, click on *Select File* and choose a JSON file in your filesystem
with the resource server configuration.
To actually import the file, click on *Upload*. If your configuration file is OK and successfully imported you'll be redirected to the Resource Server Details Page.
=== Policy Enforcement Modes
Resource servers provide a *Policy Enforcement Mode* configuration option that dictates how policies are enforced when processing authorization requests sent to the server.
* *Enforcing*
+
This is the default mode. Requests are denied by default even when there is no policy associated with a given resource.
+
* *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.

6
topics/resource-server/defining-authz-scopes.adoc Executable file
View file

@ -0,0 +1,6 @@
== Defining the uma_protection scope
In order to integrate with the server, you need to grant the role link:../service/protection-api.html[uma_protection] to the client application that you enabled as a
resource server.
When using the UMA protocol, this scope is also important to allow the resource server to ask the server for permission tickets.

6
topics/resource-server/export-configuration.adoc Executable file
View file

@ -0,0 +1,6 @@
== Exporting Resource Server Configuration
After creating a resource server, you can export all its configuration to a JSON file. For that, on the *Resource Server Details* page
click on *Export* button under *Export Settings*.
Once exported, you can use the configuration file to recreate your resource server or even share it with others in your team.

7
topics/resource-server/import-export-configuration.adoc
View file

@ -1,7 +0,0 @@
== Import/Export Authorization Configuration
Keycloak also allows you to import a JSON file with all the configuration for a resource server, as well export and download a JSON file with all the configuration
of an existing resource server.
When you import or export the configuration for a given resource server, you are doing it for all authorization configuration associated with it: resources, scopes, permissions,
policies, etc.

14
topics/resource-server/policy-enforcement-mode.adoc
View file

@ -1,14 +0,0 @@
== Policy Enforcement Modes
Resource servers provide a *Policy Enforcement Mode* configuration option that dictates how policies are enforced when processing authorization requests sent to the server.
* *Enforcing*
+
This is the default mode. Requests are denied by default even when there is no policy associated with a given resource.
+
* *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.

5
topics/resource-server/uma-protection-scope.adoc
View file

@ -1,5 +0,0 @@
== Defining uma_protection scope
As mentioned before, resource servers must have access to the *Protection API* to manage their resources and issue *Permission Tickets*.
For that, you must create a _realm role_ with name *uma_protection* and map this role to the client application that you want to configure as a resource server.

1
topics/resource-server/view.adoc
View file

@ -1,2 +1,3 @@
== Viewing Resource Servers
You can view all existing resource servers by clicking on *Authorization* in the left menu bar.

44
topics/resource/create.adoc Executable file
View file

@ -0,0 +1,44 @@
== 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
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 *Create* button in the right upper corner of the resource listing. In {{book.project.name}}, a resource defines a small set of information that is common to different types of resources, such as:
* *Name*
+
A human-readable and unique string describing a set of one or more resources.
+
* *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.
+
* *URI*
+
A URI that provides the location/address for the resource. For HTTP resources, the URI
is usually the relative path used to serve these resources.
+
* *Scopes*
+
One more scopes to associate with the resource
=== Typed Resources
The type field of a resource may be used to group different resources together, so they can be protected using a common set of permissions.
=== 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.
=== Managing Resources Remotely
Resource management is also exposed through the link:../service/protection-api.html[Protection API] to allow resource servers to remotely manage their resources.
When using the Protection API, resource servers can be implemented to manage resources owned by their users. In this case, you can
specify the user identifier to configure a resource as belonging to a specific user.
[NOTE]
{{book.project.name}} provides to resource server completly control over its resources. In the future, we should be able to
allow users to control their own resources, approve authorization requests and manage permissions. Specially when using the UMA protocol.

41
topics/resource/overview.adoc
View file

@ -1,41 +1,4 @@
== Managing Resources and Scopes
After creating a resource server, you can start creating resources - and their respective scopes - that you want to protect. Resources and scopes can be managed
by clicking on the *Resource* and *Scope* tabs, respectively.
Resource management 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
be created to represent a set of one or more resources and the way you define them is crucial to start managing permissions.
Resources also have an owner. By default, resources created from the adminstration console are owned by the resource server itself. 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.
In {{book.project.name}}, a resource defines a small set of information that is common to different types of resources, such as:
* *Name*
+
A human-readable and unique string describing a set of one or more resources.
+
* *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.
+
* *URI*
+
A URI that provides the location/address for the resource. For HTTP resources, the URI
is usually the relative path used to serve these resources.
+
* *Scopes*
+
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 <literal>verbs</literal> that can logically
apply to a resource.
+
* *Owner*
+
An entity that owns the resource. It can be the resource server itself or even a
specific user.
Resource management is also exposed through the *Protection API* to allow resource servers to remotely manage their resources. This is a very important
feature that allows resource servers to obtain the list of protected resources in order to actually enforce the authorization decisions. We'll see more on that
later when we talk about _Policy Enforcers_.
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.

13
topics/resource/view.adoc Executable file
View file

@ -0,0 +1,13 @@
=== Viewing Resources
When you click on *Resource* tab, you'll be redirect to a page listing all the resources associated with a resource server.
The resource list provides some very useful information about the protected resources, such as:
* Type
* URI
* Owner
* Associated scopes, if any
* Associated permissions
From there you can also create a permission right away by clicking on *Create Permission* button for the resources you want to create the permission.

57
topics/service/authorization-api-aapi.adoc Executable file
View file

@ -0,0 +1,57 @@
== Requesting Authorization Data and Token
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.
```bash
http://${host}:${port}/auth/realms/${realm_name}/authz/authorize
```
When asking for a RPT, you need to provide two main things:
* A permission ticket with the resources you want to access
* The AAT (as a bearer token) representing user's identity and his consent to access authorization data on his behalf.
```bash
curl -X POST
-H "Authorization: Bearer ${AAT}" -d '{
"ticket" : ${PERMISSION_TICKET}
}' "http://localhost:8080/auth/realms/hello-world-authz/authz/authorize"
```
As a result, you will get the follow response from the server:
```json
{"rpt":"${RPT}"}
```
=== 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)].
Its lifetime is the same as with the OAuth2 access token (AAT) that was used to obtain it.
When you decode a RPT you will see something like that:
```json
{
"permissions": [
{
"resource_set_id": "152251e6-f4cf-4464-8d91-f1b7960fa5fc",
"resource_set_name": "Hello World Resource"
"scopes": []
}
],
"accessToken": ${AAT},
"jti": "d6109a09-78fd-4998-bf89-95730dfd0892-1464906679405",
"exp": 1464906971,
"nbf": 0,
"iat": 1464906671,
"sub": "f1888f4d-5172-4359-be0c-af338505d86c",
"typ": "kc_ett",
"azp": "hello-world-authz-service"
}
```
The *permissions* claim consists of all the permissions granted by the server. There is also a *accessToken* property holding the AAT that was used to issue the RPT.

58
topics/service/authorization-api.adoc
View file

@ -1,57 +1,7 @@
== Authorization API
The <literal>Authorization API</literal> consists of a single endpoint responsible to issue a special type of token with all the requested permissions given
a <literal>permission ticket</literal> and a OAuth2 <literal>access_token</literal>.
The Authorization API provides a UMA-compliant endpoint 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.
```bash
curl -X POST -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/json" -d '{
"ticket": "${permission_ticket}"
}' "http://localhost:8080/auth/realms/photoz/authz/authorize"
```
As mentioned before, the permission ticket contains the resources and scopes the client is requesting access. Based on it, the authorization endpoint is going
to evaluate all the policies associated with these resources and scopes and return back a final token with all the granted permissions.
```json
{
"permissions": [
{
"resource_set_id": "87852cb2-700f-45d1-a9ab-786564aa123a",
"scopes": [
"urn:photoz.com:scopes:album:view",
"urn:photoz.com:scopes:album:create"
]
},
{
"resource_set_id": "fe372a25-65ef-4140-926c-96d9523ee40b",
"scopes": [
"urn:photoz.com:scopes:profile:view"
]
}
],
"accessToken": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmOTNlMjhjOC1kMDIzLTRhMTQtYjViZS03NGY0ZjljMjI2NmYiLCJleHAiOjE0NjA0ODg1MDcsIm5iZiI6MCwiaWF0IjoxNDYwNDg4NDQ3LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvcGhvdG96IiwiYXVkIjoicGhvdG96LWh0bWw1LWNsaWVudCIsInN1YiI6ImJkMzBlNDA5LTM4YjItNDM5Yy1iOTdlLTFhYzk0MzE2YWRmMCIsInR5cCI6IkJlYXJlciIsImF6cCI6InBob3Rvei1odG1sNS1jbGllbnQiLCJub25jZSI6IjkzY2JlMjA2LTg4Y2UtNGMxNi04NGEzLWE0NWMzNzNkY2FjNSIsInNlc3Npb25fc3RhdGUiOiI3NmQwYTdlMi03YWY0LTQ3NmYtOTZlZS1kMjE1NjQ0ZTIxOTIiLCJjbGllbnRfc2Vzc2lvbiI6IjRjMDZkZTZjLTkyZGUtNGIzYi04MGZhLWIzMjZiNjYyMWIwNyIsImFsbG93ZWQtb3JpZ2lucyI6WyIiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJwaG90b3otaHRtbDUtY2xpZW50Ijp7InJvbGVzIjpbImtjX2VudGl0bGVtZW50IiwidW1hX2F1dGhvcml6YXRpb24iXX19LCJuYW1lIjoiQWxpY2UgSW4gQ2hhaW5zIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiYWxpY2UiLCJnaXZlbl9uYW1lIjoiQWxpY2UiLCJmYW1pbHlfbmFtZSI6IkluIENoYWlucyIsImVtYWlsIjoiYWxpY2VAa2V5Y2xvYWsub3JnIn0.Bllirh-Lr9Q1hgMIZGzT1gR0uVPGhby5L92B6zSu4Zj22UMMV_JlxR-2l7lI5qHYdMgUhm2vdLKZ0axhSKT63OUsWV1cN6exkNAUcjfS3sCJIEljUAmDDh-2pw3f6oE5l7llHzatNH8VNqbZs-Z6TXj2fyrta-fUyu6IDgCaKoQ",
"jti": "0975d59a-4550-45a4-a535-6d520b1ffa77-1460488455577",
"exp": 1460488507,
"nbf": 0,
"iat": 1460488447,
"sub": "bd30e409-38b2-439c-b97e-1ac94316adf0",
"typ": "kc_ett",
"azp": "photoz-html5-client"
}
```
Following the UMA specification, this token is called <literal>Requesting Party Token</literal> or just <literal>RPT</literal>. With a RPT, a client
can send this token as a bearer token to a resource server, which in turn will introspect the RPT sent by the client and check if the resource the client
is trying to access can be mapped to the any permission within the RPT.
When asking for RPTs using the <literal>Authorization API</literal>, the corresponding <literal>access_token</literal> must contain a <literal>uma_authorization</literal> scope. In other words, the client asking for
RPTs on behalf of an user must be granted with this scope.
=== Incremental Authorization
As mentioned before, when asking for a RPT you must send a <literal>permission ticket</literal> and a OAuth2 <literal>access_token</literal>. However, accordingly
with UMA specification, you may also send some previous (and still valid) RPT. In this case, the resulting RPT will consist of all permissions being requested within the
permission ticket plus those that are present on a previous RPT.
That process is what we call <literal>incremental authorization</literal>, given that the final RPT consists of permissions previously granted (based on the previous RPT) and the new permissions
from a permission ticket.
Unlike the Protection API, any client application can access the Authorization API endpoint, which requires a special OAuth2 access token called *Authorization API Token* or *AAT*.
In UMA, a AAT is just a token with a scope *uma_authorization*.

117
topics/service/client-api.adoc Executable file
View file

@ -0,0 +1,117 @@
== Authorization Client API
If you are using Java you can access all {{book.project.name}} {{book.project.module}} using a client API.
=== Maven Dependency
```xml
<dependencies>
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-authz-client</artifactId>
<version>${KEYCLOAK_VERSION}</version>
</dependency>
</dependencies>
```
=== Configuration
The client configuration is defined in a JSON file as follows:
```json
{
"client": {
"configurationUrl": "http://localhost:8080/auth/realms/${realm_name}/.well-known/uma-configuration",
"clientId": ${clientId},
"clientSecret": ${clientSecret}
}
}
```
* *configurationUrl*
+
Use this property to specify and URL pointing to the Authorization Services Discovery URL.
+
* *clientId*
+
The identifier of the client application configured as a resource server
+
* *clientSecret*
+
The credential of the client application configured as a resource server
=== Obtaining User Entitlements
Here is an example about how to obtain user entitlements:
```java
// create a new instance based on the configuration define at keycloak-authz.json
AuthzClient authzClient = AuthzClient.create();
// query the server for a resource with a given name
Set<String> resourceId = authzClient.protection()
.resource()
.findByFilter("name=Hello World Resource");
// 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
String eat = getEntitlementAPIToken(authzClient);
// create an entitlement request
EntitlementRequest request = new EntitlementRequest();
request.addPermission(new PermissionRequest(resourceId.iterator().next()));
// 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);
// 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:
```java
// create a new instance based on the configuration define at 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
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", request);
String rpt = response.getRpt();
System.out.println("You got a RPT: " + rpt);
// now you can use the RPT to access protected resources on the resource server
```
=== Creating a Resource Using the Protection API
```java
// create a new instance based on the configuration define at keycloak-authz.json
AuthzClient authzClient = AuthzClient.create();
// create a new resource representation with the information we want
ResourceRepresentation newResource = new ResourceRepresentation();
newResource.setName("New Resource");
newResource.setType("urn:hello-world-authz:resources:example");
newResource.addScope(new ScopeRepresentation("urn:hello-world-authz:scopes:view"));
ProtectedResource resourceClient = authzClient.protection().resource();
// create the resource on the server
RegistrationResponse response = resourceClient.create(newResource);
String resourceId = response.getId();
// query the resource using its newly generated id
ResourceRepresentation resource = resourceClient.findById(resourceId).getResourceDescription();
```java

56
topics/service/entitlement-api-aapi.adoc Executable file
View file

@ -0,0 +1,56 @@
== 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.
```bash
http://${host}:${port}/auth/realms/${realm_name}/authz/entitlement
```
When asking for entitlements using this endpoint, you need to provide the EAT (as a bearer token) representing user's identity and his consent to access authorization data on his behalf.
```bash
curl -X GET \
-H "Authorization: Bearer ${EAT}" \
"http://localhost:8080/auth/realms/hello-world-authz/authz/entitlement/${resource_server_id}"
```
Where *${resource_server_id}* is the *client_id* for the client application registered as a resource server.
As a result, you'll get a response from the server as follows:
```json
{
"rpt": ${RPT}
}
```
=== 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)].
Its lifetime is the same as with the OAuth2 access token (EAT) that was used to obtain it.
When you decode a RPT you will see something like that:
```json
{
"permissions": [
{
"resource_set_id": "152251e6-f4cf-4464-8d91-f1b7960fa5fc",
"resource_set_name": "Hello World Resource"
"scopes": []
}
],
"accessToken": ${EAT},
"jti": "d6109a09-78fd-4998-bf89-95730dfd0892-1464906679405",
"exp": 1464906971,
"nbf": 0,
"iat": 1464906671,
"sub": "f1888f4d-5172-4359-be0c-af338505d86c",
"typ": "kc_ett",
"azp": "hello-world-authz-service"
}
```
The *permissions* claim consists of all the permissions granted by the server. There is also a *accessToken* property holding the AAT that was used to issue the RPT.

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

@ -1,20 +1,12 @@
== Entitlements API
An entitlement in the context of an access control decision is a privilege for an user or a process to
perform or have rights to an action on a resource. The concept is pretty much similar to what we were calling a permission.
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.
However, the Entitlements API allows you to obtain all the entitlements or permissions given an OAuth2 _access_token_. Different
than the Authorization API, which is strongly based on UMA, this API provides a more simple way to obtain the permissions for a given user
or entity in possession of a OAuth2 _access_token.
Unlink the_Authorization API, the Entitlement API is not UMA-compliant and don't require permission tickets.
In this case, {{book.project.name}} will evaluate policies associated with any resource within a resource server and return the permissions that were granted during this process.
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.
```bash
curl -X GET -H "Authorization: Bearer ${access_token}" "http://localhost:8080/auth/realms/photoz/authz/entitlement?resourceServerId=photoz-restful-api"
```
Any client application can access the Entitlement API endpoint, which requires a special OAuth2 access token called *Entitlement API Token* or *EAT*.
The resulting token from a "entitlements request" is the same when you are using the Authorization API. At end you will get a RPT with all the permissions
or entitlements for a given user.
When asking for entitlements, the corresponding _access_token_ must contain a *kc_entitlement* scope. In other words, the client asking for
entitlements on behalf of an user must be granted with this scope.

10
topics/service/overview.adoc
View file

@ -1,11 +1,3 @@
== Authorization Services
Keycloak Authorization Services are based on OAuth2 and User-Managed Access (UMA). Where the latter is basically a OAuth2 profile
that defines new terms, tokens and flows in order to define how resource owners can control protected-resource access by clients operated
by arbitrary requesting parties, where the resources reside on any number of resource servers, and where a centralized authorization server governs access based on resource owner policies.
However, our implementation of UMA is limited to provide a protocol to enable clients and resource servers to obtain and exchange permissions for their users. In the future,
we are planning to also support other functionalities and flows provided with UMA such as authorization flows and resource owner's resource sharing. In other words, for now our focus
is API security and for that UMA provides a very simple and easy-to-use extension to OAuth2 to support fine-grained authorization.
That said, we strongly recommend you to take a look at https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA specification].
Keycloak Authorization Services are based on OAuth2 and User-Managed Access (UMA).

21
topics/service/permission-api-papi.adoc Executable file
View file

@ -0,0 +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*.
```bash
http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission
```
A Permission ticket is a special security token type representing a permission request. Accordingly with 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 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.

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

@ -1,40 +1,14 @@
== Protection API
The Protection API consists of set of endpoints responsible to:
The Protection API provides a UMA-compliant set of endpoints providing:
* *Resource Registration*
+
From this endpoint resource servers can manage their resources and perform operations such as create, update, remove and searches.
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 to be protected
* *Permission Registation*
+
From this endpoint, resource servers may ask the server for a permission ticket that in turn will be sent to a client in order to obtain a final token with all the permissions for a given user.
When using UMA protocol, resource servers can access this endpoint to issue permission tickets.
When accessing the Protection API the client application acting as a resource server must be able to obtain an access token from the Keycloak Server.
With this token, the resource server is allowed to invoke the protection endpoints and perform any operation. Beside that, they need to be granted with a
*uma_protection* role. If none of these conditions are met, access to the Protection API is denied.
=== Permission Ticket
As mentioned before, one of the main services provided by the Protection API is related with issuing _permission tickets_.
A permission ticket is a special type of the token introduced with UMA that provides 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".
It completely hides from clients the permissions required to access a set of one or more resources at the resource server and allows the authorization server to introduce another security layer that manages
permissions requests to a resource server and its resources. For instance, in the future we are planning to support authorization workflows where an user can control his resources and approve permission requests
from others to access his resources (resource sharing).
Permission tickets can be obtained by a resource server as follows:
```bash
curl -X POST -H "Authorization: Bearer ${access_token}" -d '{
"resource_set_id": "53fe1824-9d8b-4c8d-a03d-c9547318cdf2",
"scopes": [
"urn:photoz.com:scopes:album:view"
]
}' "http://localhost:8080/auth/realms/photoz/authz/protection/permission"
```
As mentioned before, the _access_token_ sent with the request above was issued to the resource server using client credentials. Where the access_token
also include a *uma_protection* scope.
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*.
In UMA, a PAT is just a token with a scope *uma_protection*.

18
topics/service/resources-api-papi.adoc Executable file
View file

@ -0,0 +1,18 @@
== Managing Resources Using the Protection API
Resource servers can manage their resources remotely using a UMA-compliant endpoint.
```bash
http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set
```
This endpoint provides some registration operations as follows:
* Create resource set description: POST /resource_set
* Read resource set description: GET /resource_set/{_id}
* Update resource set description: PUT /resource_set/{_id}
* Delete resource set description: DELETE /resource_set/{_id}
* List resource set descriptions: GET /resource_set
* List resource set descriptions using a filter: GET /resource_set?filter=filter-name=
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].

36
topics/service/whatis-obtain-aat.adoc Executable file
View file

@ -0,0 +1,36 @@
== 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*.
Client applications can obtain an AAT from {{book.project.name}} just like any other OAuth2 Access Token. Usually, client applications are going to obtain AATs after the user is successfuly
authenticated in {{book.project.name}}. By default the _authorizaton_code_ grant type is used to authenticate users and issue 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.
```bash
curl -X POST \
-H "Authorization: Basic aGVsbG8td29ybGQtYXV0aHotc2VydmljZTpwYXNzd29yZA==" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'username=${username}&password=${user_password}&grant_type=password' \
"http://localhost:8080/auth/realms/${realm_name}/protocol/openid-connect/token"
```
As a result, you will get the following response from the server:
```json
{
"access_token": ${AAT},
"expires_in": 300,
"refresh_expires_in": 1800,
"refresh_token": ${refresh_token},
"token_type": "bearer",
"id_token": ${id_token},
"not-before-policy": 0,
"session_state": "3cad2afc-855b-47b7-8e4d-a21c66e312fb"
}
```
== About the uma_authorization scope
The *uma_authorization* scope indicates that an user consented access to his authorization data to a client application. You can create this
scope a _client role_ and map it to your users.

36
topics/service/whatis-obtain-eat.adoc Executable file
View file

@ -0,0 +1,36 @@
== What is a EAT and How to Obtain it ?
An *Entitlement API Token* or *EAT* is a special OAuth2 Access Token with the scope *kc_entitlement*.
Client applications can obtain an EAT from {{book.project.name}} just like any other OAuth2 Access Token. Usually, client applications are going to obtain EATs after the user is successfully
authenticated in {{book.project.name}}. By default the _authorizaton_code_ grant type is used to authenticate users and issue 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 EAT.
```bash
curl -X POST \
-H "Authorization: Basic aGVsbG8td29ybGQtYXV0aHotc2VydmljZTpwYXNzd29yZA==" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'username=${username}&password=${user_password}&grant_type=password' \
"http://localhost:8080/auth/realms/${realm_name}/protocol/openid-connect/token"
```
As a result, you will get the following response from the server:
```json
{
"access_token": ${EAT},
"expires_in": 300,
"refresh_expires_in": 1800,
"refresh_token": ${refresh_token},
"token_type": "bearer",
"id_token": ${id_token},
"not-before-policy": 0,
"session_state": "3cad2afc-855b-47b7-8e4d-a21c66e312fb"
}
```
== About the kc_entitlement scope
The *kc_entitlement* scope indicates that an user consented access to his authorization data to a client application. You can create this
scope a _client role_ and map it to your users.

37
topics/service/whatis-obtain-pat.adoc Executable file
View file

@ -0,0 +1,37 @@
== What is a PAT and How to Obtain it ?
A PAT is a special OAuth2 Access Token with the scope *uma_protection*.
Resource servers can obtain a PAT from {{book.project.name}} just like any other OAuth2 Access Token.
```bash
curl -X POST \
-H "Authorization: Basic aGVsbG8td29ybGQtYXV0aHotc2VydmljZTpwYXNzd29yZA==" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'grant_type=client_credentials' \
"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:
[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.
```bash
{
"access_token": ${PAT},
"expires_in": 300,
"refresh_expires_in": 1800,
"refresh_token": ${refresh_token},
"token_type": "bearer",
"id_token": ${id_token},
"not-before-policy": 0,
"session_state": "ccea4a55-9aec-4024-b11c-44f6f168439e"
}
```
== About the uma_protection scope
The *uma_protection* scope can be created just like any other _realm role_. Once you created it, just grant this role to
the client application that you want to use as a resource server.