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

Merge pull request #16 from pedroigor/master

Browse source 
Updating docs with latest changes.
This commit is contained in:
Pedro Igor 2016-06-16 14:08:49 -03:00 committed by GitHub
commit a74721cb76
29 changed files with 222 additions and 465 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
SUMMARY.adoc
View file

@ -4,13 +4,13 @@
.. link:topics/overview/architecture.adoc[Architecture]
.. link:topics/overview/terminology.adoc[Terminology]
. link:topics/resource-server/overview.adoc[Managing Resource Servers]
.. link:topics/resource-server/create-client.adoc[Creating a Client Application]
.. link:topics/resource-server/enable-authorization.adoc[Enabling Authorization Services]
.. link:topics/resource-server/default-config.adoc[Default Configuration]
.. link:topics/resource-server/import-config.adoc[Exporting and Importing Authorization 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/create-resource.adoc[Creating Resource-based Permissions]
.. link:topics/permission/create-scope.adoc[Creating Scope-based Permissions]
.. link:topics/permission/decision-strategy.adoc[Policy Decision Strategies]
. link:topics/policy/overview.adoc[Managing Policies]
.. link:topics/policy/user-policy.adoc[User-Based Policy]
.. link:topics/policy/role-policy.adoc[Role-Based Policy]
@ -20,19 +20,23 @@
.. 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/permission/overview.adoc[Managing Permissions]
.. link:topics/permission/create-resource.adoc[Creating Resource-based Permissions]
.. link:topics/permission/create-scope.adoc[Creating Scope-based Permissions]
.. link:topics/permission/decision-strategy.adoc[Policy Decision Strategies]
. link:topics/policy-evaluation-tool/overview.adoc[Evaluating and Testing Policies]
. link:topics/service/overview.adoc[Authorization Services]
.. link:topics/service/protection/protection-api.adoc[Protection API]
... link:topics/service/protection/whatis-obtain-pat.adoc[What is a PAT and How to Obtain It]
... link:topics/service/protection/resources-api-papi.adoc[Managing Resources]
... link:topics/service/protection/permission-api-papi.adoc[Managing Permission Requests]
... link:topics/service/protection/token-introspection.adoc[Introspecting a Requesting Party Token]
.. link:topics/service/authorization/authorization-api.adoc[Authorization API]
... link:topics/service/authorization/whatis-obtain-aat.adoc[What is a AAT and How to Obtain It]
... link:topics/service/authorization/authorization-api-aapi.adoc[Requesting Authorization Data and Token]
.. link:topics/service/entitlement/entitlement-api.adoc[Entitlement API]
... link:topics/service/entitlement/whatis-obtain-eat.adoc[What is a EAT and How to Obtain It]
... link:topics/service/entitlement/entitlement-api-aapi.adoc[Requesting Entitlements]
.. link:topics/service/protection/token-introspection.adoc[Introspecting a Requesting Party Token]
.. link:topics/service/client-api.adoc[Authorization Client Java API]
. link:topics/enforcer/overview.adoc[Policy Enforcers]
.. link:topics/enforcer/keycloak-enforcement-filter.adoc[Keycloak Adapter Policy Enforcer]

BIN
images/permission/view.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 95 KiB

After

Width:  |  Height:  |  Size: 101 KiB

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

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 92 KiB

After

Width:  |  Height:  |  Size: 108 KiB

BIN
images/policy/view.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 108 KiB

After

Width:  |  Height:  |  Size: 125 KiB

BIN
images/resource-server/authz-export.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 113 KiB

BIN
images/resource-server/authz-settings.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 90 KiB

BIN
images/resource-server/client-create.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 71 KiB

BIN
images/resource-server/client-enable-authz.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 120 KiB

BIN
images/resource-server/client-list.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 84 KiB

BIN
images/resource-server/default-permission.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 86 KiB

BIN
images/resource-server/default-policy.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 85 KiB

BIN
images/resource-server/default-resource.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 92 KiB

BIN
images/resource/create.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 70 KiB

After

Width:  |  Height:  |  Size: 72 KiB

BIN
images/resource/view.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 112 KiB

After

Width:  |  Height:  |  Size: 118 KiB

BIN
images/service/rs-uma-protection-role.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 99 KiB

176
topics/enforcer/entitlement-bearer-enforcement-filter.adoc
View file

@ -1,176 +0,0 @@
== Entitlement Bearer Token Enforcement Filter
The *org.keycloak.authorization.policy.enforcer.servlet.EntitlementBearerTokenEnforcementFilter* 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.EntitlementBearerTokenEnforcementFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Keycloak Authorization Enforcer</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
```
When using this filter, client applications need to send a RPT as a *Bearer* token using the *Authorization* header in order to gain access to a protected resource.
```bash
curl -X GET \
-H "Authorization: Bearer %{RPT}" \
"http://my-app/api/resource"
```
If the client application (or requesting party) trying to access the protected resource does not provide a RPT within the request, the filter is going to respond to the client with a 401 HTTP status code and
a *WWW-Authenticate* header as follows:
```bash
HTTP/1.1 401 Unauthorized
WWW-Authenticate: KC_ETT realm="${resource_server_id}",as_uri="http://${kc_server_host}:${kc_server_port}/auth/realms/${realm_name}/authz/entitlement"
```
Where *KC_ETT* indicates that the resource server requires a RPT with entitlements and *as_uri* holds the URI that clients can use to obtain a RPT based on an OAuth2 Access Token previously issued by a {{book.project.name}} server during user authentication.
=== Configuration
The _EntitlementBearerTokenEnforcementFilter_ 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.
+
** *online-introspection*
+
If true, the enforcer is going to validate RPTs by calling the token introspection endpoint. Thus, performing an additional round-trip to the server. Otherwise, the RPT is validated locally.
+
** *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>

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

@ -2,6 +2,14 @@
You can enforce authorization decisions to your applications if you are using {{book.project.name}} OIDC Adapters.
When you enable policy enforcement to your {{book.project.name}} application, the corresponding adapter is going to intercept
every single request to your application and enforce the authorization decisions obtained from the server.
Policy enforcement is strongly based on your application's paths and the link:../resource/overview.html[Resources] you created to a resource server using the {{book.project.name}} Administration Console. By default,
when you create a resource server, {{book.project.name}} creates a link:../resource-server/default-config.html[Default Configuration] to your resource server so you can enable policy enforcement very quickly.
The default configuration allows access for every single resource in your application as long as the authenticated user belongs to the same realm as the resource server being protected.
=== Configuration
To enable policy enforcement to your application, add the following property to your *keycloak.json* file:

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

@ -1,38 +0,0 @@
== 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>

178
topics/enforcer/uma-bearer-enforcement-filter.adoc
View file

@ -1,178 +0,0 @@
== UMA Bearer Token Enforcement Filter
The *org.keycloak.authorization.policy.enforcer.servlet.UmaBearerTokenEnforcementFilter* 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.UmaBearerTokenEnforcementFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Keycloak Authorization Enforcer</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
```
When using this filter, client applications need to send a RPT as a *Bearer* token using the *Authorization* header in order to gain access to a protected resource.
```bash
curl -X GET \
-H "Authorization: Bearer %{RPT}" \
"http://my-app/api/resource"
```
If the client application (or requesting party) trying to access the protected resource does not provide a RPT within the request, the filter is going to respond to the client with a 401 HTTP status code and
a *WWW-Authenticate* header as follows:
```bash
HTTP/1.1 401 Unauthorized
WWW-Authenticate: UMA realm="${resource_server_id}",as_uri="http://${kc_server_host}:${kc_server_port}/auth/realms/${realm_name}/authz/authorize",ticket="${PERMISSION_TICKET}"
```
From that response, users can use the permission ticket returned by the resource server and use it to obtain a RPT using the UMA protocol, as described by link:../service/authorization/authorization-api.html[Authorization API].
Where *UMA* indicates that this resource server requires a RPT and *as_uri* holds the URI that clients can use to obtain the RPT based on UMA protocol.
=== Configuration
The _EntitlementBearerTokenEnforcementFilter_ 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.
+
** *online-introspection*
+
If true, the enforcer is going to validate RPTs by calling the token introspection endpoint. Thus, performing an additional round-trip to the server. Otherwise, the RPT is validated locally.
+
** *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>

14
topics/overview/overview.adoc
View file

@ -16,8 +16,20 @@ Being based on a set of administrative UIs and a RESTful API, {{book.project.nam
for your protected resources and scopes, associate these permissions with authorization policies and enforce authorization
decisions in your application and services.
Resource servers (the application or service serving protected resources) usually rely on some kind of information to decide whether access to a protected resource should be granted or not. For RESTful-based resource servers,
that information is usually obtained from a security token, usually sent as a bearer token on every single request to the server. For web applications that rely on a session to
authenticate their users, that information is usually stored into user's session and retrieved from there on every single request.
Usually, resource servers only perform authorization decisions based on _Role-based Access Control_ or _RBAC_, where the roles granted to the user trying to access protected resources are
checked against the roles mapped to these same resources. While roles are very useful and used by applications, they also have a few limitations:
* Resources and roles are tight coupled and changes to roles (add, remove or change it's access context) may impact several resources
* Changes to your security requirements may imply deep changes to application code to reflect these changes
* Depending on your application size, role management may become a problem and error-prone
* It is not the most flexible access control mechanism. Roles do not represent who you are and lack context information. If you have it, you can do something.
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 provides:
using different devices and with a high demand for information sharing, {{book.project.name}} Authorization Services can help you to improve the authorization capabilities of your application and services by providing:
* Resource protection using fine-grained authorization policies and different access control mechanisms
* Centralized Resource, Permission and Policy Management

2
topics/policy/overview.adoc
View file

@ -9,4 +9,4 @@ image:../../images/policy/view.png[alt="Policies"]
On this tab, you'll find the list of policies and options to create and edit a policy.
To create a new policy, select a policy type in the dropdown located in the right upper corner of the policy listing.
To create a new policy, select a policy type in the dropdown `Create policy` located in the right upper corner of the policy listing.

25
topics/resource-server/create-client.adoc Executable file
View file

@ -0,0 +1,25 @@
== Creating a Client Application
The first step to enable {{book.project.name}} {{book.project.module}} is create the client application that you want to turn into a resource server. For that, click on the `Clients` left menu item.
.Clients
image:../../images/resource-server/client-list.png[alt="Clients"]
In this page, click on the `Create` button on the right.
.Create Client
image:../../images/resource-server/client-create.png[alt="Create Client"]
In this page, fill in the fields as follows:
* Enter in the `Client ID` of the client. For insance, _my-resource-server_.
* Enter in the `Root URL` for your application. For instance:
+
```bash
http://${host}:${port}/my-resource-server
```
Finally, click `Save`. This will create the client and bring you to the client `Settings` tab.
.Client Settings
image:../../images/resource-server/client-enable-authz.png[alt="Client Settings"]

57
topics/resource-server/default-config.adoc Executable file
View file

@ -0,0 +1,57 @@
== Default Configuration
When you create a resource server, {{book.project.name}} creates a default configuration to your newly created resource server.
The default configuration consists of:
* A default protected resource representing all resources in your application.
* A policy that grants access only for users within the same _realm_ as the resource server.
* A permission that governs access to all resources based on the default policy.
The default protected resource is called *Default Resource* and you can see it if you click on the `Resources` tab.
.Default Resource
image:../../images/resource-server/default-resource.png[alt="Default Resource"]
This resource defines a `Type` `urn:my-resource-server:resources:default` and an `URI` `/*`. Here, the `URI` field defines a
wildcard pattern that tells {{book.project.name}} that this resource represents all the paths in your application. In other words,
when enabling link:../enforcer/overview.html[Policy Enforcement] to your application, all the permissions associated with the resource
will be checked before granting access.
The default policy is called *Only From Realm Policy* and you can see it if you click on the `Policies` tab.
.Default Policy
image:../../images/resource-server/default-policy.png[alt="Default Policy"]
This policy is a link:../policy/js-policy.html[JavaScript-Based Policy] defining a condition where only users from the same _realm_ as the
resource server are granted with access. If you click on this policy you'll see that it defines a rule as follows:
```js
var context = $evaluation.getContext();
// using attributes from the evaluation context to obtain the realm
var contextAttributes = context.getAttributes();
var realmName = contextAttributes.getValue('kc.authz.context.authc.realm').asString(0);
// using attributes from the identity to obtain the issuer
var identity = context.getIdentity();
var identityAttributes = identity.getAttributes();
var issuer = identityAttributes.getValue('iss').asString(0);
// only users from the realm have access granted
if (issuer.endsWith(realmName)) {
$evaluation.grant();
}
```
For last, the default permission is called *Default Permission* and you can see it if you click on the `Permissions` tab.
.Default Permission
image:../../images/resource-server/default-permission.png[alt="Default Permission"]
This permission is a link:../permission/overview.html[Resource-Based Permission], defining that a set of one or more policies should
be applied to all resources with a given type.
== Post-Configuration Instructions
You are not forced to keep the default configuration if you don't want to. You can remove the default resource, policy and permission any time you want.

68
topics/resource-server/enable-authorization.adoc Executable file
View file

@ -0,0 +1,68 @@
== Enabling Authorization Services
To turn your client application into a resource server and enable fine-grained authorization, click on the `Authorization Services Enable` switch and turn it `ON`.
.Enabling Authorization Services
image:../../images/resource-server/client-enable-authz.png[alt="Enabling Authorization Services"]
Finally, click `Save`. When you do that,
a new `Authorization` tab will show up. Click on this tab and you should see a page like that.
.Resource Server Settings
image:../../images/resource-server/authz-settings.png[alt="Resource Server Settings"]
The `Authorization` tab provides a few additional tabs covering the different steps that you should follow to actually protect your application's resources. Each tab is covered separately by
a specific topic in this documentation. But here is a quick description about each one:
* *Settings*
+
General settings for your resource server. More details about this page in this section.
* *Resource*
+
From this tab, you can manage your application's link:../resource/overview.html[Resources].
* *Scope*
+
From this tab, you can manage link:../resource/overview.html[Scopes].
* *Policies*
+
From this tab, you can manage link:../policy/overview.html[Authorization Policies] and define the conditions that must be met in order to grant a permission.
* *Permissions*
+
From this tab, you can manage the link:../permission/overview.html[Permissions] for your protected resources and scopes by linking them with the policies you created.
* *Evaluate*
+
From this tab, you can link:../policy-evaluation-tool/overview.html[Simulate Authorization Requests] and check the result of the evaluation of the permissions and authorization policies you have defined.
=== Resource Server Settings
Let’s walk through each configuration item on this page.
* *Policy Enforcement Mode*
+
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.
+
* *Allow Remote Resource Management*
+
Should resources be managed remotely by the resource server? If false, resources can only be managed from this admin console.
+
* *Export Settings*
+
In this section you can export all settings to a JSON file. It provides a single `Export` button that you can click to
download a JSON file containing every single configuration defined for a resource server: protected resources, scopes, permissions and policies.

27
topics/resource-server/import-config.adoc Executable file
View file

@ -0,0 +1,27 @@
== Exporting and Importing Configuration
All the configuration defined for a resource server can be exported and downloaded. The resulting configuration file contains
every single configuration you defined for:
* Protected Resources and Scopes
* Policies
* Permissions
To export configuration, go to the `Resource Server Settings` page.
.Resource Server Settings
image:../../images/resource-server/authz-settings.png[alt="Resource Server Settings"]
In this page, you'll see a `Export Settings` section, which provides a single `Export` button. Click on that button and you'll see.
.Export Settings
image:../../images/resource-server/authz-export.png[alt="Export Settings"]
The configuration is exported using a JSON format, which you can copy and paste or click on the `Download` button to download a file with the configuration being exported.
=== Importing
To import a file with the configuration for your resource server, click on the `Select file`. It should open a dialog box from where you can select a file in your
filesystem with the configuration you want to import.
You can use this feature to both create an initial configuration for your resource server or to update the existing configuration.

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

@ -2,61 +2,7 @@
If you are familiar with OAuth2, a Resource Server is the server hosting the protected resources and capable of accepting and responding to protected resource requests.
Resource servers usually rely on some kind of information to decide whether access to a protected resource should be granted or not. For RESTful-based resource servers,
that information is usually obtained from a security token, usually sent as a bearer token on every single request to the server. For web applications that rely on a session to
authenticate their users, that information is usually stored into user's session and retrieved from there on every single request.
In {{book.project.name}}, resource servers are provided with a rich platform for enabling fine-grained authorization to their protected resources, where authorization decisions can be made
based on different access control mechanisms.
You can see the list of resource servers by clicking on the `Authorization` left menu item.
.Resource Servers
image:../../images/resource-server/view.png[alt="Resource Servers"]
To create a new resource server just click on the `Create` button.
.Add Resource Server
image:../../images/resource-server/create.png[alt="Add Resource Server"]
Resource servers can be created manually or automatically based on the configuration within a JSON file.
When manually creating resource servers, the only required field is `Client`. This field allows you to choose an *existing* client applications that can be enabled as a resource server. In order to
make a client application available to this field, you need to make sure the client application is configured as follows:
* It must be a *confidential* client
* It must have a *Service Account*
[NOTE]
For more information about how to configure confidential clients and service accounts, please take a look at https://keycloak.gitbooks.io/server-adminstration-guide/[Server Administration Guide].
However, if you want to import an existing resource server configuration, you can click on the `Import JSON File` button and upload a JSON file holding the resource server configuration.
In any case, once you fill in the required fields you can click the `Save` button to create the resource server. This will bring you to the `Resource Server Settings` page.
.Resource Server Settings
image:../../images/resource-server/manage.png[alt="Resource Management"]
Let’s walk through each configuration item on this page.
* *Policy Enforcement Mode*
+
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.
+
* *Allow Remote Resource Management*
+
Should resources be managed remotely by the resource server? If false, resources can only be managed from this admin console.
+
* *Export Settings*
+
In this section you can export all settings to a JSON file. It provides a single `Export` button that you can click to
download a JSON file containing every single configuration defined for a resource server: protected resources, scopes, permissions and policies.
Any client application can be configured to support fine-grained permissions. When you do that, you are conceptually turning the client application into a resource server.

2
topics/resource/create.adoc
View file

@ -3,7 +3,7 @@
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.
To create a new resource click on the *Create* button in the right upper corner of the resource listing.
.Add Resource
image:../../images/resource/create.png[alt="Add Resource"]

5
topics/resource/view.adoc
View file

@ -13,4 +13,7 @@ The resource list provides some very useful information about the protected reso
* Associated scopes, if any
* Associated permissions
From there you can also create a permission right away by clicking on `Create Permission` button for the resources you want to create the permission.
From there you can also create a permission right away by clicking on `Create Permission` button for the resource you want to create the permission.
[NOTE]
Before creating permissions to your resources, make sure you already have any policy to associated with the permission.

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

@ -1,6 +1,10 @@
== What is a PAT and How to Obtain it ?
A PAT is a special OAuth2 Access Token with the scope *uma_protection*.
A PAT is a special OAuth2 Access Token with the scope *uma_protection*. When you create a resource server, {{book.project.name}} automatically
creates a role _uma_protection_ for the corresponding client application and associated it with the client's service account.
.Service Account granted with uma_protection role
image:../../../images/service/rs-uma-protection-role.png[alt="Service Account granted with uma_protection role"]
Resource servers can obtain a PAT from {{book.project.name}} just like any other OAuth2 Access Token.
@ -29,9 +33,4 @@ In the example above, we are using the *client_credentials* grant type to obtain
"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 service account of the client application that you want to use as a resource server.
```