From a645071f5f30646d3a368b2875b5bd4ccb908a40 Mon Sep 17 00:00:00 2001 From: Pedro Igor Date: Tue, 29 Nov 2016 13:30:53 -0200 Subject: [PATCH] [RHSSO-599] - Replacing link with fake --- SUMMARY.adoc | 2 +- topics/enforcer/authorization-context.adoc | 1 + topics/enforcer/js-adapter.adoc | 11 +++++---- .../enforcer/keycloak-enforcement-bearer.adoc | 1 + .../enforcer/keycloak-enforcement-filter.adoc | 9 ++++---- topics/enforcer/overview.adoc | 1 + topics/example/overview.adoc | 1 + .../hello-world/before-start.adoc | 2 +- .../hello-world/create-realm.adoc | 23 ++++++++++--------- .../hello-world/create-resource-server.adoc | 19 +++++++-------- .../getting-started/hello-world/deploy.adoc | 21 +++++++++-------- .../getting-started/hello-world/overview.adoc | 1 + topics/getting-started/overview.adoc | 3 ++- topics/overview/architecture.adoc | 23 ++++++++++--------- topics/overview/overview.adoc | 1 + topics/overview/terminology.adoc | 9 ++++---- topics/permission/create-resource.adoc | 5 ++-- topics/permission/create-scope.adoc | 3 ++- topics/permission/decision-strategy.adoc | 1 + topics/permission/overview.adoc | 1 + .../permission/typed-resource-permission.adoc | 5 ++-- topics/policy-evaluation-tool/overview.adoc | 1 + topics/policy/aggregated-policy.adoc | 5 ++-- topics/policy/drools-policy.adoc | 15 ++++++------ topics/policy/evaluation-api.adoc | 1 + topics/policy/js-policy.adoc | 7 +++--- topics/policy/logic.adoc | 1 + topics/policy/overview.adoc | 1 + topics/policy/role-policy-required-role.adoc | 1 + topics/policy/role-policy.adoc | 5 ++-- topics/policy/time-policy.adoc | 3 ++- topics/policy/user-policy.adoc | 3 ++- topics/resource-server/create-client.adoc | 17 +++++++------- topics/resource-server/default-config.adoc | 9 ++++---- .../resource-server/enable-authorization.adoc | 11 +++++---- topics/resource-server/import-config.adoc | 9 ++++---- topics/resource-server/overview.adoc | 1 + topics/resource/create.adoc | 7 +++--- topics/resource/overview.adoc | 1 + topics/resource/view.adoc | 1 + .../authorization/authorization-api-aapi.adoc | 5 ++-- .../authorization/authorization-api.adoc | 1 + .../authorization/whatis-obtain-aat.adoc | 1 + topics/service/client-api.adoc | 3 ++- .../entitlement/entitlement-api-aapi.adoc | 1 + .../service/entitlement/entitlement-api.adoc | 1 + .../entitlement/whatis-obtain-eat.adoc | 1 + topics/service/overview.adoc | 1 + .../protection/permission-api-papi.adoc | 5 ++-- topics/service/protection/protection-api.adoc | 3 ++- .../protection/resources-api-papi.adoc | 1 + .../protection/token-introspection.adoc | 7 +++--- .../service/protection/whatis-obtain-pat.adoc | 1 + 53 files changed, 162 insertions(+), 111 deletions(-) diff --git a/SUMMARY.adoc b/SUMMARY.adoc index efaecb73c9..168413df7b 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -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] \ No newline at end of file diff --git a/topics/enforcer/authorization-context.adoc b/topics/enforcer/authorization-context.adoc index 11053c8f51..48359d233d 100755 --- a/topics/enforcer/authorization-context.adoc +++ b/topics/enforcer/authorization-context.adoc @@ -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`. diff --git a/topics/enforcer/js-adapter.adoc b/topics/enforcer/js-adapter.adoc index b033d0f007..9685ca8362 100755 --- a/topics/enforcer/js-adapter.adoc +++ b/topics/enforcer/js-adapter.adoc @@ -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 <> 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: <> or <>. -* 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 <>. 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 <>. 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. diff --git a/topics/enforcer/keycloak-enforcement-bearer.adoc b/topics/enforcer/keycloak-enforcement-bearer.adoc index 67223ed1bf..d1b784cfd0 100755 --- a/topics/enforcer/keycloak-enforcement-bearer.adoc +++ b/topics/enforcer/keycloak-enforcement-bearer.adoc @@ -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 diff --git a/topics/enforcer/keycloak-enforcement-filter.adoc b/topics/enforcer/keycloak-enforcement-filter.adoc index 145b5c8259..07cbccb4b0 100644 --- a/topics/enforcer/keycloak-enforcement-filter.adoc +++ b/topics/enforcer/keycloak-enforcement-filter.adoc @@ -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 <> 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 <> 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 <> property that matches the paths you want to protect. + ** *user-managed-access* + diff --git a/topics/enforcer/overview.adoc b/topics/enforcer/overview.adoc index 09bc774a8a..855b46ac39 100755 --- a/topics/enforcer/overview.adoc +++ b/topics/enforcer/overview.adoc @@ -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 diff --git a/topics/example/overview.adoc b/topics/example/overview.adoc index 064517596f..a96e739ec6 100755 --- a/topics/example/overview.adoc +++ b/topics/example/overview.adoc @@ -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 diff --git a/topics/getting-started/hello-world/before-start.adoc b/topics/getting-started/hello-world/before-start.adoc index f36b86bdde..2d338a4862 100644 --- a/topics/getting-started/hello-world/before-start.adoc +++ b/topics/getting-started/hello-world/before-start.adoc @@ -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*. \ No newline at end of file diff --git a/topics/getting-started/hello-world/create-realm.adoc b/topics/getting-started/hello-world/create-realm.adoc index a06f9e5e27..289782aac7 100644 --- a/topics/getting-started/hello-world/create-realm.adoc +++ b/topics/getting-started/hello-world/create-realm.adoc @@ -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 <> 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. \ No newline at end of file +. Click *Reset Password* to set the user's password. \ No newline at end of file diff --git a/topics/getting-started/hello-world/create-resource-server.adoc b/topics/getting-started/hello-world/create-resource-server.adoc index 839822ba01..dfaae15e22 100644 --- a/topics/getting-started/hello-world/create-resource-server.adoc +++ b/topics/getting-started/hello-world/create-resource-server.adoc @@ -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 <> 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 <>. diff --git a/topics/getting-started/hello-world/deploy.adoc b/topics/getting-started/hello-world/deploy.adoc index 8d03d403ec..2f571476aa 100644 --- a/topics/getting-started/hello-world/deploy.adoc +++ b/topics/getting-started/hello-world/deploy.adoc @@ -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 <> 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}}. +<> 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 <>, <>, <>, <>, or <>, 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]. \ No newline at end of file +* For more information about how to view and test permissions inside your application see <>. \ No newline at end of file diff --git a/topics/getting-started/hello-world/overview.adoc b/topics/getting-started/hello-world/overview.adoc index 53db9e5e4f..c0ca28a44b 100644 --- a/topics/getting-started/hello-world/overview.adoc +++ b/topics/getting-started/hello-world/overview.adoc @@ -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}}. diff --git a/topics/getting-started/overview.adoc b/topics/getting-started/overview.adoc index a2d3b2e1ac..57a2bc44b2 100644 --- a/topics/getting-started/overview.adoc +++ b/topics/getting-started/overview.adoc @@ -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*. diff --git a/topics/overview/architecture.adoc b/topics/overview/architecture.adoc index 31bd988130..6ca2fcddb4 100755 --- a/topics/overview/architecture.adoc +++ b/topics/overview/architecture.adoc @@ -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 <>. + * **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. +<> and <> 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 <>. + * **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 <>. 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 <>. 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 <> 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 <>. ==== 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 <> 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 <>. === 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 <>. diff --git a/topics/overview/overview.adoc b/topics/overview/overview.adoc index 003ed20744..6fde41b379 100755 --- a/topics/overview/overview.adoc +++ b/topics/overview/overview.adoc @@ -1,3 +1,4 @@ +[[_overview]] == Overview {% if book.product %} diff --git a/topics/overview/terminology.adoc b/topics/overview/terminology.adoc index b8e44b625f..3069b02339 100755 --- a/topics/overview/terminology.adoc +++ b/topics/overview/terminology.adoc @@ -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. \ No newline at end of file +For more information on permission tickets, see <> and the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification. \ No newline at end of file diff --git a/topics/permission/create-resource.adoc b/topics/permission/create-resource.adoc index b33801e9e3..e7598b4ef1 100755 --- a/topics/permission/create-resource.adoc +++ b/topics/permission/create-resource.adoc @@ -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. \ No newline at end of file +The <> for this permission. \ No newline at end of file diff --git a/topics/permission/create-scope.adoc b/topics/permission/create-scope.adoc index 8e2f4802b6..2951c2b07e 100755 --- a/topics/permission/create-scope.adoc +++ b/topics/permission/create-scope.adoc @@ -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. \ No newline at end of file +The <> for this permission. \ No newline at end of file diff --git a/topics/permission/decision-strategy.adoc b/topics/permission/decision-strategy.adoc index a1478fa844..f8d660eced 100755 --- a/topics/permission/decision-strategy.adoc +++ b/topics/permission/decision-strategy.adoc @@ -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. diff --git a/topics/permission/overview.adoc b/topics/permission/overview.adoc index 2be69274c1..5cbd98df61 100755 --- a/topics/permission/overview.adoc +++ b/topics/permission/overview.adoc @@ -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. diff --git a/topics/permission/typed-resource-permission.adoc b/topics/permission/typed-resource-permission.adoc index a102669e19..54dd6d2777 100755 --- a/topics/permission/typed-resource-permission.adoc +++ b/topics/permission/typed-resource-permission.adoc @@ -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 <>. 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 <> 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 diff --git a/topics/policy-evaluation-tool/overview.adoc b/topics/policy-evaluation-tool/overview.adoc index fa9a5d1f00..68335918a9 100755 --- a/topics/policy-evaluation-tool/overview.adoc +++ b/topics/policy-evaluation-tool/overview.adoc @@ -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. diff --git a/topics/policy/aggregated-policy.adoc b/topics/policy/aggregated-policy.adoc index 08cc0cbf2f..9bbd220c14 100755 --- a/topics/policy/aggregated-policy.adoc +++ b/topics/policy/aggregated-policy.adoc @@ -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 <> of this policy to apply after the other conditions have been evaluated. === Decision Strategy for Aggregated Policies diff --git a/topics/policy/drools-policy.adoc b/topics/policy/drools-policy.adoc index 04cf048da0..2c9c39ee32 100644 --- a/topics/policy/drools-policy.adoc +++ b/topics/policy/drools-policy.adoc @@ -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 <>. -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 <> 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 <>. diff --git a/topics/policy/evaluation-api.adoc b/topics/policy/evaluation-api.adoc index 5142817509..6b1d39cc15 100755 --- a/topics/policy/evaluation-api.adoc +++ b/topics/policy/evaluation-api.adoc @@ -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. diff --git a/topics/policy/js-policy.adoc b/topics/policy/js-policy.adoc index 5de02ae927..a49bf75f36 100644 --- a/topics/policy/js-policy.adoc +++ b/topics/policy/js-policy.adoc @@ -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 <>. 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 <> 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 <>. diff --git a/topics/policy/logic.adoc b/topics/policy/logic.adoc index 8a9c700869..e43278c8ee 100644 --- a/topics/policy/logic.adoc +++ b/topics/policy/logic.adoc @@ -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. diff --git a/topics/policy/overview.adoc b/topics/policy/overview.adoc index 9dcdb7378c..70deb10c7e 100755 --- a/topics/policy/overview.adoc +++ b/topics/policy/overview.adoc @@ -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. diff --git a/topics/policy/role-policy-required-role.adoc b/topics/policy/role-policy-required-role.adoc index 5733d61ef4..1b5da6eda4 100644 --- a/topics/policy/role-policy-required-role.adoc +++ b/topics/policy/role-policy-required-role.adoc @@ -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 diff --git a/topics/policy/role-policy.adoc b/topics/policy/role-policy.adoc index 694dbc176a..030efc7f84 100644 --- a/topics/policy/role-policy.adoc +++ b/topics/policy/role-policy.adoc @@ -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 <> 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. \ No newline at end of file +The <> of this policy to apply after the other conditions have been evaluated. \ No newline at end of file diff --git a/topics/policy/time-policy.adoc b/topics/policy/time-policy.adoc index 6c99e377a3..2864f4dea9 100644 --- a/topics/policy/time-policy.adoc +++ b/topics/policy/time-policy.adoc @@ -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 <> 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. \ No newline at end of file diff --git a/topics/policy/user-policy.adoc b/topics/policy/user-policy.adoc index 383f384c44..910de5955f 100644 --- a/topics/policy/user-policy.adoc +++ b/topics/policy/user-policy.adoc @@ -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. \ No newline at end of file +The <> of this policy to apply after the other conditions have been evaluated. \ No newline at end of file diff --git a/topics/resource-server/create-client.adoc b/topics/resource-server/create-client.adoc index 8ab6e82491..b70b9b8e57 100755 --- a/topics/resource-server/create-client.adoc +++ b/topics/resource-server/create-client.adoc @@ -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"] \ No newline at end of file diff --git a/topics/resource-server/default-config.adoc b/topics/resource-server/default-config.adoc index bec14c57a7..de1deb96f7 100755 --- a/topics/resource-server/default-config.adoc +++ b/topics/resource-server/default-config.adoc @@ -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 <> 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 <> 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 <> 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 <>, defining a set of one or more policies that are applied to all resources with a given type. == Changing the Default Configuration diff --git a/topics/resource-server/enable-authorization.adoc b/topics/resource-server/enable-authorization.adoc index 6f4255a4bc..ea368906ab 100755 --- a/topics/resource-server/enable-authorization.adoc +++ b/topics/resource-server/enable-authorization.adoc @@ -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 <>. * *Scope* + -From this page, you can manage link:../resource/overview.html[scopes]. +From this page, you can manage <>. * *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 <> 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 <> 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 <> and view the result of the evaluation of the permissions and authorization policies you have defined. === Resource Server Settings diff --git a/topics/resource-server/import-config.adoc b/topics/resource-server/import-config.adoc index ea15825efc..69974db701 100755 --- a/topics/resource-server/import-config.adoc +++ b/topics/resource-server/import-config.adoc @@ -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"] diff --git a/topics/resource-server/overview.adoc b/topics/resource-server/overview.adoc index 5012725649..7c90562417 100755 --- a/topics/resource-server/overview.adoc +++ b/topics/resource-server/overview.adoc @@ -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. diff --git a/topics/resource/create.adoc b/topics/resource/create.adoc index 7821eb6c2c..9e8093279f 100755 --- a/topics/resource/create.adoc +++ b/topics/resource/create.adoc @@ -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 <> 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. diff --git a/topics/resource/overview.adoc b/topics/resource/overview.adoc index f54ebe3841..0d31bfe9c9 100755 --- a/topics/resource/overview.adoc +++ b/topics/resource/overview.adoc @@ -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. diff --git a/topics/resource/view.adoc b/topics/resource/view.adoc index e6ecb76af3..f6900472c2 100755 --- a/topics/resource/view.adoc +++ b/topics/resource/view.adoc @@ -1,3 +1,4 @@ +[[_resource_view]] === Viewing Resources On the *Resource* page, you see a list of the resources associated with a resource server. diff --git a/topics/service/authorization/authorization-api-aapi.adoc b/topics/service/authorization/authorization-api-aapi.adoc index 9738aeed16..372e5db742 100755 --- a/topics/service/authorization/authorization-api-aapi.adoc +++ b/topics/service/authorization/authorization-api-aapi.adoc @@ -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 <> with the resources you want to access +* The <> (as a bearer token) representing a user's identity and his consent to access authorization data on his behalf. ```bash curl -X POST diff --git a/topics/service/authorization/authorization-api.adoc b/topics/service/authorization/authorization-api.adoc index 97d683c184..d4e5cce374 100755 --- a/topics/service/authorization/authorization-api.adoc +++ b/topics/service/authorization/authorization-api.adoc @@ -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 diff --git a/topics/service/authorization/whatis-obtain-aat.adoc b/topics/service/authorization/whatis-obtain-aat.adoc index ad6f5297c2..fc2c9c26ba 100755 --- a/topics/service/authorization/whatis-obtain-aat.adoc +++ b/topics/service/authorization/whatis-obtain-aat.adoc @@ -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 diff --git a/topics/service/client-api.adoc b/topics/service/client-api.adoc index 7040bb523b..a62fb46134 100755 --- a/topics/service/client-api.adoc +++ b/topics/service/client-api.adoc @@ -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) + diff --git a/topics/service/entitlement/entitlement-api-aapi.adoc b/topics/service/entitlement/entitlement-api-aapi.adoc index 719d7cd164..fbaebde13c 100755 --- a/topics/service/entitlement/entitlement-api-aapi.adoc +++ b/topics/service/entitlement/entitlement-api-aapi.adoc @@ -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). diff --git a/topics/service/entitlement/entitlement-api.adoc b/topics/service/entitlement/entitlement-api.adoc index e642f7d797..faf9288933 100755 --- a/topics/service/entitlement/entitlement-api.adoc +++ b/topics/service/entitlement/entitlement-api.adoc @@ -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 diff --git a/topics/service/entitlement/whatis-obtain-eat.adoc b/topics/service/entitlement/whatis-obtain-eat.adoc index a357500b7b..f1e05482d7 100755 --- a/topics/service/entitlement/whatis-obtain-eat.adoc +++ b/topics/service/entitlement/whatis-obtain-eat.adoc @@ -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*. diff --git a/topics/service/overview.adoc b/topics/service/overview.adoc index e3b5fddbde..7de9d288ab 100755 --- a/topics/service/overview.adoc +++ b/topics/service/overview.adoc @@ -1,3 +1,4 @@ +[[_service_overview]] == Authorization Services {{book.project.name}} {{book.project.module}} are based on OAuth2's User-Managed Access (UMA) Profile. diff --git a/topics/service/protection/permission-api-papi.adoc b/topics/service/protection/permission-api-papi.adoc index d5e372eacb..225874b2df 100755 --- a/topics/service/protection/permission-api-papi.adoc +++ b/topics/service/protection/permission-api-papi.adoc @@ -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 <> 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 <> 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). \ No newline at end of file diff --git a/topics/service/protection/protection-api.adoc b/topics/service/protection/protection-api.adoc index a8db5efbd5..596dd0e2e7 100755 --- a/topics/service/protection/protection-api.adoc +++ b/topics/service/protection/protection-api.adoc @@ -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 <> to query the server for the resources that need protection. * *Permission Registration* + diff --git a/topics/service/protection/resources-api-papi.adoc b/topics/service/protection/resources-api-papi.adoc index e50db21d79..8acbf66525 100755 --- a/topics/service/protection/resources-api-papi.adoc +++ b/topics/service/protection/resources-api-papi.adoc @@ -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. diff --git a/topics/service/protection/token-introspection.adoc b/topics/service/protection/token-introspection.adoc index fbe16f9686..b908b903de 100755 --- a/topics/service/protection/token-introspection.adoc +++ b/topics/service/protection/token-introspection.adoc @@ -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 <> 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 <> and <> 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 <> 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 \ No newline at end of file diff --git a/topics/service/protection/whatis-obtain-pat.adoc b/topics/service/protection/whatis-obtain-pat.adoc index 8d8fe57036..98abb9364b 100755 --- a/topics/service/protection/whatis-obtain-pat.adoc +++ b/topics/service/protection/whatis-obtain-pat.adoc @@ -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