{"id":21630498,"url":"https://github.com/hawkular/hawkular-accounts","last_synced_at":"2025-04-11T14:06:36.818Z","repository":{"id":26959400,"uuid":"30422535","full_name":"hawkular/hawkular-accounts","owner":"hawkular","description":"Authorization system in Hawkular","archived":false,"fork":false,"pushed_at":"2017-07-18T09:38:47.000Z","size":1430,"stargazers_count":7,"open_issues_count":0,"forks_count":9,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-04-14T09:32:18.538Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hawkular.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-06T16:50:39.000Z","updated_at":"2020-11-04T13:27:33.000Z","dependencies_parsed_at":"2022-08-20T21:50:47.688Z","dependency_job_id":null,"html_url":"https://github.com/hawkular/hawkular-accounts","commit_stats":null,"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hawkular%2Fhawkular-accounts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hawkular%2Fhawkular-accounts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hawkular%2Fhawkular-accounts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hawkular%2Fhawkular-accounts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hawkular","download_url":"https://codeload.github.com/hawkular/hawkular-accounts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226260538,"owners_count":17596495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-25T02:11:12.228Z","updated_at":"2024-11-25T02:11:12.678Z","avatar_url":"https://github.com/hawkular.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Hawkular Accounts\n\nWARNING: Hawkular Accounts is deprecated. This repository can still be used as reference, but it's not currently being used by any Hawkular component.\n\nHawkular Accounts is the user/organization module for Hawkular projects. It provides the registration feature,\nsetting up of organizations and related features. The main registration and user login is provided by\nhttp://keycloak.jboss.org/[Keycloak], while organizations and permissions are implemented in Hawkular Accounts\nitself.\n\nHawkular is a monitoring suite, that consists of several sub-projects for\nstoring of metrics, alerting on incoming events and more. Those projects are developed\nin their own GitHub repositories.\n\nifdef::env-github[]\n[link=https://jenkins.kroehling.de/job/hawkular-accounts/]\nimage:https://jenkins.kroehling.de/buildStatus/icon?job=hawkular-accounts[\"Build Status\", link=\"https://jenkins.kroehling.de/job/hawkular-accounts/\"]\nendif::[]\n\n== About Accounts\n\nThe project is divided into several modules. More information about the individual modules can be found in the\nrespective module's README files.\n\n* accounts: the REST backend, handling the actions from the Hawkular Accounts UI.\n* api: the components that are intended to be consumed by other Hawkular components.\n* common: some common code, of internal consumption by Accounts components\n* dist: assembles a complete Wildfly with Keycloak and Hawkular Accounts, suitable for isolated development/testing.\n* events-backend: the REST backend for event processing (login, logout, ...)\n* events-listener: JMS-to-CDI bridge for Accounts events, for consumers of Accounts\n* integration-tests: tests that should exercise features (like, \"create an offline token\")\n* jaxb-adapters: common JAXB adapters for REST backends\n* keycloak-event-listener-*: bridges between Keycloak events and our events backend\n* sample: a sample on how to integrate Accounts into other Hawkular projects.\n* sample-websocket-backend: with -frontend, serves as an example of how to use Accounts for Auth/z in WebSockets\n* sample-websocket-frontend: for usage with sample-websocket-backend\n* sample-websocket-secured: example of how to deploy a secured websocket and its frontend in one module\n* secret-store: the REST backend for generating key/secret tokens backed by Keycloak Offline tokens\n* secret-store-api: components that are intended to be consumed by other Hawkular components\n* undertow-filter: for converting the key/secret tokens into OAuth Access tokens\n* websocket-api: the API for securing WebSockets\n\nThe user interface for Hawkular Accounts is located directly in the hawkular main project, under the \"console\" module.\n\n== Basic usage\n\nFirst, add the API as a dependency:\n[source,xml]\n----\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.hawkular.accounts\u003c/groupId\u003e\n  \u003cartifactId\u003ehawkular-accounts-api\u003c/artifactId\u003e\n  \u003cversion\u003e${project.version}\u003c/version\u003e\n\u003c/dependency\u003e\n----\n\nWith that, you can now inject the permission checker and other parts of the API directly into your EJBs and other\nmanaged beans.\n\nHawkular Accounts is based on the following concepts:\n\n* *Resource* - something that you want to protect; it might be an Alert, an Inventory item, a Metric, ...\n* *Persona* - either a User or an Organization. A real User can be impersonating an Organization, so, this Organization\n  would be the current Persona. In most cases, the current Persona corresponds to an intuitive notion of the\n  \"current user\" or \"current tenant\".\n* *User* - a real user of the application. In most cases, consumers of Hawkular Accounts do not need to deal directly\n  with users.\n* *Organization* - a non-user which has an Owner and a set of Members. In most cases, consumers of Hawkular Accounts\n  do not need to deal directly with organizations.\n* *Owner* - owns a Resource, and can be (currently) either a Hawkular User or an Organization.\n* *Member* - a User or Organization that can be part of an Organization.\n\nNote that the main Accounts API allows an Organization to be the Owner of another Organization. As some Hawkular\ncomponents might not be able to deal with this scenario, however, this is currently blocked from the REST endpoint.\nThis effectively means that organizations cannot create sub organizations.\n\nTo retrieve the current Persona:\n[source,java]\n----\n@Stateless\nclass FooService {\n    @Inject\n    Instance\u003cPersona\u003e persona;\n}\n----\n\nIn order to check if a Persona has access to a given Resource, a record of this resource should exist in Hawkular\nAccounts. For instance, if you need to protect a metric, you need to:\n\n* Create a Resource with a unique key (possibly the same ID you have in your persistent storage), specifying the\n  Owner (usually, the current Persona).\n* Later on, you can check if the current Persona (or whichever Persona relevant to you) has access to the resource, via\n  `PermissionChecker`.\n\nExample:\n[source,java]\n----\n@Stateless\nclass FooService {\n    @Inject\n    Instance\u003cPersona\u003e personaInstance;\n\n    @Inject\n    PermissionChecker permissionChecker;\n\n    @Inject\n    ResourceService resourceService;\n\n    @Inject\n    @NamedOperation(\"foo-read\")\n    Operation operationRead;\n\n    public void createFoo() {\n        Foo foo = new Foo(id); // this is your business resource\n\n        // the ID can be anything that is unique. When omitted, a new UUID is created and you'll be responsible for\n        // storing it somewhere and informing it next time you need access to this resource. Also, we need to\n        // explicitly know who is the owner.\n        resourceService.create(foo.getId(), personaInstance.get());\n\n        // your storage might be Cassandra, JPA-based storage, in memory map, ...\n        storage.persist(foo);\n    }\n\n    public Foo getFoo(String id) {\n        Foo foo = storage.getFoo(id); // this is your business resource\n\n        // when omitted, the user is assumed to be the current user on the permission checker\n        if (permissionChecker.isAllowedTo(operationRead, foo.getId())) {\n            // return it to the user\n        } else {\n            // return a forbidden message\n        }\n    }\n}\n----\n\n== Operations and Roles\n\nAs a one-time setup, the permission set needs to be configured. With that, a list of operations needs to be provided,\nas well as which roles are allowed to perform those operations. To facilitate this procedure, the `OrganizationService`\ncan be used as a `@Singleton @Startup` EJB, with the setup on a `@PostConstruct` method. Another possible approach,\nif you need to have control on the ordering of the startup items, is to implement it as a ServletContextListener. You\nmight refer to the `SetupOperations` on the `sample` module, which uses the `@Singleton @Startup` approach or\n`SetupHawkularAccountsImpl` on the `accounts` module, which uses the `ServletContextListener` approach.\n\nWARNING: Keep in mind that this setup is supposed to run only once during the lifecycle of your deployed module. By\nnature, you might have several operations, so, your transaction might run for a longer period of time than normal\ntransactions. If you have concurrent calls to your setup procedure, one transaction might overlap the other, causing\ndata consistency exceptions.\n\n[source,java]\n----\noperationService\n        .setup(\"organization-create\")\n        .add(\"Monitor\") // means: all roles\n        .persist()\n\n        .setup(\"organization-read\")\n        .add(\"Maintainer\")\n        .persist()\n\n        .setup(\"organization-delete\")\n        .add(\"SuperUser\")\n        .persist()\n\n        .setup(\"organization-update\")\n        .add(\"Maintainer\")\n        .persist();\n----\n\nOr, if you need to hold on to the operations that have been created in @PostConstruct, you can replace `persist()` with\n`make()`. E.g.:\n\n[source,java]\n----\n   createOperation = operationService.setup(\"organization-create\").add(\"Monitor\").make();\n   updateOperation = operationService.setup(\"organization-update\").add(\"Administrator\").make();\n----\n\nHawkular Accounts ships with the https://docs.jboss.org/author/display/WFLY9/RBAC[same roles] as Wildfly and with the\nsame rules (ie: SuperUser will be given permission to perform operations marked as allowed for \"user with at least\nMonitor role\"). So, adding the role \"Monitor\" during the setup will automatically add all other roles to it.\n\nNote as well that if the set of roles for a given operation has not changed from what we currently have in the\ndatabase, nothing is performed.\n\nMore about the Wildfly roles can be found in this\nlink:http://blog.arungupta.me/role-based-access-control-wildfly-8/[blog post]\n\n== How to build Hawkular Accounts from source\n\nThe API and backend can be build as a regular Maven project:\n[source,bash]\n----\n$ mvn clean install\n----\n\nTo build a distribution with Wildfly and Keycloak, use:\n[source,bash]\n----\n$ mvn clean install\n----\n\n== Releasing\n\nTo perform a release of Hawkular Accounts, you'll need push\npermissions to the GitHub repository and execute the following:\n\n[source,bash]\n----\nmvn clean\nmvn release:prepare release:perform -DautoVersionSubmodules=true\n----\n\nAnd accept all the default values (for versions and tags).\n\n== License\n\nHawkular Accounts is released under Apache License, Version 2.0 as described in the link:LICENSE[LICENSE] document\n\n----\n   Copyright 2015 Red Hat, Inc.\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n----\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhawkular%2Fhawkular-accounts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhawkular%2Fhawkular-accounts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhawkular%2Fhawkular-accounts/lists"}