|
| 1 | +<!-- |
| 2 | + Licensed to the Apache Software Foundation (ASF) under one |
| 3 | + or more contributor license agreements. See the NOTICE file |
| 4 | + distributed with this work for additional information |
| 5 | + regarding copyright ownership. The ASF licenses this file |
| 6 | + to you under the Apache License, Version 2.0 (the |
| 7 | + "License"); you may not use this file except in compliance |
| 8 | + with the License. You may obtain a copy of the License at |
| 9 | + |
| 10 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 11 | + |
| 12 | + Unless required by applicable law or agreed to in writing, |
| 13 | + software distributed under the License is distributed on an |
| 14 | + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 15 | + KIND, either express or implied. See the License for the |
| 16 | + specific language governing permissions and limitations |
| 17 | + under the License. |
| 18 | +--> |
| 19 | + |
| 20 | +# AuthZ framework with pluggable privileges |
| 21 | + |
| 22 | +Provides a framework and implementations pluggable privileges and privilege checks. |
| 23 | + |
| 24 | +## Privileges |
| 25 | + |
| 26 | +A privilege is globally identified by its name. Privileges can be inheritable (from its parents) or not. Multiple |
| 27 | +privileges can be grouped together to a _composite_ privilege (think: `ALL_DML` having `SELECT`, `INSERT`, `UPDATE` and |
| 28 | +`DELETE`) - a composite privilege matches, if all its individual privileges match. Multiple privileges can also be |
| 29 | +grouped to an _alternative_ privilege, which matches if any of its individual privileges matches. |
| 30 | + |
| 31 | +Available privileges are provided by one or more `PrivilegeProvider`s, which are discovered at runtime. |
| 32 | +Note: currently there is only one `ProvilegeProvider` that plugs in the Polaris privileges. |
| 33 | + |
| 34 | +## ACLs, ACL entries and ACL chains |
| 35 | + |
| 36 | +Each securable object can have its own ACL. ACLs consist of ACL entries, which define the _granted_ and _restricted_ |
| 37 | +privileges by role name. The the number of roles is technically unbounded and the number of ACL entries can become |
| 38 | +quite large. |
| 39 | + |
| 40 | +This framework implements [separation of duties](https://en.wikipedia.org/wiki/Separation_of_duties) ("SoD"), which is a |
| 41 | +quite demanded functionality not just by large(r) user organizations. TL;DR _SoD_ allows "security administrators" to |
| 42 | +grant and revoke privileges to other users, but not leverage those privileges themselves. |
| 43 | + |
| 44 | +The _effective_ set of privileges for a specific operation performed by a specific caller needs to be computed against |
| 45 | +the target objects and their parents. _ACL chains_ are the vehicle to model this hierarchy and let the implementation |
| 46 | +compute the set of _effective_ privileges based on the individual ACLs and roles. |
| 47 | + |
| 48 | +Note: Privilege checks and _SoD_ are currently not performed via this framework. |
| 49 | + |
| 50 | +## Jackson support & Storage friendly representation |
| 51 | + |
| 52 | +The persistable types `Acl`, `AclEntry`, and `PrivilegeSet` can all be serialized using Jackson. |
| 53 | + |
| 54 | +As the number of ACL entries can become quite large, space efficient serialization is quite important. The |
| 55 | +implementation uses bit-set encoding when serializing `PrivilegeSet`s for persistence. |
| 56 | + |
| 57 | +## Code structure |
| 58 | + |
| 59 | +The code is structured into multiple modules. Consuming code should almost always pull in only the API module. |
| 60 | + |
| 61 | +* `polaris-authz-api` provides the necessary Java interfaces and immutable types. |
| 62 | +* `polaris-authz-impl` provides the storage agnostic implementation. |
| 63 | +* `polaris-authz-spi` provides the necessary interfaces to provide custom privileges and storage implementation. |
| 64 | +* `polaris-authz-store-nosql` provides the storage implementation based on `polaris-persistence-nosql-api`. |
0 commit comments