From de7a1403ce99cf00cd0a58ce9ce933ddba5cc3c1 Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Mon, 9 Oct 2017 08:38:46 +0200 Subject: [PATCH] Convert Authorization Service to a flat topic structure (#212) * Convert Authorization Service to a flat topic structure * Fix issue with toc being cut --- aggregation/navbar-head.html | 2 + authorization_services/index.adoc | 6 +- authorization_services/master.adoc | 2 +- authorization_services/topics.adoc | 114 +++++++++--------- ...e.adoc => auth-services-architecture.adoc} | 22 ++-- ...rview.adoc => auth-services-overview.adoc} | 4 +- ...gy.adoc => auth-services-terminology.adoc} | 19 +-- ...oc => enforcer-authorization-context.adoc} | 6 +- .../https.adoc => enforcer-https.adoc} | 3 +- ...-adapter.adoc => enforcer-js-adapter.adoc} | 8 +- ...enforcer-keycloak-enforcement-bearer.adoc} | 6 +- ...enforcer-keycloak-enforcement-filter.adoc} | 4 +- .../overview.adoc => enforcer-overview.adoc} | 4 +- .../overview.adoc => example-overview.adoc} | 2 +- ...iew.adoc => getting-started-overview.adoc} | 2 +- ...art.adoc => hello-world-before-start.adoc} | 4 +- ...alm.adoc => hello-world-create-realm.adoc} | 2 +- ...> hello-world-create-resource-server.adoc} | 4 +- .../deploy.adoc => hello-world-deploy.adoc} | 14 +-- ...verview.adoc => hello-world-overview.adoc} | 4 +- ...e.adoc => permission-create-resource.adoc} | 6 +- ...cope.adoc => permission-create-scope.adoc} | 6 +- ...adoc => permission-decision-strategy.adoc} | 4 +- ...overview.adoc => permission-overview.adoc} | 4 +- ...permission-typed-resource-permission.adoc} | 4 +- ...icy.adoc => policy-aggregated-policy.adoc} | 8 +- ...-policy.adoc => policy-client-policy.adoc} | 6 +- ...-policy.adoc => policy-drools-policy.adoc} | 6 +- ...on-api.adoc => policy-evaluation-api.adoc} | 4 +- ...c => policy-evaluation-tool-overview.adoc} | 10 +- ... policy-group-policy-extend-children.adoc} | 2 +- ...p-policy.adoc => policy-group-policy.adoc} | 4 +- .../js-policy.adoc => policy-js-policy.adoc} | 6 +- .../{policy/logic.adoc => policy-logic.adoc} | 4 +- .../overview.adoc => policy-overview.adoc} | 4 +- ... => policy-role-policy-required-role.adoc} | 4 +- ...le-policy.adoc => policy-role-policy.adoc} | 6 +- ...me-policy.adoc => policy-time-policy.adoc} | 6 +- ...er-policy.adoc => policy-user-policy.adoc} | 6 +- .../create.adoc => resource-create.adoc} | 10 +- .../overview.adoc => resource-overview.adoc} | 4 +- ...doc => resource-server-create-client.adoc} | 4 +- ...oc => resource-server-default-config.adoc} | 4 +- ...resource-server-enable-authorization.adoc} | 6 +- ...doc => resource-server-import-config.adoc} | 8 +- ...iew.adoc => resource-server-overview.adoc} | 4 +- .../view.adoc => resource-view.adoc} | 4 +- ...authorization-authorization-api-aapi.adoc} | 4 +- ...vice-authorization-authorization-api.adoc} | 4 +- ...vice-authorization-whatis-obtain-aat.adoc} | 4 +- ...lient-api.adoc => service-client-api.adoc} | 18 +-- ...ice-entitlement-entitlement-api-aapi.adoc} | 10 +- ... service-entitlement-entitlement-api.adoc} | 2 +- ...tlement-entitlement-request-metadata.adoc} | 8 +- ...ervice-entitlement-whatis-obtain-eat.adoc} | 4 +- .../overview.adoc => service-overview.adoc} | 4 +- ...rvice-protection-permission-api-papi.adoc} | 4 +- ...=> service-protection-protection-api.adoc} | 4 +- ...ervice-protection-resources-api-papi.adoc} | 4 +- .../service-protection-resources-api.adoc | 19 +++ ...service-protection-whatis-obtain-pat.adoc} | 4 +- ...verview.adoc => service-rpt-overview.adoc} | 4 +- ...c => service-rpt-token-introspection.adoc} | 8 +- 63 files changed, 248 insertions(+), 233 deletions(-) rename authorization_services/topics/{overview/architecture.adoc => auth-services-architecture.adoc} (97%) rename authorization_services/topics/{overview/overview.adoc => auth-services-overview.adoc} (99%) rename authorization_services/topics/{overview/terminology.adoc => auth-services-terminology.adoc} (97%) rename authorization_services/topics/{enforcer/authorization-context.adoc => enforcer-authorization-context.adoc} (95%) rename authorization_services/topics/{enforcer/https.adoc => enforcer-https.adoc} (94%) rename authorization_services/topics/{enforcer/js-adapter.adoc => enforcer-js-adapter.adoc} (97%) rename authorization_services/topics/{enforcer/keycloak-enforcement-bearer.adoc => enforcer-keycloak-enforcement-bearer.adoc} (94%) rename authorization_services/topics/{enforcer/keycloak-enforcement-filter.adoc => enforcer-keycloak-enforcement-filter.adoc} (98%) rename authorization_services/topics/{enforcer/overview.adoc => enforcer-overview.adoc} (85%) rename authorization_services/topics/{example/overview.adoc => example-overview.adoc} (99%) rename authorization_services/topics/{getting-started/overview.adoc => getting-started-overview.adoc} (98%) rename authorization_services/topics/{getting-started/hello-world/before-start.adoc => hello-world-before-start.adoc} (91%) rename authorization_services/topics/{getting-started/hello-world/create-realm.adoc => hello-world-create-realm.adoc} (97%) rename authorization_services/topics/{getting-started/hello-world/create-resource-server.adoc => hello-world-create-resource-server.adoc} (97%) rename authorization_services/topics/{getting-started/hello-world/deploy.adoc => hello-world-deploy.adoc} (95%) rename authorization_services/topics/{getting-started/hello-world/overview.adoc => hello-world-overview.adoc} (90%) rename authorization_services/topics/{permission/create-resource.adoc => permission-create-resource.adoc} (94%) rename authorization_services/topics/{permission/create-scope.adoc => permission-create-scope.adoc} (95%) rename authorization_services/topics/{permission/decision-strategy.adoc => permission-decision-strategy.adoc} (95%) rename authorization_services/topics/{permission/overview.adoc => permission-overview.adoc} (93%) rename authorization_services/topics/{permission/typed-resource-permission.adoc => permission-typed-resource-permission.adoc} (94%) rename authorization_services/topics/{policy/aggregated-policy.adoc => policy-aggregated-policy.adoc} (96%) rename authorization_services/topics/{policy/client-policy.adoc => policy-client-policy.adoc} (91%) rename authorization_services/topics/{policy/drools-policy.adoc => policy-drools-policy.adoc} (98%) rename authorization_services/topics/{policy/evaluation-api.adoc => policy-evaluation-api.adoc} (98%) rename authorization_services/topics/{policy-evaluation-tool/overview.adoc => policy-evaluation-tool-overview.adoc} (85%) rename authorization_services/topics/{policy/group-policy-extend-children.adoc => policy-group-policy-extend-children.adoc} (94%) rename authorization_services/topics/{policy/group-policy.adoc => policy-group-policy.adoc} (97%) rename authorization_services/topics/{policy/js-policy.adoc => policy-js-policy.adoc} (97%) rename authorization_services/topics/{policy/logic.adoc => policy-logic.adoc} (93%) rename authorization_services/topics/{policy/overview.adoc => policy-overview.adoc} (96%) rename authorization_services/topics/{policy/role-policy-required-role.adoc => policy-role-policy-required-role.adoc} (93%) rename authorization_services/topics/{policy/role-policy.adoc => policy-role-policy.adoc} (96%) rename authorization_services/topics/{policy/time-policy.adoc => policy-time-policy.adoc} (98%) rename authorization_services/topics/{policy/user-policy.adoc => policy-user-policy.adoc} (91%) rename authorization_services/topics/{resource/create.adoc => resource-create.adoc} (95%) rename authorization_services/topics/{resource/overview.adoc => resource-overview.adoc} (78%) rename authorization_services/topics/{resource-server/create-client.adoc => resource-server-create-client.adoc} (94%) rename authorization_services/topics/{resource-server/default-config.adoc => resource-server-default-config.adoc} (97%) rename authorization_services/topics/{resource-server/enable-authorization.adoc => resource-server-enable-authorization.adoc} (97%) rename authorization_services/topics/{resource-server/import-config.adoc => resource-server-import-config.adoc} (90%) rename authorization_services/topics/{resource-server/overview.adoc => resource-server-overview.adoc} (89%) rename authorization_services/topics/{resource/view.adoc => resource-view.adoc} (94%) rename authorization_services/topics/{service/authorization/authorization-api-aapi.adoc => service-authorization-authorization-api-aapi.adoc} (96%) rename authorization_services/topics/{service/authorization/authorization-api.adoc => service-authorization-authorization-api.adoc} (85%) rename authorization_services/topics/{service/authorization/whatis-obtain-aat.adoc => service-authorization-whatis-obtain-aat.adoc} (97%) rename authorization_services/topics/{service/client-api.adoc => service-client-api.adoc} (95%) rename authorization_services/topics/{service/entitlement/entitlement-api-aapi.adoc => service-entitlement-entitlement-api-aapi.adoc} (97%) rename authorization_services/topics/{service/entitlement/entitlement-api.adoc => service-entitlement-entitlement-api.adoc} (96%) rename authorization_services/topics/{service/entitlement/entitlement-request-metadata.adoc => service-entitlement-entitlement-request-metadata.adoc} (94%) rename authorization_services/topics/{service/entitlement/whatis-obtain-eat.adoc => service-entitlement-whatis-obtain-eat.adoc} (96%) rename authorization_services/topics/{service/overview.adoc => service-overview.adoc} (79%) rename authorization_services/topics/{service/protection/permission-api-papi.adoc => service-protection-permission-api-papi.adoc} (97%) rename authorization_services/topics/{service/protection/protection-api.adoc => service-protection-protection-api.adoc} (89%) rename authorization_services/topics/{service/protection/resources-api-papi.adoc => service-protection-resources-api-papi.adoc} (91%) create mode 100644 authorization_services/topics/service-protection-resources-api.adoc rename authorization_services/topics/{service/protection/whatis-obtain-pat.adoc => service-protection-whatis-obtain-pat.adoc} (94%) rename authorization_services/topics/{service/rpt/overview.adoc => service-rpt-overview.adoc} (95%) rename authorization_services/topics/{service/rpt/token-introspection.adoc => service-rpt-token-introspection.adoc} (94%) diff --git a/aggregation/navbar-head.html b/aggregation/navbar-head.html index 382ac843bb..2b8925e14e 100644 --- a/aggregation/navbar-head.html +++ b/aggregation/navbar-head.html @@ -41,6 +41,8 @@ ul#globalnav li a:hover { #toc.toc2 { top: 30px; + bottom: 0px; + height: unset; } body.toc2 { diff --git a/authorization_services/index.adoc b/authorization_services/index.adoc index 2afbf8b689..36c909381a 100644 --- a/authorization_services/index.adoc +++ b/authorization_services/index.adoc @@ -3,4 +3,8 @@ :numbered: include::topics/templates/document-attributes-community.adoc[] -include::topics.adoc[] \ No newline at end of file + + += {authorizationguide_name} + +include::topics.adoc[] diff --git a/authorization_services/master.adoc b/authorization_services/master.adoc index 1d80962dcf..f2ce6f603f 100644 --- a/authorization_services/master.adoc +++ b/authorization_services/master.adoc @@ -8,4 +8,4 @@ include::topics/templates/document-attributes-product.adoc[] = {authorizationguide_name} -include::topics.adoc[] \ No newline at end of file +include::topics.adoc[] diff --git a/authorization_services/topics.adoc b/authorization_services/topics.adoc index 8465c0faab..22f65e8f35 100644 --- a/authorization_services/topics.adoc +++ b/authorization_services/topics.adoc @@ -1,110 +1,112 @@ -include::topics/overview/overview.adoc[] +include::topics/auth-services-overview.adoc[leveloffset=+1] -include::topics/overview/architecture.adoc[] +include::topics/auth-services-architecture.adoc[leveloffset=+2] -include::topics/overview/terminology.adoc[] +include::topics/auth-services-terminology.adoc[leveloffset=+2] -include::topics/getting-started/overview.adoc[] +include::topics/getting-started-overview.adoc[leveloffset=+1] -include::topics/getting-started/hello-world/overview.adoc[] +include::topics/hello-world-overview.adoc[leveloffset=+2] -include::topics/getting-started/hello-world/create-realm.adoc[] +include::topics/hello-world-create-realm.adoc[leveloffset=+2] -include::topics/getting-started/hello-world/create-resource-server.adoc[] +include::topics/hello-world-create-resource-server.adoc[leveloffset=+2] -include::topics/getting-started/hello-world/deploy.adoc[] +include::topics/hello-world-deploy.adoc[leveloffset=+2] ifeval::[{project_community}==true] -include::topics/example/overview.adoc[] +include::topics/example-overview.adoc[leveloffset=+2] endif::[] -include::topics/resource-server/overview.adoc[] +include::topics/resource-server-overview.adoc[leveloffset=+1] -include::topics/resource-server/create-client.adoc[] +include::topics/resource-server-create-client.adoc[leveloffset=+2] -include::topics/resource-server/enable-authorization.adoc[] +include::topics/resource-server-enable-authorization.adoc[leveloffset=+2] -include::topics/resource-server/default-config.adoc[] +include::topics/resource-server-default-config.adoc[leveloffset=+2] -include::topics/resource-server/import-config.adoc[] +include::topics/resource-server-import-config.adoc[leveloffset=+2] -include::topics/resource/overview.adoc[] +include::topics/resource-overview.adoc[leveloffset=+1] -include::topics/resource/view.adoc[] +include::topics/resource-view.adoc[leveloffset=+2] -include::topics/resource/create.adoc[] +include::topics/resource-create.adoc[leveloffset=+2] -include::topics/policy/overview.adoc[] +include::topics/policy-overview.adoc[leveloffset=+1] -include::topics/policy/user-policy.adoc[] +include::topics/policy-user-policy.adoc[leveloffset=+2] -include::topics/policy/role-policy.adoc[] +include::topics/policy-role-policy.adoc[leveloffset=+2] -include::topics/policy/role-policy-required-role.adoc[] +include::topics/policy-role-policy-required-role.adoc[leveloffset=+3] -include::topics/policy/js-policy.adoc[] +include::topics/policy-js-policy.adoc[leveloffset=+2] -include::topics/policy/drools-policy.adoc[] +include::topics/policy-drools-policy.adoc[leveloffset=+2] -include::topics/policy/time-policy.adoc[] +include::topics/policy-time-policy.adoc[leveloffset=+2] -include::topics/policy/aggregated-policy.adoc[] +include::topics/policy-aggregated-policy.adoc[leveloffset=+2] -include::topics/policy/client-policy.adoc[] +include::topics/policy-client-policy.adoc[leveloffset=+2] -include::topics/policy/group-policy.adoc[] +include::topics/policy-group-policy.adoc[leveloffset=+2] -include::topics/policy/group-policy-extend-children.adoc[] +include::topics/policy-group-policy-extend-children.adoc[leveloffset=+3] -include::topics/policy/logic.adoc[] +include::topics/policy-logic.adoc[leveloffset=+2] -include::topics/policy/evaluation-api.adoc[] +include::topics/policy-evaluation-api.adoc[leveloffset=+2] -include::topics/permission/overview.adoc[] +include::topics/permission-overview.adoc[leveloffset=+1] -include::topics/permission/create-resource.adoc[] +include::topics/permission-create-resource.adoc[leveloffset=+2] -include::topics/permission/typed-resource-permission.adoc[] +include::topics/permission-typed-resource-permission.adoc[leveloffset=+3] -include::topics/permission/create-scope.adoc[] +include::topics/permission-create-scope.adoc[leveloffset=+2] -include::topics/permission/decision-strategy.adoc[] +include::topics/permission-decision-strategy.adoc[leveloffset=+2] -include::topics/policy-evaluation-tool/overview.adoc[] +include::topics/policy-evaluation-tool-overview.adoc[leveloffset=+1] -include::topics/service/overview.adoc[] +include::topics/service-overview.adoc[leveloffset=+1] -include::topics/service/protection/protection-api.adoc[] +include::topics/service-protection-protection-api.adoc[leveloffset=+2] -include::topics/service/protection/whatis-obtain-pat.adoc[] +include::topics/service-protection-whatis-obtain-pat.adoc[leveloffset=+3] -include::topics/service/protection/resources-api-papi.adoc[] +include::topics/service-protection-resources-api-papi.adoc[leveloffset=+3] -include::topics/service/protection/permission-api-papi.adoc[] +include::topics/service-protection-permission-api-papi.adoc[leveloffset=+3] -include::topics/service/authorization/authorization-api.adoc[] +include::topics/service-authorization-authorization-api.adoc[leveloffset=+2] -include::topics/service/authorization/whatis-obtain-aat.adoc[] +include::topics/service-authorization-whatis-obtain-aat.adoc[leveloffset=+3] -include::topics/service/authorization/authorization-api-aapi.adoc[] +include::topics/service-authorization-authorization-api-aapi.adoc[leveloffset=+3] -include::topics/service/entitlement/entitlement-api.adoc[] +include::topics/service-entitlement-entitlement-api.adoc[leveloffset=+2] -include::topics/service/entitlement/entitlement-api-aapi.adoc[] -include::topics/service/entitlement/entitlement-request-metadata.adoc[] +include::topics/service-entitlement-entitlement-api-aapi.adoc[leveloffset=+3] -include::topics/service/rpt/overview.adoc[] -include::topics/service/rpt/token-introspection.adoc[] +include::topics/service-entitlement-entitlement-request-metadata.adoc[leveloffset=+3] -include::topics/service/client-api.adoc[] +include::topics/service-rpt-overview.adoc[leveloffset=+2] -include::topics/enforcer/overview.adoc[] +include::topics/service-rpt-token-introspection.adoc[leveloffset=+3] -include::topics/enforcer/keycloak-enforcement-filter.adoc[] +include::topics/service-client-api.adoc[leveloffset=+2] -include::topics/enforcer/keycloak-enforcement-bearer.adoc[] +include::topics/enforcer-overview.adoc[leveloffset=+1] -include::topics/enforcer/authorization-context.adoc[] +include::topics/enforcer-keycloak-enforcement-filter.adoc[leveloffset=+2] -include::topics/enforcer/js-adapter.adoc[] +include::topics/enforcer-keycloak-enforcement-bearer.adoc[leveloffset=+3] -include::topics/enforcer/https.adoc[] \ No newline at end of file +include::topics/enforcer-authorization-context.adoc[leveloffset=+3] + +include::topics/enforcer-js-adapter.adoc[leveloffset=+3] + +include::topics/enforcer-https.adoc[leveloffset=+3] diff --git a/authorization_services/topics/overview/architecture.adoc b/authorization_services/topics/auth-services-architecture.adoc similarity index 97% rename from authorization_services/topics/overview/architecture.adoc rename to authorization_services/topics/auth-services-architecture.adoc index 3620470f4e..7cae652e43 100644 --- a/authorization_services/topics/overview/architecture.adoc +++ b/authorization_services/topics/auth-services-architecture.adoc @@ -1,5 +1,5 @@ [[_overview_architecture]] -=== Architecture += Architecture image:images/authz-arch-overview.png[alt="{project_name} AuthZ Architecture Overview"] @@ -27,7 +27,7 @@ Provides implementations for different environments to actually enforce authoriz + Being based on {project_name} Authentication Server, you can obtain attributes from identities and runtime environment during the evaluation of authorization policies. -==== The Authorization Process +== The Authorization Process Three main processes define the necessary steps to understand how to use {project_name} to enable fine-grained authorization to your applications: @@ -35,7 +35,7 @@ Three main processes define the necessary steps to understand how to use {projec * *Permission and Policy Management* * *Policy Enforcement* -===== Resource Management +=== Resource Management *Resource Management* involves all the necessary steps to define what is being protected. @@ -55,7 +55,7 @@ Resources can be managed using the {project_name} Administration Console or the 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. -===== Permission and Policy Management +=== Permission and Policy Management Once you have defined your resource server and all the resources you want to protect, you must set up permissions and policies. @@ -72,7 +72,7 @@ For instance,to allow access to a group of resources only for users granted with Once you have your policies defined, you can start defining your permissions. Permissions are coupled with the resource they are protecting. Here you specify what you want to protect (resource or scope) and the policies that must be satisfied to grant or deny permission. -===== Policy Enforcement +=== Policy Enforcement *Policy Enforcement* involves the necessary steps to actually enforce authorization decisions to a resource server. This is achieved by enabling a *Policy Enforcement Point* or PEP at the resource server that is capable of communicating with the authorization server, ask for authorization data and control access to protected resources based on the decisions and permissions returned by the server. @@ -81,7 +81,7 @@ image:images/pep-pattern-diagram.png[alt="PEP Overview"] {project_name} provides some built-in <<_enforcer_overview, Policy Enforcers>> implementations that you can use to protect your applications depending on the platform they are running on. -==== Authorization Services +== Authorization Services Authorization services consist of the following RESTFul APIs: @@ -91,7 +91,7 @@ Authorization services consist of the following RESTFul APIs: Each of these services provides a specific API covering the different steps involved in the authorization process. -===== Protection API +=== Protection API The *Protection API* is a https://kantarainitiative.org/confluence/display/uma/UMA+1.0+Core+Protocol[UMA-compliant] endpoint providing a small set of operations for resource servers to help them manage their resources and scopes. Only resource servers are allowed to access this API, which also requires a @@ -115,7 +115,7 @@ When using the UMA protocol, the issuance of Permission Tickets by the Protectio For more information, see <<_service_protection_api, Protection API>>. -===== Authorization API +=== Authorization API The Authorization API is also a https://kantarainitiative.org/confluence/display/uma/UMA+1.0+Core+Protocol[UMA-compliant] endpoint providing a single operation that exchanges an Access Token and <<_overview_terminology_permission_ticket, Permission Ticket>> with a Requesting Party Token (RPT). @@ -128,7 +128,7 @@ image:images/authz-calls.png[alt="Authorization API Overview"] For more information, see <<_service_authorization_api, Authorization API>>. -==== Entitlement API +== Entitlement API The Entitlement API provides a 1-legged protocol to issue RPTs. Unlike the Authorization API, the Entitlement API only expects an access token. @@ -138,7 +138,3 @@ one or more resources. image:images/entitlement-calls.png[alt="Entitlement API Overview"] For more information see <<_service_entitlement_api, Entitlement API>>. - - - - diff --git a/authorization_services/topics/overview/overview.adoc b/authorization_services/topics/auth-services-overview.adoc similarity index 99% rename from authorization_services/topics/overview/overview.adoc rename to authorization_services/topics/auth-services-overview.adoc index 596653ec88..d01df52d94 100644 --- a/authorization_services/topics/overview/overview.adoc +++ b/authorization_services/topics/auth-services-overview.adoc @@ -1,5 +1,5 @@ [[_overview]] -== Overview += Overview ifeval::[{project_product}==true] NOTE: Authorization Services is a Technology Preview feature and is not fully supported. This feature is disabled by default. @@ -41,4 +41,4 @@ using different devices, and with a high demand for information sharing, {projec * Centralized Policy Decision Point * REST security based on a set of REST-based authorization services * Authorization workflows and User-Managed Access -* The infrastructure to help avoid code replication across projects (and redeploys) and quickly adapt to changes in your security requirements. \ No newline at end of file +* The infrastructure to help avoid code replication across projects (and redeploys) and quickly adapt to changes in your security requirements. diff --git a/authorization_services/topics/overview/terminology.adoc b/authorization_services/topics/auth-services-terminology.adoc similarity index 97% rename from authorization_services/topics/overview/terminology.adoc rename to authorization_services/topics/auth-services-terminology.adoc index ff9490c6ca..f1a1ed0738 100644 --- a/authorization_services/topics/overview/terminology.adoc +++ b/authorization_services/topics/auth-services-terminology.adoc @@ -1,10 +1,10 @@ [[_overview_terminology]] -=== Terminology += Terminology Before going further, it is important to understand these terms and concepts introduced by {project_name} Authorization Services. [[_overview_terminology_resource_server]] -==== Resource Server +== Resource Server Per OAuth2 terminology, a resource server is the server hosting the protected resources and capable of accepting and responding to protected resource requests. @@ -14,20 +14,20 @@ authenticate users usually store that information in the user's session and retr In {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 +== Resource A resource is part of the assets of an application and the organization. It can be a set of one or more endpoints, a classic web resource such as an HTML page, and so on. In authorization policy terminology, a resource is the _object_ being protected. Every resource has a unique identifier that can represent a single resource or a set of resources. For instance, you can manage a _Banking Account Resource_ that represents and defines a set of authorization policies for all banking accounts. But you can also have a different resource named _Alice's Banking Account_, which represents a single resource owned by a single customer, which can have its own set of authorization policies. -==== Scope +== Scope A resource's scope is a bounded extent of access that is possible to perform on a resource. In authorization policy terminology, a scope is one of the potentially many _verbs_ that can logically apply to a resource. It usually indicates what can be done with a given resource. Example of scopes are view, edit, delete, and so on. However, scope can also be related to specific information provided by a resource. In this case, you can have a project resource and a cost scope, where the cost scope is used to define specific policies and permissions for users to access a project's cost. -==== Permission +== Permission Consider this simple and very common permission: @@ -45,7 +45,7 @@ A permission associates the object being protected with the policies that must b * Support a more flexible security model, helping you to easily adapt to changes in your security requirements * Make changes at runtime; applications are only concerned about the resources and scopes being protected and not how they are protected. -==== Policy +== Policy A policy defines the conditions that must be satisfied to grant access to an object. Unlike permissions, you do not specify the object being protected but rather the conditions that must be satisfied for access to a given object (for example, resource, scope, or both). @@ -56,7 +56,7 @@ With policies, you can implement strategies for attribute-based access control ( Instead of writing one large policy with all the conditions that must be satisfied for access to a given resource, the policies implementation in {project_name} Authorization Services 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. -==== Policy Provider +== Policy Provider Policy providers are implementations of specific policy types. {project_name} provides built-in policies, backed by their corresponding policy providers, and you can create your own policy types to support your specific requirements. @@ -64,7 +64,7 @@ policy providers, and you can create your own policy types to support your speci {project_name} provides a SPI (Service Provider Interface) that you can use to plug in your own policy provider implementations. [[_overview_terminology_permission_ticket]] -==== Permission Ticket +== Permission Ticket A permission ticket is a special type of token defined by the https://kantarainitiative.org/confluence/display/uma/UMA+1.0+Core+Protocol[OAuth2's User-Managed Access (UMA) Profile] specification that provides an opaque structure whose form is determined by the authorization server. This structure represents the resources and/or scopes being requested by a client as well as the policies that must be applied to a request for authorization data (requesting party token [RPT]). @@ -73,4 +73,5 @@ 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 <<_service_authorization_api, Authorization API>> and the https://kantarainitiative.org/confluence/display/uma/UMA+1.0+Core+Protocol[UMA] specification. \ No newline at end of file +For more information on permission tickets, see <<_service_authorization_api, Authorization API>> and the https://kantarainitiative.org/confluence/display/uma/UMA+1.0+Core+Protocol[UMA] specification. + diff --git a/authorization_services/topics/enforcer/authorization-context.adoc b/authorization_services/topics/enforcer-authorization-context.adoc similarity index 95% rename from authorization_services/topics/enforcer/authorization-context.adoc rename to authorization_services/topics/enforcer-authorization-context.adoc index 298dbeaf2e..448b77a7fe 100644 --- a/authorization_services/topics/enforcer/authorization-context.adoc +++ b/authorization_services/topics/enforcer-authorization-context.adoc @@ -1,5 +1,5 @@ [[_enforcer_authorization_context]] -==== Obtaining the Authorization Context += Obtaining the Authorization Context When policy enforcement is enabled, the permissions obtained from the server are available through `org.keycloak.AuthorizationContext`. This class provides several methods you can use to obtain permissions and ascertain whether a permission was granted for a particular resource or scope. @@ -59,7 +59,7 @@ Now, suppose your security requirements have changed and in addition to project Security requirements change, but with {project_name} there is no need to change your application code to address the new requirements. Once your application is based on the resource and scope identifier, you need only change the configuration of the permissions or policies associated with a particular resource in the authorization server. In this case, the permissions and policies associated with the `Project Resource` and/or the scope `urn:project.com:project:create` would be changed. -==== Using the AuthorizationContext to obtain an Authorization Client Instance += Using the AuthorizationContext to obtain an Authorization Client Instance The ```AuthorizationContext``` can also be used to obtain a reference to the <<_service_client_api, Authorization Client API>> configured to your application: @@ -68,4 +68,4 @@ The ```AuthorizationContext``` can also be used to obtain a reference to the <<_ AuthzClient authzClient = clientContext.getClient(); ``` -In some cases, resource servers protected by the policy enforcer need to access the APIs provided by the authorization server. With an ```AuthzClient``` instance in hands, resource servers can interact with the server in order to create resources or check for specific permissions programmatically. \ No newline at end of file +In some cases, resource servers protected by the policy enforcer need to access the APIs provided by the authorization server. With an ```AuthzClient``` instance in hands, resource servers can interact with the server in order to create resources or check for specific permissions programmatically. diff --git a/authorization_services/topics/enforcer/https.adoc b/authorization_services/topics/enforcer-https.adoc similarity index 94% rename from authorization_services/topics/enforcer/https.adoc rename to authorization_services/topics/enforcer-https.adoc index a0e435cd8f..f5c111fa60 100644 --- a/authorization_services/topics/enforcer/https.adoc +++ b/authorization_services/topics/enforcer-https.adoc @@ -1,5 +1,5 @@ [[_enforcer_filter_using_https]] -==== Setting Up TLS/HTTPS += Setting Up TLS/HTTPS When the server is using HTTPS, ensure your adapter is configured as follows: @@ -16,4 +16,3 @@ The configuration above enables TLS/HTTPS to the Authorization Client, making po [NOTE] It is strongly recommended that you enable TLS/HTTPS when accessing the {project_name} Server endpoints. - diff --git a/authorization_services/topics/enforcer/js-adapter.adoc b/authorization_services/topics/enforcer-js-adapter.adoc similarity index 97% rename from authorization_services/topics/enforcer/js-adapter.adoc rename to authorization_services/topics/enforcer-js-adapter.adoc index 627a46d7da..0e2506b44f 100644 --- a/authorization_services/topics/enforcer/js-adapter.adoc +++ b/authorization_services/topics/enforcer-js-adapter.adoc @@ -1,5 +1,5 @@ [[_enforcer_js_adapter]] -==== JavaScript Integration += JavaScript Integration The {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 {project_name} JavaScript adapter, which can be integrated to allow your client to obtain permissions from a {project_name} Server. @@ -26,7 +26,7 @@ The *keycloak-authz.js* library provides two main features: In both cases, the library allows you to easily interact with both resource server and {project_name} Authorization Services 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 +== 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 <<_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 @@ -56,7 +56,7 @@ The `authorize` function is completely asynchronous and supports a few callback Most applications should use the `onGrant` callback to retry a request after a 401 response. Subsequent requests should include the RPT as a bearer token for retries. -===== Obtaining Entitlements +== Obtaining Entitlements The keycloak-authz.js library provides an `entitlement` function that you can use to obtain an RPT from the server using the Entitlement API. @@ -75,7 +75,7 @@ The `entitlement` function is completely asynchronous and supports a few callbac * `onDeny`: The second argument of the function. Only called if the server has denied the authorization request. * `onError`: The third argument of the function. Only called if the server responds unexpectedly. -===== Obtaining the RPT +== Obtaining the RPT If you have already obtained an RPT using any of the authorization functions provided by the library, you can always obtain the RPT as follows from the authorization object (assuming that it has been initialized by one of the techniques shown earlier): diff --git a/authorization_services/topics/enforcer/keycloak-enforcement-bearer.adoc b/authorization_services/topics/enforcer-keycloak-enforcement-bearer.adoc similarity index 94% rename from authorization_services/topics/enforcer/keycloak-enforcement-bearer.adoc rename to authorization_services/topics/enforcer-keycloak-enforcement-bearer.adoc index 519c8b8ede..a9631913de 100644 --- a/authorization_services/topics/enforcer/keycloak-enforcement-bearer.adoc +++ b/authorization_services/topics/enforcer-keycloak-enforcement-bearer.adoc @@ -1,5 +1,5 @@ [[_enforcer_bearer]] -==== Protecting a Stateless Service Using a Bearer Token += 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 to access a protected resource is allowed or denied based on the permissions of the bearer token. @@ -21,7 +21,7 @@ In this example, a *keycloak.json* file in your application is similar to the fo ... ``` -===== Authorization Response +== Authorization Response When a client tries 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. The value of the `WWW-Authenticate` header depends on the authorization protocol @@ -42,5 +42,3 @@ WWW-Authenticate: KC_ETT realm="photoz-restful-api",as_uri="http://localhost:808 ``` Once a client receives a response from the server, it examines the status code and `WWW-Authenticate` header to obtain an RPT from the {project_name} Server. - - diff --git a/authorization_services/topics/enforcer/keycloak-enforcement-filter.adoc b/authorization_services/topics/enforcer-keycloak-enforcement-filter.adoc similarity index 98% rename from authorization_services/topics/enforcer/keycloak-enforcement-filter.adoc rename to authorization_services/topics/enforcer-keycloak-enforcement-filter.adoc index 81090e05c5..d75e210e76 100644 --- a/authorization_services/topics/enforcer/keycloak-enforcement-filter.adoc +++ b/authorization_services/topics/enforcer-keycloak-enforcement-filter.adoc @@ -1,5 +1,5 @@ [[_enforcer_filter]] -=== {project_name} Adapter Policy Enforcer += {project_name} Adapter Policy Enforcer You can enforce authorization decisions for your applications if you are using {project_name} OIDC adapters. @@ -10,7 +10,7 @@ when you create a resource server, {project_name} creates a <<_resource_server_d The default configuration allows access for all resources in your application provided the authenticated user belongs to the same realm as the resource server being protected. -==== Policy Enforcement Configuration +== Policy Enforcement Configuration To enable policy enforcement for your application, add the following property to your *keycloak.json* file: diff --git a/authorization_services/topics/enforcer/overview.adoc b/authorization_services/topics/enforcer-overview.adoc similarity index 85% rename from authorization_services/topics/enforcer/overview.adoc rename to authorization_services/topics/enforcer-overview.adoc index 2f3581247f..691b56681f 100644 --- a/authorization_services/topics/enforcer/overview.adoc +++ b/authorization_services/topics/enforcer-overview.adoc @@ -1,8 +1,8 @@ [[_enforcer_overview]] -== Policy Enforcers += Policy Enforcers Policy Enforcement Point (PEP) is a design pattern and as such you can implement it in different ways. {project_name} provides all the necessary means to implement PEPs for different platforms, environments, and programming languages. {project_name} Authorization Services presents a RESTful API, and leverages OAuth2 authorization capabilities for fine-grained authorization using a centralized authorization server. -image:images/pep-pattern-diagram.png[alt="PEP Overview"] \ No newline at end of file +image:images/pep-pattern-diagram.png[alt="PEP Overview"] diff --git a/authorization_services/topics/example/overview.adoc b/authorization_services/topics/example-overview.adoc similarity index 99% rename from authorization_services/topics/example/overview.adoc rename to authorization_services/topics/example-overview.adoc index 7b4327f910..7d5d72a740 100644 --- a/authorization_services/topics/example/overview.adoc +++ b/authorization_services/topics/example-overview.adoc @@ -1,5 +1,5 @@ [[_example_overview]] -== Examples += Examples The {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 own applications. diff --git a/authorization_services/topics/getting-started/overview.adoc b/authorization_services/topics/getting-started-overview.adoc similarity index 98% rename from authorization_services/topics/getting-started/overview.adoc rename to authorization_services/topics/getting-started-overview.adoc index a7db1332c4..b001610f61 100644 --- a/authorization_services/topics/getting-started/overview.adoc +++ b/authorization_services/topics/getting-started-overview.adoc @@ -1,5 +1,5 @@ [[_getting_started_overview]] -== Getting Started += Getting Started Before you can use this tutorial, you need to complete the installation of {project_name} and create the initial admin user as shown in the link:{gettingstarted_link}[{gettingstarted_name}] tutorial. There is one caveat to this. You have to run a separate {appserver_name} instance on the same machine as {project_name} Server. This separate instance will run your Java Servlet application. Because of this you will have to run the {project_name} under a different port so that there are no port conflicts when running on the same machine. Use the `jboss.socket.binding.port-offset` system property on the command line. The value of this property is a number that will be added to the base value of every port opened by {project_name} Server. diff --git a/authorization_services/topics/getting-started/hello-world/before-start.adoc b/authorization_services/topics/hello-world-before-start.adoc similarity index 91% rename from authorization_services/topics/getting-started/hello-world/before-start.adoc rename to authorization_services/topics/hello-world-before-start.adoc index 57ce8cec83..2d9b64123e 100644 --- a/authorization_services/topics/getting-started/hello-world/before-start.adoc +++ b/authorization_services/topics/hello-world-before-start.adoc @@ -1,4 +1,4 @@ -=== Before You Start += Before You Start This guide is based on the *{project_name} Demo Distribution*. Download the demo distribution before proceeding. @@ -12,4 +12,4 @@ Administration Console, a page similar to this one is displayed: image:{project_images}/getting-started/kc-start-page.png[alt="{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 +are located at *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz*. diff --git a/authorization_services/topics/getting-started/hello-world/create-realm.adoc b/authorization_services/topics/hello-world-create-realm.adoc similarity index 97% rename from authorization_services/topics/getting-started/hello-world/create-realm.adoc rename to authorization_services/topics/hello-world-create-realm.adoc index 28f413a93f..f3f02427d9 100644 --- a/authorization_services/topics/getting-started/hello-world/create-realm.adoc +++ b/authorization_services/topics/hello-world-create-realm.adoc @@ -1,5 +1,5 @@ [[_getting_started_hello_world_create_realm]] -=== Creating a Realm and a User += Creating a Realm and a User The first step is to create a realm and a user in that realm. The realm consists of: diff --git a/authorization_services/topics/getting-started/hello-world/create-resource-server.adoc b/authorization_services/topics/hello-world-create-resource-server.adoc similarity index 97% rename from authorization_services/topics/getting-started/hello-world/create-resource-server.adoc rename to authorization_services/topics/hello-world-create-resource-server.adoc index 872584ff85..6185c915ad 100644 --- a/authorization_services/topics/getting-started/hello-world/create-resource-server.adoc +++ b/authorization_services/topics/hello-world-create-resource-server.adoc @@ -1,11 +1,11 @@ [[_getting_started_hello_world_enabling_authz_services]] -=== Enabling Authorization 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: -. Click *Clients* to start creating a new client application and fill in the *Client ID*, *Client Protocol*, and *Root URL* fields. +. Click *Clients* to start creating a new client application and fill in the *Client ID*, *Client Protocol*, and *Root URL* fields. + .Create Client Application image:{project_images}/getting-started/hello-world/create-client.png[alt="Create Client Application"] diff --git a/authorization_services/topics/getting-started/hello-world/deploy.adoc b/authorization_services/topics/hello-world-deploy.adoc similarity index 95% rename from authorization_services/topics/getting-started/hello-world/deploy.adoc rename to authorization_services/topics/hello-world-deploy.adoc index 897dcc0f14..be2227c342 100644 --- a/authorization_services/topics/getting-started/hello-world/deploy.adoc +++ b/authorization_services/topics/hello-world-deploy.adoc @@ -1,5 +1,5 @@ [[_getting_started_hello_world_deploy]] -=== Build, Deploy, and Test Your Application += Build, Deploy, and Test Your Application Now that the *app-authz-vanilla* resource server (or client) is properly configured and authorization services are enabled, it can be deployed to the server. @@ -33,9 +33,9 @@ The application we are about to build and deploy is located at $ cd {quickstartRepo_dir}/app-authz-jee-vanilla ---- -==== Obtaining the Adapter Configuration +== Obtaining the Adapter Configuration -You must first obtain the adapter configuration before building and deploying the application. +You must first obtain the adapter configuration before building and deploying the application. To obtain the adapter configuration from the {project_name} Administration Console, complete the following steps. @@ -61,7 +61,7 @@ image:{project_images}/getting-started/hello-world/adapter-config.png[alt="Adapt + This change specifies to the policy enforcer to redirect users to a `/app-authz-vanilla/error.jsp` page if a user does not have the necessary permissions to access a protected resource, rather than an unhelpful `403 Unauthorized` message. -==== Building and Deploying the Application +== Building and Deploying the Application To build and deploy the application execute the following command: @@ -70,7 +70,7 @@ $ cd redhat-sso-quickstarts/app-authz-jee-vanilla $ mvn clean package wildfly:deploy ``` -==== Testing the Application +== Testing the Application If your application was successfully deployed you can access it at http://localhost:8080/app-authz-vanilla[http://localhost:8080/app-authz-vanilla]. The {project_name} Login page opens. @@ -104,11 +104,11 @@ image:{project_images}/getting-started/hello-world/access-denied-page.png[alt="A Let's fix that now, but instead of changing the `Default Policy` code we are going to change the `Logic` to `Negative` using the dropdown list below the policy code text area. That re-enables access to the application as we are negating the result of that policy, which is by default denying all requests for access. Again, before testing this change, be sure to log out and log in again. -==== Next Steps +== Next Steps 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 <<_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 <<_enforcer_authorization_context, Obtaining the Authorization Context>>. \ No newline at end of file +* For more information about how to view and test permissions inside your application see <<_enforcer_authorization_context, Obtaining the Authorization Context>>. diff --git a/authorization_services/topics/getting-started/hello-world/overview.adoc b/authorization_services/topics/hello-world-overview.adoc similarity index 90% rename from authorization_services/topics/getting-started/hello-world/overview.adoc rename to authorization_services/topics/hello-world-overview.adoc index 177dc2b88c..64c16202d9 100644 --- a/authorization_services/topics/getting-started/hello-world/overview.adoc +++ b/authorization_services/topics/hello-world-overview.adoc @@ -1,5 +1,5 @@ [[_getting_started_hello_world_overview]] -=== Securing a Servlet Application += Securing a Servlet Application 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 {project_name}. This quick tour relies heavily on the default database and server configurations and does not cover complex deployment options. @@ -10,4 +10,4 @@ This guide explains key concepts about {project_name} Authorization Services: * Enabling fine-grained authorization for a client application * Configuring a client application to be a resource server, with protected resources * Defining permissions and authorization policies to govern access to protected resources -* Enabling policy enforcement in your applications. \ No newline at end of file +* Enabling policy enforcement in your applications. diff --git a/authorization_services/topics/permission/create-resource.adoc b/authorization_services/topics/permission-create-resource.adoc similarity index 94% rename from authorization_services/topics/permission/create-resource.adoc rename to authorization_services/topics/permission-create-resource.adoc index 991fc59fd7..d50183a560 100644 --- a/authorization_services/topics/permission/create-resource.adoc +++ b/authorization_services/topics/permission-create-resource.adoc @@ -1,5 +1,5 @@ [[_permission_create_resource]] -=== Creating Resource-Based Permissions += 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. @@ -8,7 +8,7 @@ To create a new resource-based permission, select *Resource-based* in the dropdo .Add Resource-Based Permission image:{project_images}/permission/create-resource.png[alt="Add Resource-Based Permission"] -==== Configuration +== Configuration * *Name* + @@ -38,4 +38,4 @@ Defines a set of one or more policies to associate with a permission. * *Decision Strategy* + -The <<_permission_decision_strategies, Decision Strategy>> for this permission. \ No newline at end of file +The <<_permission_decision_strategies, Decision Strategy>> for this permission. diff --git a/authorization_services/topics/permission/create-scope.adoc b/authorization_services/topics/permission-create-scope.adoc similarity index 95% rename from authorization_services/topics/permission/create-scope.adoc rename to authorization_services/topics/permission-create-scope.adoc index 1180455862..deb3d1d862 100644 --- a/authorization_services/topics/permission/create-scope.adoc +++ b/authorization_services/topics/permission-create-scope.adoc @@ -1,5 +1,5 @@ [[_permission_create_scope]] -=== Creating Scope-Based Permissions += 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. @@ -8,7 +8,7 @@ To create a new scope-based permission, select *Scope-based* in the dropdown lis .Add Scope-Based Permission image:{project_images}/permission/create-scope.png[alt="Add Scope-Based Permission"] -==== Configuration +== Configuration * *Name* + @@ -33,4 +33,4 @@ Defines a set of one or more policies to associate with a permission. * *Decision Strategy* + -The <<_permission_decision_strategies, Decision Strategy>> for this permission. \ No newline at end of file +The <<_permission_decision_strategies, Decision Strategy>> for this permission. diff --git a/authorization_services/topics/permission/decision-strategy.adoc b/authorization_services/topics/permission-decision-strategy.adoc similarity index 95% rename from authorization_services/topics/permission/decision-strategy.adoc rename to authorization_services/topics/permission-decision-strategy.adoc index 154ab2de09..842224d0e4 100644 --- a/authorization_services/topics/permission/decision-strategy.adoc +++ b/authorization_services/topics/permission-decision-strategy.adoc @@ -1,5 +1,5 @@ [[_permission_decision_strategies]] -=== Policy 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. @@ -13,4 +13,4 @@ In this case, _at least one_ policy must evaluate to a positive decision for the + * *Consensus* + -In this case, the number of positive decisions must be greater than the number of negative decisions. If the number of positive and negative decisions is equal, the final decision will be negative. \ No newline at end of file +In this case, the number of positive decisions must be greater than the number of negative decisions. If the number of positive and negative decisions is equal, the final decision will be negative. diff --git a/authorization_services/topics/permission/overview.adoc b/authorization_services/topics/permission-overview.adoc similarity index 93% rename from authorization_services/topics/permission/overview.adoc rename to authorization_services/topics/permission-overview.adoc index adfd596b99..c130c77ed3 100644 --- a/authorization_services/topics/permission/overview.adoc +++ b/authorization_services/topics/permission-overview.adoc @@ -1,5 +1,5 @@ [[_permission_overview]] -== Managing Permissions += Managing Permissions A permission associates the object being protected and the policies that must be evaluated to decide whether access should be granted. @@ -14,4 +14,4 @@ Permissions can be created to protect two main types of objects: * *Resources* * *Scopes* -To create a permission, select the permission type you want to create from the dropdown list in the upper right corner of the permission listing. The following sections describe these two types of objects in more detail. \ No newline at end of file +To create a permission, select the permission type you want to create from the dropdown list in the upper right corner of the permission listing. The following sections describe these two types of objects in more detail. diff --git a/authorization_services/topics/permission/typed-resource-permission.adoc b/authorization_services/topics/permission-typed-resource-permission.adoc similarity index 94% rename from authorization_services/topics/permission/typed-resource-permission.adoc rename to authorization_services/topics/permission-typed-resource-permission.adoc index 090a38c7ec..5a37173d43 100644 --- a/authorization_services/topics/permission/typed-resource-permission.adoc +++ b/authorization_services/topics/permission-typed-resource-permission.adoc @@ -1,5 +1,5 @@ [[_permission_typed_resource]] -==== Typed Resource Permission += Typed Resource Permission Resource permissions can also be used to define policies that are to be applied to all resources with a given <<_resource_create_type, type>>. This form of resource-based permission can be useful when you have resources sharing common access requirements and constraints. @@ -13,4 +13,4 @@ To create a typed resource permission, click <<_permission_create_resource_apply 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 -image:{project_images}/permission/typed-resource-perm-example.png[alt="Example of a Typed Resource Permission"] \ No newline at end of file +image:{project_images}/permission/typed-resource-perm-example.png[alt="Example of a Typed Resource Permission"] diff --git a/authorization_services/topics/policy/aggregated-policy.adoc b/authorization_services/topics/policy-aggregated-policy.adoc similarity index 96% rename from authorization_services/topics/policy/aggregated-policy.adoc rename to authorization_services/topics/policy-aggregated-policy.adoc index 9a1f5338e3..cd8edc6453 100644 --- a/authorization_services/topics/policy/aggregated-policy.adoc +++ b/authorization_services/topics/policy-aggregated-policy.adoc @@ -1,5 +1,5 @@ [[_policy_aggregated]] -=== Aggregated Policy += Aggregated Policy As mentioned previously, {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. @@ -16,7 +16,7 @@ You can create separate policies for both domain and network conditions and crea [NOTE] When creating aggregated policies, be mindful that you are not introducing a circular reference or dependency between policies. If a circular dependency is detected, you cannot create or update the policy. -==== Configuration +== Configuration * *Name* + @@ -39,7 +39,7 @@ The decision strategy for this permission. + The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. -==== Decision Strategy for Aggregated Policies +== Decision Strategy for Aggregated Policies When creating aggregated policies, you can also define the decision strategy that will be used to determine the final decision based on the outcome from each policy. @@ -53,4 +53,4 @@ In this case, _at least one_ policy must evaluate to a positive decision in orde + * *Consensus* + -In this case, the number of positive decisions must be greater than the number of negative decisions. If the number of positive and negative decisions is the same, the final decision will be negative. \ No newline at end of file +In this case, the number of positive decisions must be greater than the number of negative decisions. If the number of positive and negative decisions is the same, the final decision will be negative. diff --git a/authorization_services/topics/policy/client-policy.adoc b/authorization_services/topics/policy-client-policy.adoc similarity index 91% rename from authorization_services/topics/policy/client-policy.adoc rename to authorization_services/topics/policy-client-policy.adoc index d5f5d8416a..9c18cd9e35 100644 --- a/authorization_services/topics/policy/client-policy.adoc +++ b/authorization_services/topics/policy-client-policy.adoc @@ -1,5 +1,5 @@ [[_policy_client]] -=== Client-Based Policy += Client-Based Policy You can use this type of policy to define conditions for your permissions where a set of one or more clients is permitted to access an object. @@ -8,7 +8,7 @@ To create a new client-based policy, select *Client* in the dropdown list in the .Add a Client-Based Policy image:images/policy/create-client.png[alt="Add Client-Based Policy"] -==== Configuration +== Configuration * *Name* + @@ -25,4 +25,4 @@ Specifies which clients are given access by this policy. + * *Logic* + -The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. \ No newline at end of file +The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. diff --git a/authorization_services/topics/policy/drools-policy.adoc b/authorization_services/topics/policy-drools-policy.adoc similarity index 98% rename from authorization_services/topics/policy/drools-policy.adoc rename to authorization_services/topics/policy-drools-policy.adoc index f8e49d0b27..9202954acc 100644 --- a/authorization_services/topics/policy/drools-policy.adoc +++ b/authorization_services/topics/policy-drools-policy.adoc @@ -1,5 +1,5 @@ [[_policy_drools]] -=== Rule-Based Policy += 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 {project_name}, and provides flexibility to write any policy based on the <<_policy_evaluation_api, Evaluation API>>. @@ -10,7 +10,7 @@ To create a new Rule-based policy, in the dropdown list in the right upper corne .Add Rule Policy image:{project_images}/policy/create-drools.png[alt="Add Rule Policy"] -==== Configuration +== Configuration * *Name* + @@ -53,7 +53,7 @@ Specifies an interval for scanning for artifact updates. + The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. -==== Examples +== Examples Here is a simple example of a Drools-based policy that uses attribute-based access control (ABAC) to define a condition that evaluates to a GRANT only if the authenticated user is the owner of the requested resource: diff --git a/authorization_services/topics/policy/evaluation-api.adoc b/authorization_services/topics/policy-evaluation-api.adoc similarity index 98% rename from authorization_services/topics/policy/evaluation-api.adoc rename to authorization_services/topics/policy-evaluation-api.adoc index b0a38ac38e..6c3a24cf1b 100644 --- a/authorization_services/topics/policy/evaluation-api.adoc +++ b/authorization_services/topics/policy-evaluation-api.adoc @@ -1,5 +1,5 @@ [[_policy_evaluation_api]] -=== Policy Evaluation API += Policy Evaluation API When writing rule-based policies using JavaScript or JBoss Drools, {project_name} provides an Evaluation API that provides useful information to help determine whether a permission should be granted. @@ -46,7 +46,7 @@ Policies determine this by invoking the `grant()` or `deny()` methods on an `Eva For more information about the Evaluation API see the {apidocs_link}[JavaDocs]. -==== The Evaluation Context +== The Evaluation Context The evaluation context provides useful information to policies during their evaluation. diff --git a/authorization_services/topics/policy-evaluation-tool/overview.adoc b/authorization_services/topics/policy-evaluation-tool-overview.adoc similarity index 85% rename from authorization_services/topics/policy-evaluation-tool/overview.adoc rename to authorization_services/topics/policy-evaluation-tool-overview.adoc index 76819b68a9..3934537961 100644 --- a/authorization_services/topics/policy-evaluation-tool/overview.adoc +++ b/authorization_services/topics/policy-evaluation-tool-overview.adoc @@ -1,5 +1,5 @@ [[_policy_evaluation_overview]] -== Evaluating and Testing Policies += Evaluating and Testing Policies When designing your policies, you can simulate authorization requests to test how your policies are being evaluated. @@ -7,19 +7,19 @@ You can access the Policy Evaluation Tool by clicking the `Evaluate` tab when ed image:{project_images}/policy-evaluation-tool/policy-evaluation-tool.png[alt="Policy Evaluation Tool"] -=== Providing Identity Information +== Providing Identity Information The *Identity Information* filters can be used to specify the user requesting permissions. You can also click *Entitlement* to obtain all permissions for the user you selected. -=== Providing Contextual Information +== Providing Contextual Information The *Contextual Information* filters can be used to define additional attributes to the evaluation context, so that policies can obtain these same attributes. -=== Providing the Permissions +== Providing the Permissions The *Permissions* filters can be used to build an authorization request. You can request permissions for a set of one or more resources and scopes. If you want to simulate authorization requests based on all protected resources and scopes, click *Add* without specifying any `Resources` or `Scopes`. -When you've specified your desired values, click *Evaluate*. \ No newline at end of file +When you've specified your desired values, click *Evaluate*. diff --git a/authorization_services/topics/policy/group-policy-extend-children.adoc b/authorization_services/topics/policy-group-policy-extend-children.adoc similarity index 94% rename from authorization_services/topics/policy/group-policy-extend-children.adoc rename to authorization_services/topics/policy-group-policy-extend-children.adoc index c46803cc14..19b7923591 100644 --- a/authorization_services/topics/policy/group-policy-extend-children.adoc +++ b/authorization_services/topics/policy-group-policy-extend-children.adoc @@ -1,5 +1,5 @@ [[_policy_group_extend_access_children]] -==== Extending Access to Child Groups += Extending Access to Child Groups By default, when you add a group to this policy, access restrictions will only apply to members of the selected group. diff --git a/authorization_services/topics/policy/group-policy.adoc b/authorization_services/topics/policy-group-policy.adoc similarity index 97% rename from authorization_services/topics/policy/group-policy.adoc rename to authorization_services/topics/policy-group-policy.adoc index e9eed3ff6e..5a6c902b03 100644 --- a/authorization_services/topics/policy/group-policy.adoc +++ b/authorization_services/topics/policy-group-policy.adoc @@ -1,5 +1,5 @@ [[_policy_group]] -=== Group-Based Policy += Group-Based Policy You can use this type of policy to define conditions for your permissions where a set of one or more groups (and their hierarchies) is permitted to access an object. @@ -8,7 +8,7 @@ To create a new group-based policy, select *Group* in the dropdown list in the u .Add Group-Based Policy image:{project_images}/policy/create-group.png[alt="Add Group-Based Policy"] -==== Configuration +== Configuration * *Name* + diff --git a/authorization_services/topics/policy/js-policy.adoc b/authorization_services/topics/policy-js-policy.adoc similarity index 97% rename from authorization_services/topics/policy/js-policy.adoc rename to authorization_services/topics/policy-js-policy.adoc index 8dca2ae67b..ef7dbedff1 100644 --- a/authorization_services/topics/policy/js-policy.adoc +++ b/authorization_services/topics/policy-js-policy.adoc @@ -1,5 +1,5 @@ [[_policy_js]] -=== JavaScript-Based Policy += 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 {project_name}, and provides flexibility to write any policy based on the <<_policy_evaluation_api, Evaluation API>>. @@ -9,7 +9,7 @@ To create a new JavaScript-based policy, select *JavaScript* in the dropdown lis .Add JavaScript Policy image:{project_images}/policy/create-js.png[alt="Add JavaScript Policy"] -==== Configuration +== Configuration * *Name* + @@ -28,7 +28,7 @@ The JavaScript code providing the conditions for this policy. + The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. -==== Examples +== Examples Here is a simple example of a JavaScript-based policy that uses attribute-based access control (ABAC) to define a condition based on an attribute obtained from the execution context: diff --git a/authorization_services/topics/policy/logic.adoc b/authorization_services/topics/policy-logic.adoc similarity index 93% rename from authorization_services/topics/policy/logic.adoc rename to authorization_services/topics/policy-logic.adoc index f00080c76f..18a1e22385 100644 --- a/authorization_services/topics/policy/logic.adoc +++ b/authorization_services/topics/policy-logic.adoc @@ -1,8 +1,8 @@ [[_policy_logic]] -=== Positive and Negative 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. For example, suppose you want to create a policy where only users *not* granted with a specific role should be given access. In this case, you can create a role-based policy using that role and set its *Logic* field to *Negative*. If you keep *Positive*, which -is the default behavior, the policy result will be kept as it is. \ No newline at end of file +is the default behavior, the policy result will be kept as it is. diff --git a/authorization_services/topics/policy/overview.adoc b/authorization_services/topics/policy-overview.adoc similarity index 96% rename from authorization_services/topics/policy/overview.adoc rename to authorization_services/topics/policy-overview.adoc index 8ca03666a1..cbb8d6aaf9 100644 --- a/authorization_services/topics/policy/overview.adoc +++ b/authorization_services/topics/policy-overview.adoc @@ -1,5 +1,5 @@ [[_policy_overview]] -== Managing Policies += Managing Policies As mentioned previously, policies define the conditions that must be satisfied before granting access to an object. @@ -10,4 +10,4 @@ image:{project_images}/policy/view.png[alt="Policies"] On this tab, you can view the list of previously created policies as well as create and edit a policy. -To create a new policy, in the upper right corner of the policy list, select a policy type from the `Create policy` dropdown list. Details about each policy type are described in this section. \ No newline at end of file +To create a new policy, in the upper right corner of the policy list, select a policy type from the `Create policy` dropdown list. Details about each policy type are described in this section. diff --git a/authorization_services/topics/policy/role-policy-required-role.adoc b/authorization_services/topics/policy-role-policy-required-role.adoc similarity index 93% rename from authorization_services/topics/policy/role-policy-required-role.adoc rename to authorization_services/topics/policy-role-policy-required-role.adoc index 495e887969..cb0de4ff02 100644 --- a/authorization_services/topics/policy/role-policy-required-role.adoc +++ b/authorization_services/topics/policy-role-policy-required-role.adoc @@ -1,5 +1,5 @@ [[_policy_rbac_required]] -==== Defining a Role as 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 only if the user requesting access has been granted *all* the *required* roles. Both realm and client roles can be configured as such. @@ -10,4 +10,4 @@ image:{project_images}/policy/create-role.png[alt="Example of Required Role"] To specify a role as required, select the `Required` checkbox for the role you want to configure as required. Required roles can be useful when your policy defines multiple roles but only a subset of them are mandatory. In this case, you can combine realm and client roles to enable an -even more fine-grained role-based access control (RBAC) model for your application. For example, you can have policies specific for a client and require a specific client role associated with that client. Or you can enforce that access is granted only in the presence of a specific realm role. You can also combine both approaches within the same policy. \ No newline at end of file +even more fine-grained role-based access control (RBAC) model for your application. For example, you can have policies specific for a client and require a specific client role associated with that client. Or you can enforce that access is granted only in the presence of a specific realm role. You can also combine both approaches within the same policy. diff --git a/authorization_services/topics/policy/role-policy.adoc b/authorization_services/topics/policy-role-policy.adoc similarity index 96% rename from authorization_services/topics/policy/role-policy.adoc rename to authorization_services/topics/policy-role-policy.adoc index 1d7c2ae622..c700f8f4b4 100644 --- a/authorization_services/topics/policy/role-policy.adoc +++ b/authorization_services/topics/policy-role-policy.adoc @@ -1,5 +1,5 @@ [[_policy_rbac]] -=== Role-Based Policy += 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. @@ -12,7 +12,7 @@ To create a new role-based policy, select *Role* in the dropdown list in the upp .Add Role-Based Policy image:{project_images}/policy/create-role.png[alt="Add Role-Based Policy"] -==== Configuration +== Configuration * *Name* + @@ -33,4 +33,4 @@ Specifies which *client* roles are permitted by this policy. To enable this fiel + * *Logic* + -The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. \ No newline at end of file +The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. diff --git a/authorization_services/topics/policy/time-policy.adoc b/authorization_services/topics/policy-time-policy.adoc similarity index 98% rename from authorization_services/topics/policy/time-policy.adoc rename to authorization_services/topics/policy-time-policy.adoc index 32fe39e625..1410fd7cbd 100644 --- a/authorization_services/topics/policy/time-policy.adoc +++ b/authorization_services/topics/policy-time-policy.adoc @@ -1,5 +1,5 @@ [[_policy_time]] -=== Time-Based Policy += Time-Based Policy You can use this type of policy to define time conditions for your permissions. @@ -8,7 +8,7 @@ To create a new time-based policy, select *Time* in the dropdown list in the upp .Add Time Policy image:{project_images}/policy/create-time.png[alt="Add Time Policy"] -==== Configuration +== Configuration * *Name* + @@ -52,4 +52,4 @@ Defines the minute that access must be granted. You can also specify a range of + The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. -Access is only granted if all conditions are satisfied. {project_name} will perform an _AND_ based on the outcome of each condition. \ No newline at end of file +Access is only granted if all conditions are satisfied. {project_name} will perform an _AND_ based on the outcome of each condition. diff --git a/authorization_services/topics/policy/user-policy.adoc b/authorization_services/topics/policy-user-policy.adoc similarity index 91% rename from authorization_services/topics/policy/user-policy.adoc rename to authorization_services/topics/policy-user-policy.adoc index f0fee5504c..0ce977386a 100644 --- a/authorization_services/topics/policy/user-policy.adoc +++ b/authorization_services/topics/policy-user-policy.adoc @@ -1,5 +1,5 @@ [[_policy_user]] -=== User-Based Policy += 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. @@ -8,7 +8,7 @@ To create a new user-based policy, select *User* in the dropdown list in the upp .Add a User-Based Policy image:{project_images}/policy/create-user.png[alt="Add User-Based Policy"] -==== Configuration +== Configuration * *Name* + @@ -25,4 +25,4 @@ Specifies which users are given access by this policy. + * *Logic* + -The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. \ No newline at end of file +The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated. diff --git a/authorization_services/topics/resource/create.adoc b/authorization_services/topics/resource-create.adoc similarity index 95% rename from authorization_services/topics/resource/create.adoc rename to authorization_services/topics/resource-create.adoc index 705610161f..ada02626eb 100644 --- a/authorization_services/topics/resource/create.adoc +++ b/authorization_services/topics/resource-create.adoc @@ -1,5 +1,5 @@ [[_resource_create]] -=== Creating Resources += 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 be created to represent a set of one or more resources and the way you define them is crucial to managing permissions. @@ -31,16 +31,16 @@ is usually the relative path used to serve these resources. + One or more scopes to associate with the resource. -==== Typed Resources +== Typed Resources The type field of a resource can be used to group different resources together, so they can be protected using a common set of permissions. -==== Resource Owners +== Resource Owners Resources also have an owner. By default, resources are owned by the resource server. However, resources can also be associated with users, so you can create permissions based on the resource owner. For example, only the resource owner is allowed to delete or update a given resource. -==== Managing Resources Remotely +== Managing Resources Remotely Resource management is also exposed through the <<_service_protection_api, Protection API>> to allow resource servers to remotely manage their resources. @@ -49,4 +49,4 @@ specify the user identifier to configure a resource as belonging to a specific u [NOTE] {project_name} provides resource servers complete control over their resources. In the future, we should be able to -allow users to control their own resources as well as approve authorization requests and manage permissions, especially when using the UMA protocol. \ No newline at end of file +allow users to control their own resources as well as approve authorization requests and manage permissions, especially when using the UMA protocol. diff --git a/authorization_services/topics/resource/overview.adoc b/authorization_services/topics/resource-overview.adoc similarity index 78% rename from authorization_services/topics/resource/overview.adoc rename to authorization_services/topics/resource-overview.adoc index 0d31bfe9c9..c4659cea86 100644 --- a/authorization_services/topics/resource/overview.adoc +++ b/authorization_services/topics/resource-overview.adoc @@ -1,5 +1,5 @@ [[_resource_overview]] -== Managing Resources and Scopes += 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. -Resources and scopes can be managed by navigating to the *Resource* and *Scope* tabs, respectively. \ No newline at end of file +Resources and scopes can be managed by navigating to the *Resource* and *Scope* tabs, respectively. diff --git a/authorization_services/topics/resource-server/create-client.adoc b/authorization_services/topics/resource-server-create-client.adoc similarity index 94% rename from authorization_services/topics/resource-server/create-client.adoc rename to authorization_services/topics/resource-server-create-client.adoc index c7e9fb206f..f548cfa8a9 100644 --- a/authorization_services/topics/resource-server/create-client.adoc +++ b/authorization_services/topics/resource-server-create-client.adoc @@ -1,5 +1,5 @@ [[_resource_server_create_client]] -=== Creating a Client Application += Creating a Client Application The first step to enable {project_name} Authorization Services is to create the client application that you want to turn into a resource server. @@ -25,4 +25,4 @@ http://${host}:${port}/my-resource-server . Click *Save*. The client is created and the client Settings page opens. A page similar to the following is displayed: + .Client Settings -image:{project_images}/resource-server/client-enable-authz.png[alt="Client Settings"] \ No newline at end of file +image:{project_images}/resource-server/client-enable-authz.png[alt="Client Settings"] diff --git a/authorization_services/topics/resource-server/default-config.adoc b/authorization_services/topics/resource-server-default-config.adoc similarity index 97% rename from authorization_services/topics/resource-server/default-config.adoc rename to authorization_services/topics/resource-server-default-config.adoc index 01b33f7480..ff8bed0de5 100644 --- a/authorization_services/topics/resource-server/default-config.adoc +++ b/authorization_services/topics/resource-server-default-config.adoc @@ -1,5 +1,5 @@ [[_resource_server_default_config]] -=== Default Configuration += Default Configuration When you create a resource server, {project_name} creates a default configuration for your newly created resource server. @@ -41,7 +41,7 @@ image:{project_images}/resource-server/default-permission.png[alt="Default Permi This permission is a <<_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 +== Changing the Default Configuration You can change the default configuration by removing the default resource, policy, or permission definitions and creating your own. diff --git a/authorization_services/topics/resource-server/enable-authorization.adoc b/authorization_services/topics/resource-server-enable-authorization.adoc similarity index 97% rename from authorization_services/topics/resource-server/enable-authorization.adoc rename to authorization_services/topics/resource-server-enable-authorization.adoc index 128e260fa6..174d928524 100644 --- a/authorization_services/topics/resource-server/enable-authorization.adoc +++ b/authorization_services/topics/resource-server-enable-authorization.adoc @@ -1,5 +1,5 @@ [[_resource_server_enable_authorization]] -=== Enabling Authorization Services += 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*. @@ -38,7 +38,7 @@ From this page, you can manage the <<_permission_overview, permissions>> for you From this page, you can <<_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]] -==== Resource Server Settings +== Resource Server Settings On the Resource Server Settings page, you can configure the policy enforcement mode, allow remote resource management, and export the authorization configuration settings. @@ -65,4 +65,4 @@ Specifies whether resources can be managed remotely by the resource server. If f + * *Export Settings* + -You can export the authorization configuration settings to a JSON file. Click *Export* to display the complete JSON configuration for download. The configuration file contains everything defined for a resource server: protected resources, scopes, permissions, and policies. \ No newline at end of file +You can export the authorization configuration settings to a JSON file. Click *Export* to display the complete JSON configuration for download. The configuration file contains everything defined for a resource server: protected resources, scopes, permissions, and policies. diff --git a/authorization_services/topics/resource-server/import-config.adoc b/authorization_services/topics/resource-server-import-config.adoc similarity index 90% rename from authorization_services/topics/resource-server/import-config.adoc rename to authorization_services/topics/resource-server-import-config.adoc index c3d0d311a7..0edfeceb57 100644 --- a/authorization_services/topics/resource-server/import-config.adoc +++ b/authorization_services/topics/resource-server-import-config.adoc @@ -1,5 +1,5 @@ [[_resource_server_import_config]] -=== Export and Import Authorization Configuration += Export and Import Authorization Configuration 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: @@ -7,7 +7,7 @@ The configuration settings for a resource server (or client) can be exported and * Policies * Permissions -==== Exporting a Configuration File +== Exporting a Configuration File To export a configuration file, complete the following steps: @@ -23,6 +23,6 @@ image:{project_images}/resource-server/authz-export.png[alt="Export Settings"] The configuration file is exported in JSON format and displayed in a text area, from which you can copy and paste. You can also click *Download* to download the configuration file and save it. -==== Importing a Configuration File +== Importing a Configuration File -To import a configuration file for a resource server, click *Select file* to select a file containing the configuration you want to import. \ No newline at end of file +To import a configuration file for a resource server, click *Select file* to select a file containing the configuration you want to import. diff --git a/authorization_services/topics/resource-server/overview.adoc b/authorization_services/topics/resource-server-overview.adoc similarity index 89% rename from authorization_services/topics/resource-server/overview.adoc rename to authorization_services/topics/resource-server-overview.adoc index 6ade00d77b..a6aa64401b 100644 --- a/authorization_services/topics/resource-server/overview.adoc +++ b/authorization_services/topics/resource-server-overview.adoc @@ -1,8 +1,8 @@ [[_resource_server_overview]] -== Managing Resource Servers += 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. In {project_name}, resource servers are provided with a rich platform for enabling fine-grained authorization for their protected resources, where authorization decisions can be made based on different access control mechanisms. -Any client application can be configured to support fine-grained permissions. In doing so, you are conceptually turning the client application into a resource server. \ No newline at end of file +Any client application can be configured to support fine-grained permissions. In doing so, you are conceptually turning the client application into a resource server. diff --git a/authorization_services/topics/resource/view.adoc b/authorization_services/topics/resource-view.adoc similarity index 94% rename from authorization_services/topics/resource/view.adoc rename to authorization_services/topics/resource-view.adoc index 5b9f814862..33b72ce42f 100644 --- a/authorization_services/topics/resource/view.adoc +++ b/authorization_services/topics/resource-view.adoc @@ -1,5 +1,5 @@ [[_resource_view]] -=== Viewing Resources += Viewing Resources On the *Resource* page, you see a list of the resources associated with a resource server. @@ -17,4 +17,4 @@ The resource list provides information about the protected resources, such as: From this list, you can also directly create a permission by clicking *Create Permission* for the resource for which you want to create the permission. [NOTE] -Before creating permissions for your resources, be sure you have already defined the policies that you want to associate with the permission. \ No newline at end of file +Before creating permissions for your resources, be sure you have already defined the policies that you want to associate with the permission. diff --git a/authorization_services/topics/service/authorization/authorization-api-aapi.adoc b/authorization_services/topics/service-authorization-authorization-api-aapi.adoc similarity index 96% rename from authorization_services/topics/service/authorization/authorization-api-aapi.adoc rename to authorization_services/topics/service-authorization-authorization-api-aapi.adoc index 21f1455563..c0bc2929f5 100644 --- a/authorization_services/topics/service/authorization/authorization-api-aapi.adoc +++ b/authorization_services/topics/service-authorization-authorization-api-aapi.adoc @@ -1,5 +1,5 @@ [[_service_authorization_api_aapi]] -==== Requesting Authorization Data and Token += Requesting Authorization Data and Token Client applications using the UMA protocol can use a specific endpoint to obtain a special security token called a <<_service_rpt_overview, Requesting Party Token (RPT)>>. This token consists of all the permissions granted to a user as a result of the evaluation of the permissions and authorization policies associated with the resources being requested. @@ -29,4 +29,4 @@ As a result, the server response is: ```json {"rpt":"${RPT}"} -``` \ No newline at end of file +``` diff --git a/authorization_services/topics/service/authorization/authorization-api.adoc b/authorization_services/topics/service-authorization-authorization-api.adoc similarity index 85% rename from authorization_services/topics/service/authorization/authorization-api.adoc rename to authorization_services/topics/service-authorization-authorization-api.adoc index 15bdb970ce..14f1792361 100644 --- a/authorization_services/topics/service/authorization/authorization-api.adoc +++ b/authorization_services/topics/service-authorization-authorization-api.adoc @@ -1,8 +1,8 @@ [[_service_authorization_api]] -=== 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 of all permissions and authorization policies associated with the resources being requested. Unlike the Protection API, any client application can access the Authorization API endpoint, which requires a special OAuth2 access token called an authorization API token (AAT). -In UMA, an AAT is a token with the scope *uma_authorization*. \ No newline at end of file +In UMA, an AAT is a token with the scope *uma_authorization*. diff --git a/authorization_services/topics/service/authorization/whatis-obtain-aat.adoc b/authorization_services/topics/service-authorization-whatis-obtain-aat.adoc similarity index 97% rename from authorization_services/topics/service/authorization/whatis-obtain-aat.adoc rename to authorization_services/topics/service-authorization-whatis-obtain-aat.adoc index 6911fb53d1..8be95cdc77 100644 --- a/authorization_services/topics/service/authorization/whatis-obtain-aat.adoc +++ b/authorization_services/topics/service-authorization-whatis-obtain-aat.adoc @@ -1,5 +1,5 @@ [[_service_authorization_aat]] -==== What is an AAT and How to Obtain It += What is an AAT and How to Obtain It An authorization API token (AAT) is a special OAuth2 access token with the scope *uma_authorization*. When you create a user, {project_name} automatically assigns the role _uma_authorization_ to the user. The _uma_authorization_ role is a default realm role. @@ -35,4 +35,4 @@ As a result, the server response is: "not-before-policy": 0, "session_state": "3cad2afc-855b-47b7-8e4d-a21c66e312fb" } -``` \ No newline at end of file +``` diff --git a/authorization_services/topics/service/client-api.adoc b/authorization_services/topics/service-client-api.adoc similarity index 95% rename from authorization_services/topics/service/client-api.adoc rename to authorization_services/topics/service-client-api.adoc index 6fbdfdc29b..ff034436f9 100644 --- a/authorization_services/topics/service/client-api.adoc +++ b/authorization_services/topics/service-client-api.adoc @@ -1,12 +1,12 @@ [[_service_client_api]] -=== Authorization Client Java API += Authorization Client Java API Depending on your requirements, a resource server should be able to manage resources remotely or even check for permissions programmatically. If you are using Java, you can access the {project_name} Authorization Services using the Authorization Client API. It is targeted for resource servers that want to access the different APIs provided by the server such as the Protection, Authorization and Entitlement APIs. -==== Maven Dependency +== Maven Dependency ```xml @@ -18,7 +18,7 @@ It is targeted for resource servers that want to access the different APIs provi ``` -==== Configuration +== Configuration The client configuration is defined in a ``keycloak.json`` file as follows: @@ -43,14 +43,14 @@ The base URL of the {project_name} server. All other {project_name} pages and RE * *resource* (required) + -The client-id of the application. Each application has a client-id that is used to identify the application. +The client-id of the application. Each application has a client-id that is used to identify the application. * *credentials* (required) Specifies the credentials of the application. This is an object notation where the key is the credential type and the value is the value of the credential type. The configuration file is usually located in your application's classpath, the default location from where the client is going to try to find a ```keycloak.json``` file. -==== Creating the Authorization Client +== Creating the Authorization Client Considering you have a ```keycloak.json``` file in your classpath, you can create a new ```AuthzClient``` instance as follows: @@ -59,7 +59,7 @@ Considering you have a ```keycloak.json``` file in your classpath, you can creat AuthzClient authzClient = AuthzClient.create(); ``` -==== Obtaining User Entitlements +== Obtaining User Entitlements Here is an example illustrating how to obtain user entitlements: @@ -107,7 +107,7 @@ String rpt = response.getRpt(); // now you can use the RPT to access protected resources on the resource server ``` -==== Creating a Resource Using the Protection API +== Creating a Resource Using the Protection API ```java // create a new instance based on the configuration defined in keycloak-authz.json @@ -136,7 +136,7 @@ String resourceId = response.getId(); ResourceRepresentation resource = resourceClient.findById(resourceId).getResourceDescription(); ``` -==== Introspecting a RPT +== Introspecting a RPT ```java AuthzClient authzClient = AuthzClient.create(); @@ -148,4 +148,4 @@ ResourceRepresentation resource = resourceClient.findById(resourceId).getResourc // iterate over the granted permissions } } -``` \ No newline at end of file +``` diff --git a/authorization_services/topics/service/entitlement/entitlement-api-aapi.adoc b/authorization_services/topics/service-entitlement-entitlement-api-aapi.adoc similarity index 97% rename from authorization_services/topics/service/entitlement/entitlement-api-aapi.adoc rename to authorization_services/topics/service-entitlement-entitlement-api-aapi.adoc index e1d7a535e2..64e030934f 100644 --- a/authorization_services/topics/service/entitlement/entitlement-api-aapi.adoc +++ b/authorization_services/topics/service-entitlement-entitlement-api-aapi.adoc @@ -1,5 +1,5 @@ [[_service_entitlement_api_aapi]] -==== Requesting Entitlements += Requesting Entitlements Client applications can use a specific endpoint to obtain a special security token called a <<_service_rpt_overview, Requesting Party Token (RPT)>>. This token consists of all the entitlements (or permissions) for a user as a result of the evaluation of the permissions and authorization policies associated with the resources being requested. @@ -32,7 +32,7 @@ and his consent to access authorization data on his behalf. The access token mus After successfully invoking the Entitlement API endpoint, you will get a <<_service_rpt_overview, RPT>> with all permissions granted by the server. -===== Obtaining Entitlements +== Obtaining Entitlements The easiest way to obtain entitlements for a specific user is using an HTTP GET request. For example, using curl: @@ -63,7 +63,7 @@ other hand, *Alice Bank Account* is a resource where user *alice* is the owner. When obtaining entitlements for user *alice*, the server is going to evaluate all permissions associated with resources *Main Page* and *Alice Bank Account*. Giving you back a RPT (if permissions were actually granted) with a set of permissions representing these resources. -===== Obtaining Entitlements for a Specific Set of Resources +== Obtaining Entitlements for a Specific Set of Resources You can also use the entitlements endpoint to obtain a user's entitlements for a set of one or more resources. For example, using curl: @@ -102,7 +102,3 @@ curl -X POST -H "Authorization: Bearer ${access_token}" -d '{ ] }' "http://${host}:${port}/auth/realms/${realm_name}/authz/entitlement/{client_id}" ``` - - - - diff --git a/authorization_services/topics/service/entitlement/entitlement-api.adoc b/authorization_services/topics/service-entitlement-entitlement-api.adoc similarity index 96% rename from authorization_services/topics/service/entitlement/entitlement-api.adoc rename to authorization_services/topics/service-entitlement-entitlement-api.adoc index 852f6f1abf..cba921c1d1 100644 --- a/authorization_services/topics/service/entitlement/entitlement-api.adoc +++ b/authorization_services/topics/service-entitlement-entitlement-api.adoc @@ -1,5 +1,5 @@ [[_service_entitlement_api]] -=== Entitlement API += Entitlement API The Entitlement API provides a 1-legged protocol for obtaining authorization data from the server, where the authorization data represents the result of the evaluation of all permissions and authorization policies associated with the resources being requested. diff --git a/authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc b/authorization_services/topics/service-entitlement-entitlement-request-metadata.adoc similarity index 94% rename from authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc rename to authorization_services/topics/service-entitlement-entitlement-request-metadata.adoc index ec9512d312..c8315d5d68 100644 --- a/authorization_services/topics/service/entitlement/entitlement-request-metadata.adoc +++ b/authorization_services/topics/service-entitlement-entitlement-request-metadata.adoc @@ -1,5 +1,5 @@ [[_service_entitlement_request_metadata]] -==== Entitlement Request Metadata += Entitlement Request Metadata When requesting entitlements client applications are allowed to associate metadata information to the request and define how they expect to obtain the permissions. @@ -20,7 +20,7 @@ The Entitlement API endpoint only allows passing metadata along an entitlement r The following sections will explain how and when you can use the different information you can include in an entitlement request as a metadata. -==== Decide whether or not resource's name should be included the response += Decide whether or not resource's name should be included the response .include_resource_name ```bash @@ -39,7 +39,7 @@ can be used to reduce the size of RPTs and optimize client-server communication. By default, permissions in a RPT contain both the id and name of the resource that was granted by every single permission. This option is specially useful when the resource server is capable of map their resources only based on the resource`s id. -==== Limiting the number of permissions within a RPT += Limiting the number of permissions within a RPT .limit ```bash @@ -61,5 +61,3 @@ will include the first permissions defined there. This option allows clients to control the size of RPTs and keep only last permissions granted by the server. It usually makes sense only in cases your client is capable of sending previously issued RPTs while asking for new permissions (a.k.a.: incremental authorization). - - diff --git a/authorization_services/topics/service/entitlement/whatis-obtain-eat.adoc b/authorization_services/topics/service-entitlement-whatis-obtain-eat.adoc similarity index 96% rename from authorization_services/topics/service/entitlement/whatis-obtain-eat.adoc rename to authorization_services/topics/service-entitlement-whatis-obtain-eat.adoc index ca3c55ad5e..2e2116a6b2 100644 --- a/authorization_services/topics/service/entitlement/whatis-obtain-eat.adoc +++ b/authorization_services/topics/service-entitlement-whatis-obtain-eat.adoc @@ -1,5 +1,5 @@ [[_service_entitlement_whatis_obtain_eat]] -=== Entitlement API Tokens += Entitlement API Tokens An entitlement API token (EAT) is a special OAuth2 access token with the scope *kc_entitlement*. @@ -33,4 +33,4 @@ As a result, the server response is: === About the kc_entitlement scope -The *kc_entitlement* scope can be created like any other _realm role_, or as a _client role_. Once created, grant this role to the users of your realm. \ No newline at end of file +The *kc_entitlement* scope can be created like any other _realm role_, or as a _client role_. Once created, grant this role to the users of your realm. diff --git a/authorization_services/topics/service/overview.adoc b/authorization_services/topics/service-overview.adoc similarity index 79% rename from authorization_services/topics/service/overview.adoc rename to authorization_services/topics/service-overview.adoc index 9028485210..671fc67b46 100644 --- a/authorization_services/topics/service/overview.adoc +++ b/authorization_services/topics/service-overview.adoc @@ -1,7 +1,7 @@ [[_service_overview]] -== Authorization Services += Authorization Services {project_name} Authorization Services are based on OAuth2's User-Managed Access (UMA) Profile. This section describes the different RESTful endpoints that you can interact with to enable fine-grained authorization -for your applications and services. \ No newline at end of file +for your applications and services. diff --git a/authorization_services/topics/service/protection/permission-api-papi.adoc b/authorization_services/topics/service-protection-permission-api-papi.adoc similarity index 97% rename from authorization_services/topics/service/protection/permission-api-papi.adoc rename to authorization_services/topics/service-protection-permission-api-papi.adoc index ed170c9739..7e1e4e777d 100644 --- a/authorization_services/topics/service/protection/permission-api-papi.adoc +++ b/authorization_services/topics/service-protection-permission-api-papi.adoc @@ -1,5 +1,5 @@ [[_service_protection_permission_api_papi]] -==== Managing Permission Requests += 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. @@ -32,4 +32,4 @@ Client wise, a permission ticket has also important aspects that its worthy to h * Clients can have access to resources on different resource servers and protected by different authorization servers These are just some of the benefits brought by UMA where other aspects of UMA are strongly based on permission tickets, specially regarding -privacy and user controlled access to their resources. \ No newline at end of file +privacy and user controlled access to their resources. diff --git a/authorization_services/topics/service/protection/protection-api.adoc b/authorization_services/topics/service-protection-protection-api.adoc similarity index 89% rename from authorization_services/topics/service/protection/protection-api.adoc rename to authorization_services/topics/service-protection-protection-api.adoc index 16cef4a301..50981879a4 100644 --- a/authorization_services/topics/service/protection/protection-api.adoc +++ b/authorization_services/topics/service-protection-protection-api.adoc @@ -1,5 +1,5 @@ [[_service_protection_api]] -=== Protection API += Protection API The Protection API provides a UMA-compliant set of endpoints providing: @@ -12,4 +12,4 @@ With this endpoint, resource servers can manage their resources remotely and ena In the UMA protocol, resource servers access this endpoint, which issues permission tickets. An important requirement for this API is that _only_ resource servers are allowed to access its endpoints using a special OAuth2 access token called a protection API token (PAT). -In UMA, a PAT is a token with the scope *uma_protection*. \ No newline at end of file +In UMA, a PAT is a token with the scope *uma_protection*. diff --git a/authorization_services/topics/service/protection/resources-api-papi.adoc b/authorization_services/topics/service-protection-resources-api-papi.adoc similarity index 91% rename from authorization_services/topics/service/protection/resources-api-papi.adoc rename to authorization_services/topics/service-protection-resources-api-papi.adoc index 2d94bc47a3..e42d3c9948 100644 --- a/authorization_services/topics/service/protection/resources-api-papi.adoc +++ b/authorization_services/topics/service-protection-resources-api-papi.adoc @@ -1,5 +1,5 @@ [[_service_protection_resources_api]] -==== Managing Resources += Managing Resources Resource servers can manage their resources remotely using a UMA-compliant endpoint. @@ -16,4 +16,4 @@ This endpoint provides registration operations outlined as follows (entire path * List resource set descriptions: GET /resource_set * List resource set descriptions using a filter: GET /resource_set?filter=${filter} -For more information about the contract for each of these operations, see https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html[UMA Resource Set Registration]. \ No newline at end of file +For more information about the contract for each of these operations, see https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html[UMA Resource Set Registration]. diff --git a/authorization_services/topics/service-protection-resources-api.adoc b/authorization_services/topics/service-protection-resources-api.adoc new file mode 100644 index 0000000000..e42d3c9948 --- /dev/null +++ b/authorization_services/topics/service-protection-resources-api.adoc @@ -0,0 +1,19 @@ +[[_service_protection_resources_api]] += Managing Resources + +Resource servers can manage their resources remotely using a UMA-compliant endpoint. + +```bash +http://${host}:${port}/auth/realms/${realm_name}/authz/protection/resource_set +``` + +This endpoint provides registration operations outlined as follows (entire path omitted for clarity): + +* Create resource set description: POST /resource_set +* Read resource set description: GET /resource_set/{_id} +* Update resource set description: PUT /resource_set/{_id} +* Delete resource set description: DELETE /resource_set/{_id} +* List resource set descriptions: GET /resource_set +* List resource set descriptions using a filter: GET /resource_set?filter=${filter} + +For more information about the contract for each of these operations, see https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html[UMA Resource Set Registration]. diff --git a/authorization_services/topics/service/protection/whatis-obtain-pat.adoc b/authorization_services/topics/service-protection-whatis-obtain-pat.adoc similarity index 94% rename from authorization_services/topics/service/protection/whatis-obtain-pat.adoc rename to authorization_services/topics/service-protection-whatis-obtain-pat.adoc index c2e707b132..4c44106453 100644 --- a/authorization_services/topics/service/protection/whatis-obtain-pat.adoc +++ b/authorization_services/topics/service-protection-whatis-obtain-pat.adoc @@ -1,5 +1,5 @@ [[_service_protection_whatis_obtain_pat]] -==== What is a PAT and How to Obtain It += 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, {project_name} automatically creates a role, _uma_protection_, for the corresponding client application and associates it with the client's service account. @@ -34,4 +34,4 @@ The example above is using the *client_credentials* grant type to obtain a PAT f [NOTE] {project_name} can authenticate your client application in different ways. For simplicity, the *client_credentials* grant type is used here, -which requires a _client_id_ and a _client_secret_. You can choose to use any supported authentication method. \ No newline at end of file +which requires a _client_id_ and a _client_secret_. You can choose to use any supported authentication method. diff --git a/authorization_services/topics/service/rpt/overview.adoc b/authorization_services/topics/service-rpt-overview.adoc similarity index 95% rename from authorization_services/topics/service/rpt/overview.adoc rename to authorization_services/topics/service-rpt-overview.adoc index c6dc90b729..47594f552c 100644 --- a/authorization_services/topics/service/rpt/overview.adoc +++ b/authorization_services/topics/service-rpt-overview.adoc @@ -1,5 +1,5 @@ [[_service_rpt_overview]] -=== Requesting Party Token += Requesting Party Token A requesting party token (RPT) is a https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] digitally signed using https://www.rfc-editor.org/rfc/rfc7515.txt[JSON web signature (JWS)]. The token is built based on the OAuth2 access token previously issued by {project_name} to a specific client acting on behalf of an user or on its own behalf. @@ -29,4 +29,4 @@ When you decode an RPT, you see a payload similar to the following: From this token you can obtain all permissions granted by the server from the *permissions* claim. Also note that permissions are directly related with the resources/scopes you are protecting and complete decoupled from -the access control methods that were used to actually grant and issue these same permissions. \ No newline at end of file +the access control methods that were used to actually grant and issue these same permissions. diff --git a/authorization_services/topics/service/rpt/token-introspection.adoc b/authorization_services/topics/service-rpt-token-introspection.adoc similarity index 94% rename from authorization_services/topics/service/rpt/token-introspection.adoc rename to authorization_services/topics/service-rpt-token-introspection.adoc index 42dd22d47f..475246f1b5 100644 --- a/authorization_services/topics/service/rpt/token-introspection.adoc +++ b/authorization_services/topics/service-rpt-token-introspection.adoc @@ -1,5 +1,5 @@ [[_service_protection_token_introspection]] -==== Introspecting a Requesting Party Token += 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. @@ -8,7 +8,7 @@ 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 <<_enforcer_overview, policy enforcers>> fits your application -==== Obtaining Information about an RPT += Obtaining Information about an RPT The token introspection is essentially a https://tools.ietf.org/html/rfc7662[OAuth2 token introspection]-compliant endpoint from which you can obtain information about an RPT. @@ -65,7 +65,7 @@ If the RPT is not active, this response is returned instead: } ``` -==== Do I Need to Invoke the Server Every Time I Want to Introspect an RPT? += Do I Need to Invoke the Server Every Time I Want to Introspect an RPT? No. Both <<_service_entitlement_api, Entitlement>> APIs use the https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] specification as the default format for RPTs. @@ -76,4 +76,4 @@ you can also use the permissions within the token to enforce authorization decis This is essentially what the <<_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 \ No newline at end of file +* Query for token validity based on its _exp_, _iat_, and _aud_ claims