RHSSO-599, 598: fix headers and remaining links issues

SUMMARY.adoc

@@ -6,6 +6,7 @@
 
    .. link:topics/overview/terminology.adoc[Terminology]
 
+{% if book.community %}
  . link:topics/getting-started/overview.adoc[Getting Started]
 
    .. link:topics/getting-started/hello-world/overview.adoc[Securing a Servlet Application]
@@ -14,9 +15,10 @@
 
       ... link:topics/getting-started/hello-world/create-resource-server.adoc[Enabling Authorization Services]
 
- ... link:topics/getting-started/hello-world/deploy.adoc[Build, Deploy and Test]
+      ... link:topics/getting-started/hello-world/deploy.adoc[Build, Deploy, and Test]
 
    .. link:topics/example/overview.adoc[Examples]
+ {% endif %} 
  
  . link:topics/resource-server/overview.adoc[Managing Resource Servers]
 
@@ -101,3 +103,4 @@
       ... link:topics/enforcer/js-adapter.adoc[JavaScript Integration]
 
       ... link:topics/enforcer/https.adoc[Setting up TLS/HTTPS]
+

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.

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, make sure your adapter is configured as follows:
 

topics/enforcer/js-adapter.adoc

@@ -1,5 +1,5 @@
 [[_enforcer_js_adapter]]
-== JavaScript Integration
+=== JavaScript Integration
 
 The {{book.project.name}} Server comes with a JavaScript library you can use to interact with a resource server protected by a policy enforcer.
 This library is based on the {{book.external_link.keycloakjsadapter.link}}[{{book.project.name}} {{book.external_link.keycloakjsadapter.name}}], which can be integrated to allow your client to obtain permissions from a {{book.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 {{book.project.name}} {{book.project.module}} to obtain tokens with
 permissions your client can use as bearer tokens to access the protected resources on a resource server.
 
-=== Handling Authorization Responses from a Resource Server
+==== 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 <<fake/../keycloak-enforcement-bearer.adoc#_enforcer_bearer, bearer token>>.
 Typically, when you try to access a resource server with a bearer token that is lacking permissions to access a protected resource, the resource server
@@ -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):
 

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

topics/enforcer/keycloak-enforcement-filter.adoc

@@ -1,5 +1,5 @@
 [[_enforcer_filter]]
-== {{book.project.name}} Adapter Policy Enforcer
+=== {{book.project.name}} Adapter Policy Enforcer
 
 You can enforce authorization decisions for your applications if you are using {{book.project.name}} OIDC adapters.
 
@@ -10,7 +10,7 @@ when you create a resource server, {{book.project.name}} creates a <<fake/../../
 
 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:
 

topics/getting-started/hello-world/before-start.adoc

@@ -1,4 +1,4 @@
-== Before You Start
+=== Before You Start
 
 This guide is based on the *{{book.project.name}} Demo Distribution*. Download the demo distribution before proceeding.
 

topics/getting-started/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:
 

topics/getting-started/hello-world/create-resource-server.adoc

@@ -1,5 +1,5 @@
 [[_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.
 

topics/getting-started/hello-world/deploy.adoc

@@ -1,9 +1,9 @@
 [[_getting_started_hello_world_deploy]]
-== Building, Deploying, and Testing Your Application
+=== Building, Deploying, and Testing Your Application
 
 Now that the *hello-world-authz-service* resource server (or client) is properly configured and authorization services are enabled, it can be deployed to the server.
 
-=== Obtaining the Adapter Configuration
+==== Obtaining the Adapter Configuration
 
 You must first obtain the adapter configuration before building and deploying the application. 
 
@@ -31,7 +31,7 @@ image:../../../images/getting-started/hello-world/adapter-config.png[alt="Adapte
 
 This change specifies to the policy enforcer to redirect users to a `/hello-world-authz-service/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, navigate to the *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/hello-world-authz-service/* directory and execute the following command:
 
@@ -39,7 +39,7 @@ To build and deploy the application, navigate to the *${KEYCLOAK_DEMO_SERVER_DIR
 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/hello-world-authz-service[http://localhost:8080/hello-world-authz-service]. The {{book.project.name}} Login page opens.
 
@@ -73,7 +73,7 @@ image:../../../images/getting-started/hello-world/access-denied-page.png[alt="Ac
 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:
 

topics/getting-started/hello-world/overview.adoc

@@ -1,5 +1,5 @@
 [[_getting_started_hello_world_overview]]
-== Hello World
+=== Hello World
 
 The purpose of this getting started guide is to get you up and running as quickly as possible so that you can experiment with and test various authorization features provided by {{book.project.name}}.
 This quick tour relies heavily on the default database and server configurations and does not cover complex deployment options.

topics/overview/architecture.adoc

@@ -1,5 +1,5 @@
 [[_overview_architecture]]
-== Architecture
+=== Architecture
 
 image:../../images/authz-arch-overview.png[alt="{{book.project.name}} AuthZ Architecture Overview"]
 
@@ -27,7 +27,7 @@ Provides implementations for different environments to actually enforce authoriz
 +
 Being based on {{book.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 KC to enable fine-grained authorization to your applications:
 
@@ -35,7 +35,7 @@ Three main processes define the necessary steps to understand how to use KC to e
 * *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 {{book.project.name}} Administration Console
 
 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"]
 {{book.project.name}} provides some built-in <<fake/../../enforcer/overview.adoc#_enforcer_overview, Policy Enforcers>> implementations that you can use to protect your applications depending on the platform they are running on.
 
 
-=== Authorization Services
+==== 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://docs.kantarainitiative.org/uma/rec-uma-core.html[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 <<fake/../../service/protection/protection-api.adoc#_service_protection_api, Protection API>>.
 
-==== Authorization API
+===== Authorization API
 
 The Authorization API is also a https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA-compliant] endpoint providing a single operation that exchanges an Access Token and <<fake/.././terminology.adoc#_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 <<fake/../../service/authorization/authorization-api.adoc#_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.
 

topics/overview/overview.adoc

@@ -2,7 +2,7 @@
 == Overview
 
 {% if book.product %}
-{{book.project.module}} is a Technology Preview feature and is not fully supported. This feature is disabled by default.
+NOTE: {{book.project.module}} is a Technology Preview feature and is not fully supported. This feature is disabled by default.
 
 To enable {{book.project.module}} add the `standalone/configuration/profile.properties` file with the contents `profile=preview`
 or start the server with `-Dkeycloak.profile=preview` to enable all technology preview features.

topics/overview/terminology.adoc

@@ -1,9 +1,9 @@
 [[_overview_terminology]]
-== Terminology
+=== Terminology
 
 Before going further, it is important to understand these terms and concepts introduced by {{book.project.name}} {{book.project.module}}.
 
-=== 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.
 
@@ -13,20 +13,20 @@ authenticate users usually store that information in the user's session and retr
 
 In {{book.project.name}}, any *confidential* client application can act as a resource server. This client's resources and their respective scopes are protected and governed by a set of authorization policies.
 
-=== Resource
+==== 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:
 
@@ -44,7 +44,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).
@@ -55,7 +55,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 {{book.project.name}} {{book.project.module}} follows the divide-and-conquer technique.
 That is, you can create individual policies, then reuse them with different permissions and build more complex policies by combining individual policies.
 
-=== Policy Provider
+==== Policy Provider
 
 Policy providers are implementations of specific policy types. {{book.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.
@@ -63,7 +63,7 @@ policy providers, and you can create your own policy types to support your speci
 {{book.project.name}} provides a SPI (Service Provider Interface) that you can use to plug in your own policy provider implementations.
 
 [[_overview_terminology_permission_ticket]]
-=== Permission Ticket
+==== Permission Ticket
 
 A permission ticket is a special type of token defined by the https://docs.kantarainitiative.org/uma/rec-uma-core.html[OAuth2's User-Managed Access (UMA) Profile] specification that provides an opaque structure whose form is determined by the authorization server. This
 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]).

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:../../images/permission/create-resource.png[alt="Add Resource-Based Permission"]
 
-=== Configuration
+==== Configuration
 
 * *Name*
 +

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:../../images/permission/create-scope.png[alt="Add Scope-Based Permission"]
 
-=== Configuration
+==== Configuration
 
 * *Name*
 +

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.
 

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 <<fake/../../resource/create.adoc#_resource_create_type, type>>. This form of resource-based permission can be useful when you have resources sharing common access requirements and constraints.
 

topics/policy/aggregated-policy.adoc

@@ -1,5 +1,5 @@
 [[_policy_aggregated]]
-== Aggregated Policies
+=== Aggregated Policies
 
 As mentioned previously, {{book.project.name}} allows you to build a policy of policies, a concept referred to as policy aggregation. You can use policy aggregation to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the policies that are evaluated during the processing of authorization requests.
 
@@ -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 <<fake/../logic.adoc#_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.
 

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 {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_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:../../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 <<fake/../logic.adoc#_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:

topics/policy/evaluation-api.adoc

@@ -1,5 +1,5 @@
 [[_policy_evaluation_api]]
-== Evaluation API
+=== Evaluation API
 
 When writing rule-based policies using JavaScript or JBoss Drools, {{book.project.name}} provides an Evaluation API that provides useful information to help determine whether a permission should be granted.
 
@@ -46,7 +46,7 @@ When processing an authorization request, {{book.project.name}} creates an `Eval
 
 Policies determine this by invoking the `grant()` or `deny()` methods on an `Evaluation` instance. By default, the state of the `Evaluation` instance is denied, which means that your policies must explicitly invoke the `grant()` method to indicate to the policy evaluation engine that permission should be granted.
 
-=== The Evaluation Context
+==== The Evaluation Context
 
 The evaluation context provides useful information to policies during their evaluation.
 

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 {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_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:../../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 <<fake/../logic.adoc#_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:

topics/policy/logic.adoc

@@ -1,5 +1,5 @@
 [[_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.
 

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.

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-Based* in the dropdown list in t
 .Add Role-Based Policy
 image:../../images/policy/create-role.png[alt="Add Role-Based Policy"]
 
-=== Configuration
+==== Configuration
 
 * *Name*
 +

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:../../images/policy/create-time.png[alt="Add Time Policy"]
 
-=== Configuration
+==== Configuration
 
 * *Name*
 +

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-Based* in the dropdown list in t
 .Add a User-Based Policy
 image:../../images/policy/create-user.png[alt="Add User-Based Policy"]
 
-=== Configuration
+==== Configuration
 
 * *Name*
 +

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 {{book.project.name}} {{book.project.module}} is to create the client application that you want to turn into a resource server. 
 

topics/resource-server/default-config.adoc

@@ -1,5 +1,5 @@
 [[_resource_server_default_config]]
-== Default Configuration
+=== Default Configuration
 
 When you create a resource server, {{book.project.name}} creates a default configuration for your newly created resource server.
 
@@ -41,6 +41,6 @@ image:../../images/resource-server/default-permission.png[alt="Default Permissio
 
 This permission is a <<fake/../../permission/create-resource.adoc#_permission_create_resource, resource-based permission>>, defining a set of one or more policies that are applied to all resources with a given type.
 
-== Changing the Default Configuration
+=== Changing the Default Configuration
 
 You can change the default configuration by removing the default resource, policy, or permission definitions and creating your own.

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*.
 
@@ -37,7 +37,7 @@ From this page, you can manage the <<fake/../../permission/overview.adoc#_permis
 +
 From this page, you can <<fake/../../policy-evaluation-tool/overview.adoc#_policy_evaluation_overview, simulate authorization requests>> and view the result of the evaluation of the permissions and authorization policies you have defined.
 
-=== Resource Server Settings
+==== 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.
 

topics/resource-server/import-config.adoc

@@ -1,5 +1,5 @@
 [[_resource_server_import_config]]
-== Exporting and Importing Configuration Files
+=== Exporting and Importing Configuration Files
 
 The configuration settings for a resource server (or client) can be exported and downloaded. You can also import an existing configuration file for a resource server. Importing and exporting a configuration file is helpful when you want to create an initial configuration for a resource server or to update an existing configuration. The configuration file contains definitions for:
 
@@ -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:../../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.

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 <<fake/../../service/protection/protection-api.adoc#_service_protection_api, Protection API>> to allow resource servers to remotely manage their resources.
 

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 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.
@@ -27,7 +27,7 @@ As a result, the server response is:
 {"rpt":"${RPT}"}
 ```
 
-=== 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 AAT sent by the client during the authorization process.

topics/service/authorization/authorization-api.adoc

@@ -1,5 +1,5 @@
 [[_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.

topics/service/authorization/whatis-obtain-aat.adoc

@@ -1,5 +1,5 @@
 [[_service_authorization_aat]]
-== Authorization API Token
+=== Authorization API Token
 
 An authorization API token (AAT) is a special OAuth2 access token with the scope *uma_authorization*. When you create a user, {{book.project.name}} automatically
 assigns the role _uma_authorization_ to the user. The _uma_authorization_ role is a default realm role.

topics/service/client-api.adoc

@@ -1,9 +1,9 @@
 [[_service_client_api]]
-== Authorization Client API
+=== Authorization Client API
 
 If you are using Java, you can access all {{book.project.name}} {{book.project.module}} using a client API.
 
-=== Maven Dependency
+==== Maven Dependency
 
 ```xml
 <dependencies>
@@ -15,7 +15,7 @@ If you are using Java, you can access all {{book.project.name}} {{book.project.m
 </dependencies>
 ```
 
-=== Configuration
+==== Configuration
 
 The client configuration is defined in a JSON file as follows:
 
@@ -45,7 +45,7 @@ The client-id of the application. Each application has a client-id that is used
 * *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. Currently only secret/password is supported. 
 
-=== Obtaining User Entitlements
+==== Obtaining User Entitlements
 
 Here is an example illustrating how to obtain user entitlements:
 
@@ -97,7 +97,7 @@ String rpt = response.getRpt();
 System.out.println("You got a RPT: " + rpt);
 ```
 
-=== 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

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 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.
@@ -9,7 +9,7 @@ With an RPT, client applications can gain access to protected resources at the r
 http://${host}:${port}/auth/realms/${realm_name}/authz/entitlement
 ```
 
-=== Obtaining Entitlements
+==== Obtaining Entitlements
 
 The easiest way to obtain entitlements for a specific user is using an HTTP GET request. For example, using curl:
 
@@ -35,7 +35,7 @@ As a result, the server response is:
 Using this method to obtain entitlements, the server responds to the requesting client with *all* entitlements for a user, based on the evaluation of the permissions and
 authorization policies associated with the resources managed by the resource server.
 
-=== 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:
 
@@ -75,7 +75,7 @@ curl -X POST -H "Authorization: Bearer ${access_token}" -d '{
 }' "http://localhost:8080/auth/realms/hello-world-authz/authz/entitlement/hello-world-authz-service"
 ```
 
-=== 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 access_token sent by the client during the authorization process.
 

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.

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*.
 
@@ -31,6 +31,6 @@ As a result, the server response is:
 }
 ```
 
-== About the kc_entitlement scope
+=== 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.

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.
 

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:
 

topics/service/protection/resources-api-papi.adoc

@@ -1,5 +1,5 @@
 [[_service_protection_resources_api]]
-== Managing Resources Using the Protection API
+=== Managing Resources Using the Protection API
 
 Resource servers can manage their resources remotely using a UMA-compliant endpoint.
 

topics/service/protection/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 <<fake/../../../enforcer/overview.adoc#_enforcer_overview, policy enforcers>> fits your application
 
-=== Obtaining Information about a RPT
+==== Obtaining Information about a 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 a 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 a RPT?
+==== Do I Need to Invoke the Server Every Time I want to Introspect a RPT?
 
 No. Both <<fake/../../../service/authorization/authorization-api.adoc#_service_authorization_api, Authorization>> and <<fake/../../../service/entitlement/entitlement-api.adoc#_service_entitlement_api, Entitlement>> APIs use the
  https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] specification as the default format for RPTs.

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, {{book.project.name}} automatically
 creates a role, _uma_protection_, for the corresponding client application and associates it with the client's service account.