https://github.com/hawkular/hawkular-accounts

Authorization system in Hawkular
https://github.com/hawkular/hawkular-accounts

Last synced: about 1 year ago
JSON representation

Authorization system in Hawkular

• Host: GitHub
• URL: https://github.com/hawkular/hawkular-accounts
• Owner: hawkular
• Created: 2015-02-06T16:50:39.000Z (over 11 years ago)
• Default Branch: master
• Last Pushed: 2017-07-18T09:38:47.000Z (almost 9 years ago)
• Last Synced: 2024-04-14T09:32:18.538Z (about 2 years ago)
• Language: Java
• Size: 1.36 MB
• Stars: 7
• Watchers: 10
• Forks: 9
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc

Awesome Lists containing this project

README

          
= Hawkular Accounts

WARNING: Hawkular Accounts is deprecated. This repository can still be used as reference, but it's not currently being used by any Hawkular component.

Hawkular Accounts is the user/organization module for Hawkular projects. It provides the registration feature,

setting up of organizations and related features. The main registration and user login is provided by

http://keycloak.jboss.org/[Keycloak], while organizations and permissions are implemented in Hawkular Accounts

itself.

Hawkular is a monitoring suite, that consists of several sub-projects for

storing of metrics, alerting on incoming events and more. Those projects are developed

in their own GitHub repositories.

ifdef::env-github[]

[link=https://jenkins.kroehling.de/job/hawkular-accounts/]

image:https://jenkins.kroehling.de/buildStatus/icon?job=hawkular-accounts["Build Status", link="https://jenkins.kroehling.de/job/hawkular-accounts/"]

endif::[]

== About Accounts

The project is divided into several modules. More information about the individual modules can be found in the

respective module's README files.

* accounts: the REST backend, handling the actions from the Hawkular Accounts UI.

* api: the components that are intended to be consumed by other Hawkular components.

* common: some common code, of internal consumption by Accounts components

* dist: assembles a complete Wildfly with Keycloak and Hawkular Accounts, suitable for isolated development/testing.

* events-backend: the REST backend for event processing (login, logout, ...)

* events-listener: JMS-to-CDI bridge for Accounts events, for consumers of Accounts

* integration-tests: tests that should exercise features (like, "create an offline token")

* jaxb-adapters: common JAXB adapters for REST backends

* keycloak-event-listener-*: bridges between Keycloak events and our events backend

* sample: a sample on how to integrate Accounts into other Hawkular projects.

* sample-websocket-backend: with -frontend, serves as an example of how to use Accounts for Auth/z in WebSockets

* sample-websocket-frontend: for usage with sample-websocket-backend

* sample-websocket-secured: example of how to deploy a secured websocket and its frontend in one module

* secret-store: the REST backend for generating key/secret tokens backed by Keycloak Offline tokens

* secret-store-api: components that are intended to be consumed by other Hawkular components

* undertow-filter: for converting the key/secret tokens into OAuth Access tokens

* websocket-api: the API for securing WebSockets

The user interface for Hawkular Accounts is located directly in the hawkular main project, under the "console" module.

== Basic usage

First, add the API as a dependency:

[source,xml]

----

  org.hawkular.accounts

  hawkular-accounts-api

  ${project.version}

----

With that, you can now inject the permission checker and other parts of the API directly into your EJBs and other

managed beans.

Hawkular Accounts is based on the following concepts:

* *Resource* - something that you want to protect; it might be an Alert, an Inventory item, a Metric, ...

* *Persona* - either a User or an Organization. A real User can be impersonating an Organization, so, this Organization

  would be the current Persona. In most cases, the current Persona corresponds to an intuitive notion of the

  "current user" or "current tenant".

* *User* - a real user of the application. In most cases, consumers of Hawkular Accounts do not need to deal directly

  with users.

* *Organization* - a non-user which has an Owner and a set of Members. In most cases, consumers of Hawkular Accounts

  do not need to deal directly with organizations.

* *Owner* - owns a Resource, and can be (currently) either a Hawkular User or an Organization.

* *Member* - a User or Organization that can be part of an Organization.

Note that the main Accounts API allows an Organization to be the Owner of another Organization. As some Hawkular

components might not be able to deal with this scenario, however, this is currently blocked from the REST endpoint.

This effectively means that organizations cannot create sub organizations.

To retrieve the current Persona:

[source,java]

----

@Stateless

class FooService {

    @Inject

    Instance persona;

}

----

In order to check if a Persona has access to a given Resource, a record of this resource should exist in Hawkular

Accounts. For instance, if you need to protect a metric, you need to:

* Create a Resource with a unique key (possibly the same ID you have in your persistent storage), specifying the

  Owner (usually, the current Persona).

* Later on, you can check if the current Persona (or whichever Persona relevant to you) has access to the resource, via

  `PermissionChecker`.

Example:

[source,java]

----

@Stateless

class FooService {

    @Inject

    Instance personaInstance;

    @Inject

    PermissionChecker permissionChecker;

    @Inject

    ResourceService resourceService;

    @Inject

    @NamedOperation("foo-read")

    Operation operationRead;

    public void createFoo() {

        Foo foo = new Foo(id); // this is your business resource

        // the ID can be anything that is unique. When omitted, a new UUID is created and you'll be responsible for

        // storing it somewhere and informing it next time you need access to this resource. Also, we need to

        // explicitly know who is the owner.

        resourceService.create(foo.getId(), personaInstance.get());

        // your storage might be Cassandra, JPA-based storage, in memory map, ...

        storage.persist(foo);

    }

    public Foo getFoo(String id) {

        Foo foo = storage.getFoo(id); // this is your business resource

        // when omitted, the user is assumed to be the current user on the permission checker

        if (permissionChecker.isAllowedTo(operationRead, foo.getId())) {

            // return it to the user

        } else {

            // return a forbidden message

        }

    }

}

----

== Operations and Roles

As a one-time setup, the permission set needs to be configured. With that, a list of operations needs to be provided,

as well as which roles are allowed to perform those operations. To facilitate this procedure, the `OrganizationService`

can be used as a `@Singleton @Startup` EJB, with the setup on a `@PostConstruct` method. Another possible approach,

if you need to have control on the ordering of the startup items, is to implement it as a ServletContextListener. You

might refer to the `SetupOperations` on the `sample` module, which uses the `@Singleton @Startup` approach or

`SetupHawkularAccountsImpl` on the `accounts` module, which uses the `ServletContextListener` approach.

WARNING: Keep in mind that this setup is supposed to run only once during the lifecycle of your deployed module. By

nature, you might have several operations, so, your transaction might run for a longer period of time than normal

transactions. If you have concurrent calls to your setup procedure, one transaction might overlap the other, causing

data consistency exceptions.

[source,java]

----

operationService

        .setup("organization-create")

        .add("Monitor") // means: all roles

        .persist()

        .setup("organization-read")

        .add("Maintainer")

        .persist()

        .setup("organization-delete")

        .add("SuperUser")

        .persist()

        .setup("organization-update")

        .add("Maintainer")

        .persist();

----

Or, if you need to hold on to the operations that have been created in @PostConstruct, you can replace `persist()` with

`make()`. E.g.:

[source,java]

----

   createOperation = operationService.setup("organization-create").add("Monitor").make();

   updateOperation = operationService.setup("organization-update").add("Administrator").make();

----

Hawkular Accounts ships with the https://docs.jboss.org/author/display/WFLY9/RBAC[same roles] as Wildfly and with the

same rules (ie: SuperUser will be given permission to perform operations marked as allowed for "user with at least

Monitor role"). So, adding the role "Monitor" during the setup will automatically add all other roles to it.

Note as well that if the set of roles for a given operation has not changed from what we currently have in the

database, nothing is performed.

More about the Wildfly roles can be found in this

link:http://blog.arungupta.me/role-based-access-control-wildfly-8/[blog post]

== How to build Hawkular Accounts from source

The API and backend can be build as a regular Maven project:

[source,bash]

----

$ mvn clean install

----

To build a distribution with Wildfly and Keycloak, use:

[source,bash]

----

$ mvn clean install

----

== Releasing

To perform a release of Hawkular Accounts, you'll need push

permissions to the GitHub repository and execute the following:

[source,bash]

----

mvn clean

mvn release:prepare release:perform -DautoVersionSubmodules=true

----

And accept all the default values (for versions and tags).

== License

Hawkular Accounts is released under Apache License, Version 2.0 as described in the link:LICENSE[LICENSE] document

----

   Copyright 2015 Red Hat, Inc.

   Licensed under the Apache License, Version 2.0 (the "License");

   you may not use this file except in compliance with the License.

   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software

   distributed under the License is distributed on an "AS IS" BASIS,

   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

   See the License for the specific language governing permissions and

   limitations under the License.

----