2016-06-17 05:07:34 +00:00
# About the Example Application
This is a simple application based on HTML5+AngularJS+JAX-RS that will introduce you to some of the main concepts around Keycloak Authorization Services.
Basically, it is a project containing three modules:
2016-06-22 17:33:29 +00:00
* **photoz-restful-api**, a simple RESTFul API based on JAX-RS and acting as a resource server.
* **photoz-html5-client**, a HTML5+AngularJS client that will consume the RESTful API published by a resource resourcer.
* **photoz-authz-policy**, a simple project with some rule-based policies using JBoss Drools.
2016-06-17 05:07:34 +00:00
For this application, users can be regular users or administrators. Regular users can create/view/delete their albums
2016-06-22 17:33:29 +00:00
and administrators can do anything.
2016-06-17 05:07:34 +00:00
2016-06-22 17:33:29 +00:00
In Keycloak, albums are resources that must be protected based on a set of policies that defines who and how can access them.
2016-06-17 05:07:34 +00:00
2016-06-22 17:33:29 +00:00
The resources are also associated with a set of scopes that defines a specific access context. In this case, albums have three main scopes:
2016-06-17 05:07:34 +00:00
* urn:photoz.com:scopes:album:create
* urn:photoz.com:scopes:album:view
* urn:photoz.com:scopes:album:delete
The authorization requirements for this example application are based on the following assumptions:
* By default, any regular user can perform any operation on his resources.
* For instance, Alice can create, view and delete her albums.
2016-06-22 17:33:29 +00:00
* Only the owner and administrators can delete albums. Here we are considering policies based on the *urn:photoz.com:scopes:album:delete* scope
2016-06-17 05:07:34 +00:00
* For instance, only Alice can delete her album.
* Only administrators can access the Administration API (which basically provides ways to query albums for all users)
2016-06-22 17:33:29 +00:00
* Administrators are only authorized to access resources if the client's ip address is well known
2016-06-17 05:07:34 +00:00
That said, this application will show you how to use the Keycloak to define policies using:
* Role-based Access Control
* Attribute-based Access Control
* Rule-based policies using JBoss Drools
* Rule-based policies using JavaScript
Beside that, this example demonstrates how to create resources dynamically and how to protected them using the *Protection API* and the *Authorization Client API* . Here you'll see
how to create a resource whose owner is the authenticated user.
It also provides some background on how you can actually protect your JAX-RS endpoints using a *policy enforcer* .
## Create the Example Realm and a Resource Server
2016-06-23 04:02:39 +00:00
Considering that your Keycloak Server is up and running, log in to the Keycloak Administration Console.
2016-06-17 05:07:34 +00:00
Now, create a new realm based on the following configuration file:
2016-06-22 17:33:29 +00:00
examples/authz/photoz/photoz-realm.json
2016-06-17 05:07:34 +00:00
That will import a pre-configured realm with everything you need to run this example. For more details about how to import a realm
into Keycloak, check the Keycloak's reference documentation.
After importing that file, you'll have a new realm called ``photoz``.
Back to the command-line, build the example application. This step is necessary given that we're using policies based on
2016-06-22 17:33:29 +00:00
JBoss Drools, which require ``photoz-authz-policy`` artifact installed into your local maven repository.
2016-06-17 05:07:34 +00:00
cd examples/authz/photoz
mvn clean install
2016-11-02 20:11:30 +00:00
> Please make sure you have the environment variable M2_HOME set. It should reference the path for your Maven installation. If not set, you will see some WARN messages in the logs when booting Keycloak.
2016-06-17 05:07:34 +00:00
2016-06-23 04:02:39 +00:00
Now, let's import another configuration using the Administration Console in order to configure the client application ``photoz-restful-api`` as a resource server with all resources, scopes, permissions and policies.
2016-06-17 05:07:34 +00:00
2016-06-23 04:02:39 +00:00
Click on ``Clients`` on the left side menu. Click on the ``photoz-restful-api`` on the client listing page. This will
open the ``Client Details`` page. Once there, click on the `Authorization` tab.
2016-06-17 05:07:34 +00:00
Click on the ``Select file`` button, which means you want to import a resource server configuration. Now select the file that is located at:
2016-11-02 20:11:30 +00:00
examples/authz/photoz/photoz-restful-api/src/main/resources/photoz-restful-api-authz-service.json
2016-06-17 05:07:34 +00:00
2016-06-23 04:02:39 +00:00
Now click ``Upload`` and the resource server will be updated accordingly.
2016-06-17 05:07:34 +00:00
## Deploy and Run the Example Applications
To deploy the example applications, follow these steps:
2016-06-22 17:33:29 +00:00
cd examples/authz/photoz/photoz-html5-client
2016-06-23 04:02:39 +00:00
mvn clean package wildfly:deploy
2016-06-17 05:07:34 +00:00
And then:
2016-06-22 17:33:29 +00:00
cd examples/authz/photoz/photoz-restful-api
2016-06-23 04:02:39 +00:00
mvn clean package wildfly:deploy
2016-06-17 05:07:34 +00:00
Now, try to access the client application using the following URL:
2016-06-22 17:33:29 +00:00
http://localhost:8080/photoz-html5-client
2016-06-17 05:07:34 +00:00
If everything is correct, you will be redirect to Keycloak login page. You can login to the application with the following credentials:
* username: jdoe / password: jdoe
* username: alice / password: alice
2016-06-23 04:02:39 +00:00
* username: admin / password: admin