* Create a realm with the necessary configuration to enable fine-grained authorization to a servlet application
* Create a resource server and the resources that must be protected
* Create permissions, authorization policies and how to apply them to your protected resources
* Configure the {{book.project.name}} Authorization Enforcer Filter to your servlet application
The application we are using in this guide is one of the examples provided by the {{book.project.name}} Demo Distribution. You can find all the source code
under *examples/authz/servlet-authz/*.
[NOTE]
Before going further, make sure you followed all the instructions in the link:../getting-started/getting-started.html[Getting Started] guide.
=== About the Servlet Application
The application we are about to create is a very simple. In a nutshell, it implements the following security requirements:
* An _Administration Area_ that only administrators can access
* An _User Premium Area_ that only users with a premium plan can access
"description": "Allows access to the Protection API"
}
]
},
"clients": [
{
"clientId": "servlet-authz-app",
"enabled": true,
"publicClient": false,
"baseUrl": "/servlet-authz-app",
"adminUrl": "/servlet-authz-app",
"bearerOnly": false,
"serviceAccountsEnabled": true,
"redirectUris": [
"/servlet-authz-app/*"
],
"secret": "secret"
}
]
}
```
=== Creating a Resource Server and Protecting Resources
Now that we have the *servlet-authz* realm properly configured, we need to enable the *servlet-authz-app* as a resource server. For that, click on the *Authorization* in the left menu bar.
From that page you can create a resource server by manually filling that form or you can just import a JSON file with the configuration you want. For this guide, we'll just import a JSON file as follows:
All this configuration can also be done using the {{book.project.name}} Administration Console. We are using the import tool just for demonstration purposes
=== A Quick Overview of the Permissions and Policies
The resource server configuration tells a lot about what we are really protecting. It is basically describing the security requirements we have discussed earlier.
As the name implies, each of these resources are related with the requirements we previously discussed, representing the different areas or group of resources we want to protect.
As you may notice, each of these resources (except Main Page) defines an *uri* property. This property represents the path we want to protect and maps directly, or indirectly by using a pattern,
This resource represents all resources in the application, as you can see from the pattern used in the *uri* property. It also defines a single scope/action to indicate that users, if granted, can access this resource.
Now, let's see what are the permissions and authorization policies configured to this resource:
```json
...
{
"name": "Protected Resource Permission",
"description": "A policy that defines access to any protected resource",
"type": "resource",
"decisionStrategy": "AFFIRMATIVE",
"config": {
"resources": "[\"Protected Resource\"]",
"applyPolicies": "[\"All Users Policy\"]"
}
},
...
```
The definition above is a permission that links the _Protected Resource_ with the policies we want to apply. In this case, we are applying a single _All Users Policy_.
Policies define the conditions to be meet in order to access something. In this case, the _All Users Policy_ is composed of two other policies, a special policy type called link:../policy/aggregated-policy.html[Aggregated Policies].
```json
...
{
"name": "All Users Policy",
"description": "Defines that all users can do something",
"type": "aggregate",
"decisionStrategy": "AFFIRMATIVE",
"config": {
"applyPolicies": "[\"Any User Policy\",\"Any Admin Policy\",\"Only Premium User Policy\"]"
}
},
...
```
{{book.project.name}} provides a few built-in policy types (and their respective policy providers) implementing different access control mechanisms (RBAC, GBAC, Rule-based, Time-based, etc) that you can use to build your own policies and permissions.
Aggregated policies are very useful in order to group related policies together and make policy management less painful.
Now that we have all the configuration for our resource server in place, we can configure the authorization enforcement filter to actually protect resources.
The *org.keycloak.authorization.policy.enforcer.servlet.KeycloakAdapterEnforcementFilter* is shipped with the {{book.project.name}} OIDC Adapters distribution. In order to make it available to
your application at runtime, you must create a *META-INF/jboss-deployment-structure.xml* at the application root directory. If you are using maven, this file can be placed under *src/main/webapp/META-INF/jboss-deployment-structure.xml*:
For last, you need to create a *META-INF/keycloak-authz.json* and put it in your application's classpath. If you are using Maven, this file goes inside *src/main/resources*:
There you can execute the following command to _deploy_ the application to the running server:
```bash
mvn clean package wildfly:deploy
```
That should be enough to get the application properly packaged and deployed to a _running_ {{book.project.name}} server.
If the application was properly deployed, you can try to access it at http://localhost:8080/auth[http://localhost:8080/servlet-authz-app] and use the following credentials to login into the application:
* username: alice / password: alice (regular user)
