Merge pull request #35 from pedroigor/master
[RHSSO-599] - Replacing link with fake
This commit is contained in:
Pedro Igor
GitHub
commit
48cd884df5
53 changed files with 162 additions and 111 deletions
|
|
@ -46,7 +46,7 @@
|
|||
.. 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]
|
||||
.. link:topics/enforcer/keycloak-enforcement-filter.adoc[{{book.project.name}} Adapter Policy Enforcer]
|
||||
... link:topics/enforcer/keycloak-enforcement-bearer.adoc[Protecting a Stateless Service Using a Bearer Token]
|
||||
... link:topics/enforcer/authorization-context.adoc[Obtaining the Authorization Context]
|
||||
... link:topics/enforcer/js-adapter.adoc[JavaScript Integration]
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
[[_enforcer_authorization_context]]
|
||||
== Obtaining the Authorization Context
|
||||
|
||||
When policy enforcement is enabled, the permissions obtained from the server are available through `org.keycloak.AuthorizationContext`.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
[[_enforcer_js_adapter]]
|
||||
== JavaScript Integration
|
||||
|
||||
The {{book.project.name}} Server comes with a JavaScript library you can use to interact with a resource server protected by a policy enforcer.
|
||||
This library is based on the https://keycloak.gitbooks.io/securing-client-applications-guide/content/topics/oidc/javascript-adapter.html[Keycloak JavaScript adapter], which can be integrated to allow your client to obtain permissions from a {{book.project.name}} Server.
|
||||
This library is based on the https://keycloak.gitbooks.io/securing-client-applications-guide/content/topics/oidc/javascript-adapter.html[{{book.project.name}} JavaScript adapter], which can be integrated to allow your client to obtain permissions from a {{book.project.name}} Server.
|
||||
|
||||
You can obtain this library from a running a {{book.project.name}} Server instance by including the following `script` tag in your web page:
|
||||
|
||||
|
|
@ -16,18 +17,18 @@ var authorization = new KeycloakAuthorization(keycloak);
|
|||
```
|
||||
The *keycloak-authz.js* library provides two main features:
|
||||
|
||||
* Handle responses from a resource server protected by a link:overview.html[{{book.project.name}} policy enforcer] and obtain a requesting party token (RPT) with the necessary permissions to gain access to the protected resources on the resource server.
|
||||
* Handle responses from a resource server protected by a <<fake/../overview.adoc#_enforcer_overview, {{book.project.name}} Policy Enforcer>> and obtain a requesting party token (RPT) with the necessary permissions to gain access to the protected resources on the resource server.
|
||||
|
||||
** In this case, the library can handle whatever authorization protocol the resource server is using: link:../service/authorization/authorization-api.html[UMA] or link:../service/entitlement/entitlement-api.html[Entitlements].
|
||||
** In this case, the library can handle whatever authorization protocol the resource server is using: <<fake/../../service/authorization/authorization-api.adoc#_service_authorization_api, UMA>> or <<fake/../../service/entitlement/entitlement-api.adoc#_service_entitlement_api, Entitlements>>.
|
||||
|
||||
* Obtain permissions from a {{book.project.name}} Server using the link:../service/entitlement/entitlement-api.html[Entitlement API].
|
||||
* Obtain permissions from a {{book.project.name}} Server using the <<fake/../../service/entitlement/entitlement-api.adoc#_service_entitlement_api, Entitlement API>>.
|
||||
|
||||
In both cases, the library allows you to easily interact with both resource server and {{book.project.name}} {{book.project.module}} to obtain tokens with
|
||||
permissions your client can use as bearer tokens to access the protected resources on a resource server.
|
||||
|
||||
=== Handling Authorization Responses from a Resource Server
|
||||
|
||||
If a resource server is protected by a policy enforcer, it responds to client requests based on the permissions carried along with a link:keycloak-enforcement-bearer.html[bearer token].
|
||||
If a resource server is protected by a policy enforcer, it responds to client requests based on the permissions carried along with a <<fake/../keycloak-enforcement-bearer.adoc#_enforcer_bearer, bearer token>>.
|
||||
Typically, when you try to access a resource server with a bearer token that is lacking permissions to access a protected resource, the resource server
|
||||
responds with a *401* status code and a `WWW-Authenticate` header.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_enforcer_bearer]]
|
||||
== Protecting a Stateless Service Using a Bearer Token
|
||||
|
||||
If the adapter is configured with the `bearer-only` configuration option, the policy enforcer decides whether a request
|
||||
|
|
|
|||
|
|
@ -1,11 +1,12 @@
|
|||
== Keycloak Adapter Policy Enforcer
|
||||
[[_enforcer_filter]]
|
||||
== {{book.project.name}} Adapter Policy Enforcer
|
||||
|
||||
You can enforce authorization decisions for your applications if you are using {{book.project.name}} OIDC adapters.
|
||||
|
||||
When you enable policy enforcement for your {{book.project.name}} application, the corresponding adapter intercepts all requests to your application and enforces the authorization decisions obtained from the server.
|
||||
|
||||
Policy enforcement is strongly linked to your application's paths and the link:../resource/overview.html[resources] you created for a resource server using the {{book.project.name}} Administration Console. By default,
|
||||
when you create a resource server, {{book.project.name}} creates a link:../resource-server/default-config.html[default configuration] for your resource server so you can enable policy enforcement quickly.
|
||||
Policy enforcement is strongly linked to your application's paths and the <<fake/../../resource/overview.adoc#_resource_overview, resources>> you created for a resource server using the {{book.project.name}} Administration Console. By default,
|
||||
when you create a resource server, {{book.project.name}} creates a <<fake/../../resource-server/default-config.adoc#_resource_server_default_config, default configuration>> for your resource server so you can enable policy enforcement quickly.
|
||||
|
||||
The default configuration allows access for all resources in your application provided the authenticated user belongs to the same realm as the resource server being protected.
|
||||
|
||||
|
|
@ -67,7 +68,7 @@ Here is a description of each configuration option:
|
|||
* *policy-enforcer*
|
||||
+
|
||||
Specifies the configuration options that define how policies are actually enforced and optionally the paths you want to protect. If not specified, the policy enforcer queries the server
|
||||
for all resources associated with the resource server being protected. In this case, you need to ensure the resources are properly configured with a link:../resource/create.adoc#_uri[URI] property that matches the paths you want to protect.
|
||||
for all resources associated with the resource server being protected. In this case, you need to ensure the resources are properly configured with a <<fake/../../resource/create.adoc#_resource_create_uri, URI>> property that matches the paths you want to protect.
|
||||
+
|
||||
** *user-managed-access*
|
||||
+
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_enforcer_overview]]
|
||||
== Policy Enforcers
|
||||
|
||||
Policy Enforcement Point (PEP) is a design pattern and as such you can implement it in different ways. {{book.project.name}} provides all the necessary means
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_example_overview]]
|
||||
== Examples
|
||||
|
||||
The {{book.project.name}} Authorization can also help you to quickly get started with the authorization services and understand how to apply the same concepts to your
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ Ensure you have a {{book.project.name}} instance running; the default configurat
|
|||
Administration Console, a page similar to this one is displayed:
|
||||
|
||||
.{{book.project.name}} Administration Console
|
||||
image:../../images/getting-started/kc-start-page.png[alt="Keycloak Administration Console"]
|
||||
image:../../images/getting-started/kc-start-page.png[alt="{{book.project.name}} Administration Console"]
|
||||
|
||||
The source code for the getting started tutorials can be obtained from the demo distributions. The authorization-related examples
|
||||
are located at *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz*.
|
||||
|
|
@ -1,32 +1,33 @@
|
|||
[[_getting_started_hello_world_create_realm]]
|
||||
== Creating a Realm and a User
|
||||
|
||||
The first step is to create a realm and a user in that realm. The realm consists of:
|
||||
|
||||
* A single user
|
||||
|
||||
* A single client application, which then becomes a link:../../overview/terminology.html[resource server] for which you need to enable authorization services.
|
||||
* A single client application, which then becomes a <<fake/../../../overview/terminology.adoc#_overview_terminology, resource server>> for which you need to enable authorization services.
|
||||
|
||||
To create a realm and a user complete the following steps:
|
||||
|
||||
1. Create a realm with a name *hello-world-authz*. Once created, a page similar to the following is displayed:
|
||||
|
||||
. Create a realm with a name *hello-world-authz*. Once created, a page similar to the following is displayed:
|
||||
+
|
||||
.Realm hello-world-authz
|
||||
image:../../../images/getting-started/hello-world/create-realm.png[alt="Realm hello-world-authz"]
|
||||
|
||||
2. Create a user for your newly created realm. Click *Users*. The user list page opens.
|
||||
. Create a user for your newly created realm. Click *Users*. The user list page opens.
|
||||
|
||||
3. On the right side of the empty user list, click *Add User*.
|
||||
|
||||
4. Complete the fields as shown in the screenshot below to create a new user with the username of *alice* and then click *Save*.
|
||||
. On the right side of the empty user list, click *Add User*.
|
||||
|
||||
. Complete the fields as shown in the screenshot below to create a new user with the username of *alice* and then click *Save*.
|
||||
+
|
||||
.Add User
|
||||
image:../../../images/getting-started/hello-world/create-user.png[alt="Add User"]
|
||||
|
||||
5. Set a password for the *alice* user by clicking the *Credentials* tab.
|
||||
|
||||
. Set a password for the *alice* user by clicking the *Credentials* tab.
|
||||
+
|
||||
.Set User Password
|
||||
image:../../../images/getting-started/hello-world/reset-user-pwd.png[alt="Set User Password"]
|
||||
|
||||
6. Complete the *New Password* and *Password Confirmation* fields with a password and click the *Temporary* switch to *OFF*.
|
||||
. Complete the *New Password* and *Password Confirmation* fields with a password and click the *Temporary* switch to *OFF*.
|
||||
|
||||
7. Click *Reset Password* to set the user's password.
|
||||
. Click *Reset Password* to set the user's password.
|
||||
|
|
@ -1,27 +1,28 @@
|
|||
[[_getting_started_hello_world_enabling_authz_services]]
|
||||
== Enabling Authorization Services
|
||||
|
||||
You can enable authorization services in an existing client application configured to use the OpenID Connect Protocol. You can also create a new client.
|
||||
|
||||
To create a new client, complete the following steps:
|
||||
|
||||
1. Click *Clients* to start creating a new client application and fill in the fields as shown in the screenshot below:
|
||||
|
||||
. Click *Clients* to start creating a new client application and fill in the fields as shown in the screenshot below:
|
||||
+
|
||||
.Create Client Application
|
||||
image:../../../images/getting-started/hello-world/create-client.png[alt="Create Client Application"]
|
||||
|
||||
2. Click *Save*. The Client Details page is displayed.
|
||||
|
||||
. Click *Save*. The Client Details page is displayed.
|
||||
+
|
||||
.Client Details
|
||||
image:../../../images/getting-started/hello-world/enable-authz.png[alt="Client Details"]
|
||||
|
||||
3. On the Client Details page, click the *Authorization Enabled* switch to *ON*, and then click *Save*.
|
||||
. On the Client Details page, click the *Authorization Enabled* switch to *ON*, and then click *Save*.
|
||||
A new *Authorization* tab is displayed for the client.
|
||||
|
||||
4. Click the *Authorization* tab and an Authorization Settings page similar to the following is displayed:
|
||||
|
||||
. Click the *Authorization* tab and an Authorization Settings page similar to the following is displayed:
|
||||
+
|
||||
.Authorization Settings
|
||||
image:../../../images/getting-started/hello-world/authz-settings.png[alt="Authorization Settings"]
|
||||
|
||||
When you enable authorization services for a client application, {{book.project.name}} automatically creates several link:../../resource-server/default-config.html[default settings] for your client authorization configuration.
|
||||
When you enable authorization services for a client application, {{book.project.name}} automatically creates several <<fake/../../../resource-server/default-config.adoc#_resource_server_default_config, default settings>> for your client authorization configuration.
|
||||
|
||||
For more information about authorization configuration, see link:../../resource-server/enable-authorization.html[Enabling Authorization Services].
|
||||
For more information about authorization configuration, see <<fake/../../../resource-server/enable-authorization.adoc#_resource_server_enable_authorization, Enabling Authorization Services>>.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_getting_started_hello_world_deploy]]
|
||||
== Building, Deploying, and Testing Your Application
|
||||
|
||||
Now that the *hello-world-authz-service* resource server (or client) is properly configured and authorization services are enabled, it can be deployed to the server.
|
||||
|
|
@ -8,19 +9,19 @@ You must first obtain the adapter configuration before building and deploying th
|
|||
|
||||
To obtain the adapter configuration from the {{book.project.name}} Administration Console, complete the following steps.
|
||||
|
||||
1. Click *Clients*. In the client listing, click the *hello-world-authz-service* client application. The Client Details page opens.
|
||||
|
||||
. Click *Clients*. In the client listing, click the *hello-world-authz-service* client application. The Client Details page opens.
|
||||
+
|
||||
.Client Details
|
||||
image:../../../images/getting-started/hello-world/enable-authz.png[alt="Client Details"]
|
||||
|
||||
2. Click the *Installation* tab. From the Format Option dropdown list, select *Keycloak OIDC JSON*. The adapter configuration is displayed in JSON format. Click *Download*.
|
||||
|
||||
. Click the *Installation* tab. From the Format Option dropdown list, select *Keycloak OIDC JSON*. The adapter configuration is displayed in JSON format. Click *Download*.
|
||||
+
|
||||
.Adapter Configuration
|
||||
image:../../../images/getting-started/hello-world/adapter-config.png[alt="Adapter Configuration"]
|
||||
|
||||
3. Navigate to the *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/hello-world-authz-service/src/main/webapp/WEB-INF* directory and locate the *keycloak.json* file. Replace its contents with the adapter configuration you obtained from step 2 and save the file.
|
||||
. Navigate to the *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/hello-world-authz-service/src/main/webapp/WEB-INF* directory and locate the *keycloak.json* file. Replace its contents with the adapter configuration you obtained from step 2 and save the file.
|
||||
|
||||
4. (optional) By default, the policy enforcer responds with a `403` status code when the user lacks permission to access protected resources on the resource server. However, you can also specify a redirection URL for unauthorized users. To specify a redirection URL, edit the *keycloak.json* file you updated in step 3 and replace the `policy-enforcer` configuration with the following:
|
||||
. (optional) By default, the policy enforcer responds with a `403` status code when the user lacks permission to access protected resources on the resource server. However, you can also specify a redirection URL for unauthorized users. To specify a redirection URL, edit the *keycloak.json* file you updated in step 3 and replace the `policy-enforcer` configuration with the following:
|
||||
|
||||
```json
|
||||
"policy-enforcer": {
|
||||
|
|
@ -50,11 +51,11 @@ Log in as *alice* using the password you specified for that user. After authenti
|
|||
.Hello World Authz Main Page
|
||||
image:../../../images/getting-started/hello-world/main-page.png[alt="Hello World Authz Main Page"]
|
||||
|
||||
The link:../../resource-server/default-config.html[default settings] defined by {{book.project.name}} when you enable authorization services for a client application provide a simple
|
||||
The <<fake/../../../resource-server/default-config.adoc#_resource_server_default_config, default settings>> defined by {{book.project.name}} when you enable authorization services for a client application provide a simple
|
||||
policy that always grants access to the resources protected by this policy.
|
||||
|
||||
You can start by changing the default permissions and policies and test how your application responds, or even create new policies using the different
|
||||
link:../../policy/overview.html[policy types] provided by {{book.project.name}}.
|
||||
<<fake/../../../policy/overview.adoc#_policy_overview, policy types>> provided by {{book.project.name}}.
|
||||
|
||||
There are a plenty of things you can do now to test this application. For example, you can change the default policy by clicking the Authorization tab for the client, then `Policies` tab, then click on `Default Policy` in the list to allow you to change it as follows:
|
||||
|
||||
|
|
@ -77,6 +78,6 @@ That re-enables access to the application as we are negating the result of that
|
|||
There are additional things you can do, such as:
|
||||
|
||||
* Create a scope, define a policy and permission for it, and test it on the application side. Can the user perform an action (or anything else represented by the scope you created)?
|
||||
* Create different types of policies such as link:../../policy/role-policy.adoc[role-based], link:../../policy/user-policy.adoc[user-based], link:../../policy/time-policy.adoc[time-based], link:../../policy/aggregated-policy.adoc[aggregated policies], or link:../../policy/drools-policy.adoc[Drools-based], and associate these policies with the `Default Permission`.
|
||||
* Create different types of policies such as <<fake/../../../policy/role-policy.adoc#_policy_rbac, role-based>>, <<fake/../../../policy/user-policy.adoc#_policy_user, user-based>>, <<fake/../../../policy/time-policy.adoc#_policy_time, time-based>>, <<fake/../../../policy/aggregated-policy.adoc#_policy_aggregated, aggregated policies>>, or <<fake/../../../policy/drools-policy.adoc#_policy_drools, rule-based>>, and associate these policies with the `Default Permission`.
|
||||
* Apply multiple policies to the `Default Permission` and test the behavior. For example, combine multiple policies and change the `Decision Strategy` accordingly.
|
||||
* For more information about how to view and test permissions inside your application see link:../../enforcer/authorization-context.adoc[Obtaining the Authorization Context].
|
||||
* For more information about how to view and test permissions inside your application see <<fake/../../../enforcer/authorization-context.adoc#_enforcer_authorization_context, Obtaining the Authorization Context>>.
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
[[_getting_started_hello_world_overview]]
|
||||
== Hello World
|
||||
|
||||
The purpose of this getting started guide is to get you up and running as quickly as possible so that you can experiment with and test various authorization features provided by {{book.project.name}}.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_getting_started_overview]]
|
||||
== Getting Started
|
||||
|
||||
All tutorials are based on the *{{book.project.name}} Demo Distribution*.
|
||||
|
|
@ -14,7 +15,7 @@ Ensure you have a {{book.project.name}} instance running; the default configurat
|
|||
Administration Console, a page similar to this one is displayed:
|
||||
|
||||
.{{book.project.name}} Administration Console
|
||||
image:../../images/getting-started/kc-start-page.png[alt="Keycloak Administration Console"]
|
||||
image:../../images/getting-started/kc-start-page.png[alt="{{book.project.name}} Administration Console"]
|
||||
|
||||
All source code for the getting started tutorials can be obtained from the demo distributions. The authorization-related examples
|
||||
are located at *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz*.
|
||||
|
|
|
|||
|
|
@ -1,25 +1,26 @@
|
|||
[[_overview_architecture]]
|
||||
== Architecture
|
||||
|
||||
image:../../images/authz-arch-overview.png[alt="Keycloak AuthZ Architecture Overview"]
|
||||
image:../../images/authz-arch-overview.png[alt="{{book.project.name}} AuthZ Architecture Overview"]
|
||||
|
||||
From a design perspective, {{book.project.module}} is based on a well-defined set of authorization patterns providing these capabilities:
|
||||
|
||||
* **Policy Administration Point (PAP)**
|
||||
+
|
||||
Provides a set of UIs based on the {{book.project.name}} Administration Console to manage resource servers, resources, scopes, permissions, and policies.
|
||||
Part of this is also accomplished remotely through the use of the link:../service/protection/protection-api.adoc[Protection API].
|
||||
Part of this is also accomplished remotely through the use of the <<fake/../../service/protection/protection-api.adoc#_service_protection_api, Protection API>>.
|
||||
+
|
||||
|
||||
* **Policy Decision Point (PDP)**
|
||||
+
|
||||
Provides a distributable policy decision point to where authorization requests are sent and policies are evaluated accordingly with the permissions being requested. Part of this is also accomplished remotely through the use of the
|
||||
link:../service/authorization/authorization-api.adoc[Authorization] and link:../service/entitlement/entitlement-api.adoc[Entitlement] APIs.
|
||||
<<fake/../../service/authorization/authorization-api.adoc#_service_authorization_api, Authorization>> and <<fake/../../service/entitlement/entitlement-api.adoc#_service_entitlement_api, Entitlement>> APIs.
|
||||
+
|
||||
|
||||
* **Policy Enforcement Point (PEP)**
|
||||
+
|
||||
Provides implementations for different environments to actually enforce authorization decisions at the resource server side.
|
||||
Keycloak provides some built-in link:../enforcer/overview.html[Policy Enforcers].
|
||||
{{book.project.name}} provides some built-in <<fake/../../enforcer/overview.adoc#_enforcer_overview, Policy Enforcers>>.
|
||||
+
|
||||
|
||||
* **Policy Information Point (PIP)**
|
||||
|
|
@ -40,7 +41,7 @@ Three main processes define the necessary steps to understand how to use KC to e
|
|||
|
||||
image:../../images/resource-mgmt-process.png[alt="Resource Management Overview"]
|
||||
|
||||
First, you need to specify {{book.project.name}} what are you looking to protect, which usually represents a web application or a set of one or more services. For more information on resource servers see link:../overview/terminology.html[Terminology].
|
||||
First, you need to specify {{book.project.name}} what are you looking to protect, which usually represents a web application or a set of one or more services. For more information on resource servers see <<fake/../../overview/terminology.adoc#_overview_terminology, Terminology>>.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -50,7 +51,7 @@ A resource can be a web page, a RESTFul resource, a file in your file system, an
|
|||
|
||||
For instance, you might 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 might 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 the {{book.project.name}} Administration Console or the link:../service/protection/protection-api.adoc[Protection API]. In the latter case, resource servers are able to manage their resources remotely.
|
||||
Resources can be managed using the {{book.project.name}} Administration Console or the <<fake/../../service/protection/protection-api.adoc#_service_protection_api, 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 one or more attributes within a resource.
|
||||
|
||||
|
|
@ -77,7 +78,7 @@ what you want to protect (resource or scope) and the policies that must be satis
|
|||
|
||||
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.
|
||||
{{book.project.name}} provides some built-in <<fake/../../enforcer/overview.adoc#_enforcer_overview, Policy Enforcers>> implementations that you can use to protect your applications depending on the platform they are running on.
|
||||
|
||||
|
||||
=== Authorization Services
|
||||
|
|
@ -112,11 +113,11 @@ By default, Remote Resource Management is enabled. You can change that using the
|
|||
|
||||
When using the UMA protocol, the issuance of Permission Tickets by the Protection API is an important part of the whole authorization process. As described in a subsequent section, they represent the permissions being requested by the client and that are sent to the server 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.
|
||||
|
||||
For more information, see link:../service/protection/protection-api.adoc[Protection API].
|
||||
For more information, see <<fake/../../service/protection/protection-api.adoc#_service_protection_api, 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 Access Token and link:./terminology.adoc#_permission_ticket[Permission Ticket] with a Requesting Party Token (RPT).
|
||||
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 Access Token and <<fake/.././terminology.adoc#_overview_terminology_permission_ticket, Permission Ticket>> with a Requesting Party Token (RPT).
|
||||
|
||||
The RPT holds all permissions granted to a client and can be used to call a resource server to get access to its protected resources.
|
||||
|
||||
|
|
@ -125,7 +126,7 @@ within a permission ticket.
|
|||
|
||||
image:../../images/authz-calls.png[alt="Authorization API Overview"]
|
||||
|
||||
For more information, see link:../service/authorization/authorization-api.adoc[Authorization API].
|
||||
For more information, see <<fake/../../service/authorization/authorization-api.adoc#_service_authorization_api, Authorization API>>.
|
||||
|
||||
=== Entitlement API
|
||||
|
||||
|
|
@ -136,7 +137,7 @@ one or more resources.
|
|||
|
||||
image:../../images/entitlement-calls.png[alt="Entitlement API Overview"]
|
||||
|
||||
For more information see link:../service/entitlement/entitlement-api.adoc[Entitlement API].
|
||||
For more information see <<fake/../../service/entitlement/entitlement-api.adoc#_service_entitlement_api, Entitlement API>>.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_overview]]
|
||||
== Overview
|
||||
|
||||
{% if book.product %}
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_overview_terminology]]
|
||||
== Terminology
|
||||
|
||||
Before going further, it is important to understand these terms and concepts introduced by {{book.project.name}} {{book.project.module}}.
|
||||
|
|
@ -10,7 +11,7 @@ Resource servers usually rely on some kind of information to decide whether acce
|
|||
that information is usually carried in a security token, typically sent as a bearer token along with every request to the server. Web applications that rely on a session to
|
||||
authenticate users usually store that information in the user's session and retrieve it from there for each request.
|
||||
|
||||
In Keycloak, any *confidential* client application can act as a resource server. This client's resources and their respective scopes are protected and governed by a set of authorization policies.
|
||||
In {{book.project.name}}, any *confidential* client application can act as a resource server. This client's resources and their respective scopes are protected and governed by a set of authorization policies.
|
||||
|
||||
=== Resource
|
||||
|
||||
|
|
@ -50,7 +51,7 @@ but rather the conditions that must be satisfied for access to a given object (f
|
|||
Policies are strongly related to the different access control mechanisms (ACMs) that you can use to protect your resources.
|
||||
With policies, you can implement strategies for attribute-based access control (ABAC), role-based access control (RBAC), context-based access control, or any combination of these.
|
||||
|
||||
Keycloak leverages the concept of policies and how you define them by providing the concept of aggregated policies, where you can build a "policy of policies" and still control the behavior of the evaluation.
|
||||
{{book.project.name}} leverages the concept of policies and how you define them by providing the concept of aggregated policies, where you can build a "policy of policies" and still control the behavior of the evaluation.
|
||||
Instead of writing one large policy with all the conditions that must be satisfied for access to a given resource, the policies implementation in {{book.project.name}} {{book.project.module}} follows the divide-and-conquer technique.
|
||||
That is, you can create individual policies, then reuse them with different permissions and build more complex policies by combining individual policies.
|
||||
|
||||
|
|
@ -61,7 +62,7 @@ policy providers, and you can create your own policy types to support your speci
|
|||
|
||||
{{book.project.name}} provides a SPI (Service Provider Interface) that you can use to plug in your own policy provider implementations.
|
||||
|
||||
[[_permission_ticket]]
|
||||
[[_overview_terminology_permission_ticket]]
|
||||
=== Permission Ticket
|
||||
|
||||
A permission ticket is a special type of token defined by the https://docs.kantarainitiative.org/uma/rec-uma-core.html[OAuth2's User-Managed Access (UMA) Profile] specification that provides an opaque structure whose form is determined by the authorization server. This
|
||||
|
|
@ -71,4 +72,4 @@ In UMA, permission tickets are crucial to support person-to-person sharing and a
|
|||
|
||||
In the UMA workflow, permission tickets are issued by the authorization server to a resource server, which returns the permission ticket to the client trying to access a protected resource. Once the client receives the ticket, it can make a request for an RPT (a final token holding authorization data) by sending the ticket back to the authorization server.
|
||||
|
||||
For more information on permission tickets, see link:../service/authorization/authorization-api.html[Authorization API] and the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification.
|
||||
For more information on permission tickets, see <<fake/../../service/authorization/authorization-api.adoc#_service_authorization_api, Authorization API>> and the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification.
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
[[_permission_create_resource]]
|
||||
== Creating Resource-based Permissions
|
||||
|
||||
A resource-based permission defines a set of one or more resources to protect using a set of one or more authorization policies.
|
||||
|
|
@ -18,7 +19,7 @@ can identify them more easily.
|
|||
+
|
||||
A string containing details about this permission.
|
||||
|
||||
[[_apply_resource_type]]
|
||||
[[_permission_create_resource_apply_resource_type]]
|
||||
* *Apply To Resource Type*
|
||||
+
|
||||
Specifies if the permission is applied to all resources with a given type. When selecting this field, you are prompted to enter the resource type to protect.
|
||||
|
|
@ -37,4 +38,4 @@ Defines a set of one or more policies to associate with a permission.
|
|||
|
||||
* *Decision Strategy*
|
||||
+
|
||||
The link:decision-strategy.html[Decision Strategy] for this permission.
|
||||
The <<fake/../decision-strategy.adoc#_permission_decision_strategies, Decision Strategy>> for this permission.
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
[[_permission_create_scope]]
|
||||
== Creating Scope-based Permissions
|
||||
|
||||
A scope-based permission defines a set of one or more scopes to protect using a set of one or more authorization policies. Unlike resource-based permissions, you can use this permission type to create permissions not only for a resource, but also for the scopes associated with it, providing more granularity when defining the permissions that govern your resources and the actions that can be performed on them.
|
||||
|
|
@ -32,4 +33,4 @@ Defines a set of one or more policies to associate with a permission.
|
|||
|
||||
* *Decision Strategy*
|
||||
+
|
||||
The link:decision-strategy.html[Decision Strategy] for this permission.
|
||||
The <<fake/../decision-strategy.adoc#_permission_decision_strategies, Decision Strategy>> for this permission.
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
[[_permission_decision_strategies]]
|
||||
== Policy Decision Strategies
|
||||
|
||||
When associating policies with a permission, you can also define a decision strategy to specify how to evaluate the outcome of the associated policies to determine access.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_permission_overview]]
|
||||
== Managing Permissions
|
||||
|
||||
A permission associates the object being protected and the policies that must be evaluated to decide whether access should be granted.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
[[_permission_typed_resource]]
|
||||
== Typed Resource Permission
|
||||
|
||||
Resource permissions can also be used to define policies that are to be applied to all resources with a given link:../resource/create.adoc#_type[type]. This form of resource-based permission can be useful when you have resources sharing common access requirements and constraints.
|
||||
Resource permissions can also be used to define policies that are to be applied to all resources with a given <<fake/../../resource/create.adoc#_resource_create_type, type>>. This form of resource-based permission can be useful when you have resources sharing common access requirements and constraints.
|
||||
|
||||
Frequently, resources within an application can be categorized (or typed) based on the data they encapsulate or the functionality they provide. For example, a financial application can manage different banking accounts where each one belongs to a specific customer. Although they are different banking accounts, they share common security requirements and constraints that are globally defined by the banking organization. With typed resource permissions, you can define common policies to apply to all banking accounts, such as:
|
||||
|
||||
|
|
@ -8,7 +9,7 @@ Frequently, resources within an application can be categorized (or typed) based
|
|||
* Only allow access from the owner's country and/or region
|
||||
* Enforce a specific authentication method
|
||||
|
||||
To create a typed resource permission, click link:./create-resource.adoc#_apply_resource_type[Apply to Resource Type] when creating a new resource-based permission. With `Apply to Resource Type` set to `On`,
|
||||
To create a typed resource permission, click <<fake/../create-resource.adoc#_permission_create_resource_apply_resource_type, Apply to Resource Type>> when creating a new resource-based permission. With `Apply to Resource Type` set to `On`,
|
||||
you can specify the type that you want to protect as well as the policies that are to be applied to govern access to all resources with type you have specified.
|
||||
|
||||
.Example of a Typed Resource Permission
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_policy_evaluation_overview]]
|
||||
== Policy Evaluation Tool
|
||||
|
||||
When designing your policies, you can simulate authorization requests to test how your policies are being evaluated.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
[[_policy_aggregated]]
|
||||
== Aggregated Policies
|
||||
|
||||
As mentioned previously, Keycloak allows you to build a policy of policies, a concept referred to as policy aggregation. You can use policy aggregation to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the policies that are evaluated during the processing of authorization requests.
|
||||
As mentioned previously, {{book.project.name}} allows you to build a policy of policies, a concept referred to as policy aggregation. You can use policy aggregation to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the policies that are evaluated during the processing of authorization requests.
|
||||
|
||||
To create a new aggregated policy, select *Aggregated* in the dropdown list located in the right upper corner of the permission listing.
|
||||
|
||||
|
|
@ -36,7 +37,7 @@ The decision strategy for this permission.
|
|||
+
|
||||
* *Logic*
|
||||
+
|
||||
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.
|
||||
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
|
||||
|
||||
=== Decision Strategy for Aggregated Policies
|
||||
|
||||
|
|
|
|||
|
|
@ -1,13 +1,14 @@
|
|||
[[_policy_drools]]
|
||||
== Rule-Based Policy
|
||||
|
||||
With this type of policy you can define conditions for your permissions using http://www.drools.org[Drools], which is a rule evaluation environment. It is one of the _Rule-Based_ policy types
|
||||
supported by {{book.project.name}}, and provides flexibility to write any policy based on the link:evaluation-api.adoc[Evaluation API].
|
||||
supported by {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
|
||||
|
||||
To create a new Drools-based policy, in the dropdown list in the right upper corner of the permission listing,
|
||||
select *Drools*.
|
||||
To create a new Rule-based policy, in the dropdown list in the right upper corner of the permission listing,
|
||||
select *Rule*.
|
||||
|
||||
.Add Drools Policy
|
||||
image:../../images/policy/create-drools.png[alt="Add Drools Policy"]
|
||||
.Add Rule Policy
|
||||
image:../../images/policy/create-drools.png[alt="Add Rule Policy"]
|
||||
|
||||
=== Configuration
|
||||
|
||||
|
|
@ -50,7 +51,7 @@ Specifies an interval for scanning for artifact updates.
|
|||
+
|
||||
* *Logic*
|
||||
+
|
||||
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.
|
||||
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
|
||||
|
||||
=== Examples
|
||||
|
||||
|
|
@ -88,4 +89,4 @@ rule "Authorize Using Identity Information"
|
|||
end
|
||||
```
|
||||
|
||||
For more information about what you can access from the `org.keycloak.authorization.policy.evaluation.Evaluation` interface, see link:./evaluation-api.adoc[Evaluation API].
|
||||
For more information about what you can access from the `org.keycloak.authorization.policy.evaluation.Evaluation` interface, see <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_policy_evaluation_api]]
|
||||
== Evaluation API
|
||||
|
||||
When writing rule-based policies using JavaScript or JBoss Drools, {{book.project.name}} provides an Evaluation API that provides useful information to help determine whether a permission should be granted.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
[[_policy_js]]
|
||||
== JavaScript-Based Policy
|
||||
|
||||
You can use this type of policy to define conditions for your permissions using JavaScript. It is one of the rule-based policy types
|
||||
supported by {{book.project.name}}, and provides flexibility to write any policy based on the link:evaluation-api.adoc[Evaluation API].
|
||||
supported by {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
|
||||
|
||||
To create a new JavaScript-based policy, select *JavaScript* in the dropdown list in the upper right corner of the permission listing.
|
||||
|
||||
|
|
@ -25,7 +26,7 @@ The JavaScript code providing the conditions for this policy.
|
|||
+
|
||||
* *Logic*
|
||||
+
|
||||
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.
|
||||
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
|
||||
|
||||
=== Examples
|
||||
|
||||
|
|
@ -64,4 +65,4 @@ if (identity.hasRole('admin') || email.endsWith('@keycloak.org')) {
|
|||
}
|
||||
```
|
||||
|
||||
When writing your own rules, keep in mind that the *$evaluation* object is an object implementing *org.keycloak.authorization.policy.evaluation.Evaluation*. For more information about what you can access from this interface, see the link:evaluation-api.adoc[Evaluation API].
|
||||
When writing your own rules, keep in mind that the *$evaluation* object is an object implementing *org.keycloak.authorization.policy.evaluation.Evaluation*. For more information about what you can access from this interface, see the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_policy_logic]]
|
||||
== Positive and Negative Logic
|
||||
|
||||
Policies can be configured with positive or negative logic. Briefly, you can use this option to define whether the policy result should be kept as it is or be negated.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_policy_overview]]
|
||||
== Managing Policies
|
||||
|
||||
As mentioned previously, policies define the conditions that must be satisfied before granting access to an object.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_policy_rbac_required]]
|
||||
== Defining a Role as Required
|
||||
|
||||
When creating a role-based policy, you can specify a specific role as `Required`. When you do that, the policy will grant access
|
||||
|
|
|
|||
|
|
@ -1,8 +1,9 @@
|
|||
[[_policy_rbac]]
|
||||
== Role-Based Policy
|
||||
|
||||
You can use this type of policy to define conditions for your permissions where a set of one or more roles is permitted to access an object.
|
||||
|
||||
By default, roles added to this policy are not specified as required and the policy will grant access if the user requesting access has been granted any of these roles. However, you can specify a specific role as link:role-policy-required-role.adoc[required] if you want to enforce a specific role. You can also combine required and non-required roles, regardless of whether they are realm or client roles.
|
||||
By default, roles added to this policy are not specified as required and the policy will grant access if the user requesting access has been granted any of these roles. However, you can specify a specific role as <<fake/../role-policy-required-role.adoc#_policy_rbac_required, required>> if you want to enforce a specific role. You can also combine required and non-required roles, regardless of whether they are realm or client roles.
|
||||
|
||||
Role policies can be useful when you need more restricted role-based access control (RBAC), where specific roles must be enforced to grant access to an object. For instance, you can enforce that a user must consent to allowing a client application (which is acting on the user's behalf) to access the user's resources. You can use {{book.project.name}} Client Scope Mapping to enable consent pages or even enforce clients to explicitly provide a scope when obtaining access tokens from a {{book.project.name}} server.
|
||||
|
||||
|
|
@ -32,4 +33,4 @@ Specifies which *client* roles are permitted by this policy. To enable this fiel
|
|||
+
|
||||
* *Logic*
|
||||
+
|
||||
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.
|
||||
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
[[_policy_time]]
|
||||
== Time-Based Policy
|
||||
|
||||
You can use this type of policy to define time conditions for your permissions.
|
||||
|
|
@ -49,6 +50,6 @@ Defines the minute that access must be granted. You can also specify a range of
|
|||
+
|
||||
* *Logic*
|
||||
+
|
||||
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.
|
||||
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
|
||||
|
||||
Access is only granted if all conditions are satisfied. {{book.project.name}} will perform an _AND_ based on the outcome of each condition.
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
[[_policy_user]]
|
||||
== User-Based Policy
|
||||
|
||||
You can use this type of policy to define conditions for your permissions where a set of one or more users is permitted to access an object.
|
||||
|
|
@ -24,4 +25,4 @@ Specifies which users are given access by this policy.
|
|||
+
|
||||
* *Logic*
|
||||
+
|
||||
The link:logic.html[Logic] of this policy to apply after the other conditions have been evaluated.
|
||||
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.
|
||||
|
|
@ -1,27 +1,28 @@
|
|||
[[_resource_server_create_client]]
|
||||
== Creating a Client Application
|
||||
|
||||
The first step to enable {{book.project.name}} {{book.project.module}} is to create the client application that you want to turn into a resource server.
|
||||
|
||||
To create a client application, complete the following steps:
|
||||
|
||||
1. Click *Clients*.
|
||||
|
||||
. Click *Clients*.
|
||||
+
|
||||
.Clients
|
||||
image:../../images/resource-server/client-list.png[alt="Clients"]
|
||||
|
||||
2. On this page, click *Create*.
|
||||
|
||||
. On this page, click *Create*.
|
||||
+
|
||||
.Create Client
|
||||
image:../../images/resource-server/client-create.png[alt="Create Client"]
|
||||
|
||||
3. Type the `Client ID` of the client. For example, _my-resource-server_.
|
||||
4. Type the `Root URL` for your application. For example:
|
||||
. Type the `Client ID` of the client. For example, _my-resource-server_.
|
||||
. Type the `Root URL` for your application. For example:
|
||||
+
|
||||
```bash
|
||||
http://${host}:${port}/my-resource-server
|
||||
```
|
||||
|
||||
5. Click *Save*. The client is created and the client Settings page opens. A page similar to the following is displayed:
|
||||
|
||||
. Click *Save*. The client is created and the client Settings page opens. A page similar to the following is displayed:
|
||||
+
|
||||
.Client Settings
|
||||
image:../../images/resource-server/client-enable-authz.png[alt="Client Settings"]
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
[[_resource_server_default_config]]
|
||||
== Default Configuration
|
||||
|
||||
When you create a resource server, {{book.project.name}} creates a default configuration for your newly created resource server.
|
||||
|
|
@ -15,10 +16,10 @@ image:../../images/resource-server/default-resource.png[alt="Default Resource"]
|
|||
|
||||
This resource defines a `Type`, namely `urn:my-resource-server:resources:default` and a `URI` `/*`. Here, the `URI` field defines a
|
||||
wildcard pattern that indicates to {{book.project.name}} that this resource represents all the paths in your application. In other words,
|
||||
when enabling link:../enforcer/overview.html[policy enforcement] for your application, all the permissions associated with the resource
|
||||
when enabling <<fake/../../enforcer/overview.adoc#_enforcer_overview, policy enforcement>> for your application, all the permissions associated with the resource
|
||||
will be examined before granting access.
|
||||
|
||||
The `Type` mentioned previously defines a value that can be used to create link:../permission/typed-resource-permission.adoc[typed resource permissions] that must be applied
|
||||
The `Type` mentioned previously defines a value that can be used to create <<fake/../../permission/typed-resource-permission.adoc#_permission_typed_resource, typed resource permissions>> that must be applied
|
||||
to the default resource or any other resource you create using the same type.
|
||||
|
||||
The default policy is referred to as the *only from realm policy* and you can view it if you navigate to the *Policies* tab.
|
||||
|
|
@ -26,7 +27,7 @@ The default policy is referred to as the *only from realm policy* and you can vi
|
|||
.Default Policy
|
||||
image:../../images/resource-server/default-policy.png[alt="Default Policy"]
|
||||
|
||||
This policy is a link:../policy/js-policy.html[JavaScript-based policy] defining a condition that always grants access to the resources protected by this policy. If you click this policy you can see that it defines a rule as follows:
|
||||
This policy is a <<fake/../../policy/js-policy.adoc#_policy_js, JavaScript-based policy>> defining a condition that always grants access to the resources protected by this policy. If you click this policy you can see that it defines a rule as follows:
|
||||
|
||||
```js
|
||||
// by default, grants any permission associated with this policy
|
||||
|
|
@ -38,7 +39,7 @@ Lastly, the default permission is referred to as the *default permission* and yo
|
|||
.Default Permission
|
||||
image:../../images/resource-server/default-permission.png[alt="Default Permission"]
|
||||
|
||||
This permission is a link:../permission/overview.html[resource-based permission], defining a set of one or more policies that are applied to all resources with a given type.
|
||||
This permission is a <<fake/../../permission/create-resource.adoc#_permission_create_resource, resource-based permission>>, defining a set of one or more policies that are applied to all resources with a given type.
|
||||
|
||||
== Changing the Default Configuration
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_resource_server_enable_authorization]]
|
||||
== Enabling Authorization Services
|
||||
|
||||
To turn your OIDC Client Application into a resource server and enable fine-grained authorization, click the *Authorization Enabled* switch to *ON* and click *Save*.
|
||||
|
|
@ -18,23 +19,23 @@ General settings for your resource server. More details about this page in this
|
|||
|
||||
* *Resource*
|
||||
+
|
||||
From this page, you can manage your application's link:../resource/overview.html[resources].
|
||||
From this page, you can manage your application's <<fake/../../resource/overview.adoc#_resource_overview, resources>>.
|
||||
|
||||
* *Scope*
|
||||
+
|
||||
From this page, you can manage link:../resource/overview.html[scopes].
|
||||
From this page, you can manage <<fake/../../resource/overview.adoc#_resource_overview, scopes>>.
|
||||
|
||||
* *Policies*
|
||||
+
|
||||
From this page, you can manage link:../policy/overview.html[authorization policies] and define the conditions that must be met to grant a permission.
|
||||
From this page, you can manage <<fake/../../policy/overview.adoc#_policy_overview, authorization policies>> and define the conditions that must be met to grant a permission.
|
||||
|
||||
* *Permissions*
|
||||
+
|
||||
From this page, you can manage the link:../permission/overview.html[permissions] for your protected resources and scopes by linking them with the policies you created.
|
||||
From this page, you can manage the <<fake/../../permission/overview.adoc#_permission_overview, permissions>> for your protected resources and scopes by linking them with the policies you created.
|
||||
|
||||
* *Evaluate*
|
||||
+
|
||||
From this page, you can link:../policy-evaluation-tool/overview.html[simulate authorization requests] and view the result of the evaluation of the permissions and authorization policies you have defined.
|
||||
From this page, you can <<fake/../../policy-evaluation-tool/overview.adoc#_policy_evaluation_overview, simulate authorization requests>> and view the result of the evaluation of the permissions and authorization policies you have defined.
|
||||
|
||||
=== Resource Server Settings
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_resource_server_import_config]]
|
||||
== Exporting and Importing Configuration Files
|
||||
|
||||
The configuration settings for a resource server (or client) can be exported and downloaded. You can also import an existing configuration file for a resource server. Importing and exporting a configuration file is helpful when you want to create an initial configuration for a resource server or to update an existing configuration. The configuration file contains definitions for:
|
||||
|
|
@ -10,13 +11,13 @@ The configuration settings for a resource server (or client) can be exported and
|
|||
|
||||
To export a configuration file, complete the following steps:
|
||||
|
||||
1. Navigate to the *Resource Server Settings* page.
|
||||
|
||||
. Navigate to the *Resource Server Settings* page.
|
||||
+
|
||||
.Resource Server Settings
|
||||
image:../../images/resource-server/authz-settings.png[alt="Resource Server Settings"]
|
||||
|
||||
2. On this page, in the Export Settings section, click *Export*.
|
||||
|
||||
. On this page, in the Export Settings section, click *Export*.
|
||||
+
|
||||
.Export Settings
|
||||
image:../../images/resource-server/authz-export.png[alt="Export Settings"]
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_resource_server_overview]]
|
||||
== Managing Resource Servers
|
||||
|
||||
According to the OAuth2 specification, a resource server is a server hosting the protected resources and capable of accepting and responding to protected resource requests.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_resource_create]]
|
||||
== Creating Resources
|
||||
|
||||
Creating a resource is straightforward and generic. Your main concern is the granularity of the resources you create. In other words, resources can
|
||||
|
|
@ -14,13 +15,13 @@ In {{book.project.name}}, a resource defines a small set of information that is
|
|||
+
|
||||
A human-readable and unique string describing this resource.
|
||||
|
||||
[[_type]]
|
||||
[[_resource_create_type]]
|
||||
* *Type*
|
||||
+
|
||||
A string uniquely identifying the type of a set of one or more resources. The type is a _string_ used to group different resource instances.
|
||||
For example, the default type for the default resource that is automatically created is `urn:resource-server-name:resources:default`
|
||||
|
||||
[[_uri]]
|
||||
[[_resource_create_uri]]
|
||||
* *URI*
|
||||
+
|
||||
A URI that provides the location/address for the resource. For HTTP resources, the URI
|
||||
|
|
@ -41,7 +42,7 @@ However, resources can also be associated with users, so you can create permissi
|
|||
|
||||
=== Managing Resources Remotely
|
||||
|
||||
Resource management is also exposed through the link:../service/protection/protection-api.html[Protection API] to allow resource servers to remotely manage their resources.
|
||||
Resource management is also exposed through the <<fake/../../service/protection/protection-api.adoc#_service_protection_api, 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.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_resource_overview]]
|
||||
== Managing Resources and Scopes
|
||||
|
||||
Resource management is straightforward and generic. After creating a resource server, you can start creating the resources and scopes that you want to protect.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_resource_view]]
|
||||
=== Viewing Resources
|
||||
|
||||
On the *Resource* page, you see a list of the resources associated with a resource server.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_authorization_api_aapi]]
|
||||
== Requesting Authorization Data and Token
|
||||
|
||||
Client applications using the UMA protocol can use a specific endpoint to obtain a special security token called a requesting party token (RPT).
|
||||
|
|
@ -10,8 +11,8 @@ http://${host}:${port}/auth/realms/${realm_name}/authz/authorize
|
|||
|
||||
When requesting an RPT, you need to provide two things:
|
||||
|
||||
* A link:../protection/permission-api-papi.adoc[permission ticket] with the resources you want to access
|
||||
* The link:./whatis-obtain-aat.adoc[authorization API token (AAT)] (as a bearer token) representing a user's identity and his consent to access authorization data on his behalf.
|
||||
* A <<fake/../../protection/permission-api-papi.adoc#_service_protection_permission_api_papi, permission ticket>> with the resources you want to access
|
||||
* The <<fake/../whatis-obtain-aat.adoc#_service_authorization_aat, authorization API token (AAT)>> (as a bearer token) representing a user's identity and his consent to access authorization data on his behalf.
|
||||
|
||||
```bash
|
||||
curl -X POST
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_authorization_api]]
|
||||
== Authorization API
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_authorization_aat]]
|
||||
== Authorization API Token
|
||||
|
||||
An authorization API token (AAT) is a special OAuth2 access token with the scope *uma_authorization*. When you create a user, {{book.project.name}} automatically
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_client_api]]
|
||||
== Authorization Client API
|
||||
|
||||
If you are using Java, you can access all {{book.project.name}} {{book.project.module}} using a client API.
|
||||
|
|
@ -35,7 +36,7 @@ The name of the realm.
|
|||
|
||||
* *auth-server-url* (required)
|
||||
+
|
||||
The base URL of the Keycloak server. All other Keycloak pages and REST service endpoints are derived from this. It is usually in the form https://host:port/auth.
|
||||
The base URL of the {{book.project.name}} server. All other {{book.project.name}} pages and REST service endpoints are derived from this. It is usually in the form https://host:port/auth.
|
||||
|
||||
* *resource* (required)
|
||||
+
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_entitlement_api_aapi]]
|
||||
== Requesting Entitlements
|
||||
|
||||
Client applications can use a specific endpoint to obtain a special security token called a requesting party token (RPT).
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_entitlement_api]]
|
||||
== Entitlement API
|
||||
|
||||
The Entitlement API provides a 1-legged protocol for obtaining authorization data from the server, where the authorization data
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_entitlement_whatis_obtain_eat]]
|
||||
== Entitlement API Tokens
|
||||
|
||||
An entitlement API token (EAT) is a special OAuth2 access token with the scope *kc_entitlement*.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_overview]]
|
||||
== Authorization Services
|
||||
|
||||
{{book.project.name}} {{book.project.module}} are based on OAuth2's User-Managed Access (UMA) Profile.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_protection_permission_api_papi]]
|
||||
== Managing Permission Requests
|
||||
|
||||
Resource servers using the UMA protocol can use a specific endpoint to manage permission requests. This endpoint provides a UMA-compliant flow for registering permission requests and obtaining a permission ticket.
|
||||
|
|
@ -6,7 +7,7 @@ Resource servers using the UMA protocol can use a specific endpoint to manage pe
|
|||
http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission
|
||||
```
|
||||
|
||||
A link:../../overview/terminology.adoc#_permission_ticket[permission ticket] is a special security token type representing a permission request. Per the UMA specification, a permission ticket is:
|
||||
A <<fake/../../../overview/terminology.adoc#_overview_terminology_permission_ticket, permission ticket>> is a special security token type representing a permission request. Per the UMA specification, a permission ticket is:
|
||||
|
||||
`A correlation handle that is conveyed from an authorization server to a resource server, from a resource server to a client, and ultimately from a client back to an authorization server, to enable the authorization server to assess the correct policies to apply to a request for authorization data.`
|
||||
|
||||
|
|
@ -14,5 +15,5 @@ A link:../../overview/terminology.adoc#_permission_ticket[permission ticket] is
|
|||
_Permission ticket support is limited_.
|
||||
In the full UMA protocol, resource servers can register permission requests in the server to support authorization flows where a resource owner (the user that owns a resource being requested) can approve access to his resources by third parties, among other ways. This represents one of the main features of the UMA specification: resource owners can control their own resources and the policies that govern them. Currently {{book.project.name}} UMA implementation support is very limited in this regard. For example, the system does not store permission tickets on the server and we are essentially using UMA to provide API security and base our authorization offerings. In the future, full support of UMA and other use cases is planned.
|
||||
|
||||
In most cases, you won't need to deal with this endpoint directly. {{book.project.name}} provides a link:../enforcer/overview.html[policy enforcer] that enables UMA for your
|
||||
In most cases, you won't need to deal with this endpoint directly. {{book.project.name}} provides a <<fake/../../../enforcer/overview.adoc#_enforcer_overview, policy enforcer>> that enables UMA for your
|
||||
resource server so it can obtain a permission ticket from the authorization server, return this ticket to client application, and enforce authorization decisions based on a final requesting party token (RPT).
|
||||
|
|
@ -1,10 +1,11 @@
|
|||
[[_service_protection_api]]
|
||||
== Protection API
|
||||
|
||||
The Protection API provides a UMA-compliant set of endpoints providing:
|
||||
|
||||
* *Resource Registration*
|
||||
+
|
||||
With this endpoint, resource servers can manage their resources remotely and enable link::../../../../enforcer/overview.adoc[policy enforcers] to query the server for the resources that need protection.
|
||||
With this endpoint, resource servers can manage their resources remotely and enable <<fake/../../../enforcer/overview.adoc#_enforcer_overview, policy enforcers>> to query the server for the resources that need protection.
|
||||
|
||||
* *Permission Registration*
|
||||
+
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_protection_resources_api]]
|
||||
== Managing Resources Using the Protection API
|
||||
|
||||
Resource servers can manage their resources remotely using a UMA-compliant endpoint.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_protection_token_introspection]]
|
||||
== Introspecting a Requesting Party Token
|
||||
|
||||
Sometimes you might want to introspect a requesting party token (RPT) to check its validity or obtain the permissions within the token to enforce authorization decisions on the resource server side.
|
||||
|
|
@ -5,7 +6,7 @@ Sometimes you might want to introspect a requesting party token (RPT) to check i
|
|||
There are two main use cases where token introspection can help you:
|
||||
|
||||
* When client applications need to query the token validity to obtain a new one with the same or additional permissions
|
||||
* When enforcing authorization decisions at the resource server side, especially when none of the built-in link:../../enforcer/overview.html[policy enforcers] fits your application
|
||||
* When enforcing authorization decisions at the resource server side, especially when none of the built-in <<fake/../../../enforcer/overview.adoc#_enforcer_overview, policy enforcers>> fits your application
|
||||
|
||||
=== Obtaining Information about a RPT
|
||||
|
||||
|
|
@ -66,13 +67,13 @@ If the RPT is not active, this response is returned instead:
|
|||
|
||||
=== Do I Need to Invoke the Server Every Time I want to Introspect a RPT?
|
||||
|
||||
No. Both link:../../service/authorization/authorization-api.html[Authorization] and link:../../service/entitlement/entitlement-api.html[Entitlement] APIs use the
|
||||
No. Both <<fake/../../../service/authorization/authorization-api.adoc#_service_authorization_api, Authorization>> and <<fake/../../../service/entitlement/entitlement-api.adoc#_service_entitlement_api, Entitlement>> APIs use the
|
||||
https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] specification as the default format for RPTs.
|
||||
|
||||
If you want to validate these tokens without a call to the remote introspection endpoint, you can decode the RPT and query for its validity locally. Once you decode the token,
|
||||
you can also use the permissions within the token to enforce authorization decisions.
|
||||
|
||||
This is essentially what the link:../../enforcer/overview.html[policy enforcers] do. Be sure to:
|
||||
This is essentially what the <<fake/../../../enforcer/overview.adoc#_enforcer_overview, policy enforcers>> do. Be sure to:
|
||||
|
||||
* Validate the signature of the RPT (based on the realm's public key)
|
||||
* Query for token validity based on its _exp_, _iat_, and _aud_ claims
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
[[_service_protection_whatis_obtain_pat]]
|
||||
== What is a PAT and How to Obtain It?
|
||||
|
||||
A *protection API token* (PAT) is a special OAuth2 access token with a scope defined as *uma_protection*. When you create a resource server, {{book.project.name}} automatically
|
||||
|
|
|
|||
Loading…
Reference in a new issue