forked from TrueCloudLab/policy-engine
85 lines
5.6 KiB
Markdown
85 lines
5.6 KiB
Markdown
# Access policy engine
|
|
|
|
## General overview
|
|
|
|
### Purpose
|
|
|
|
Access policy engine (APE) is aimed at checking if a request can be performed over a resource by looking up the set chains of rules.
|
|
|
|
#### Terms
|
|
|
|
| Term | Description | Structure overview |
|
|
| -------------- | -------------------------------------------------------------- | -------------- |
|
|
| `Request` | The action that is being performed on the `Resource`. | <ul><li>`Operation` - `GetObject`,`PutObject` etc.;</li><li>`Properties` - actor's public key, actor's attributes;</li><li>`Resource`.</li></ul> |
|
|
| `Resource` | The object that the request is being performed on. Check also [resource.md](./resource.md). | <ul><li>`Name` - strictly formatted string value;</li><li>`Properties`.</li></ul> |
|
|
| `Chain` | A chain of `Rule`-s defined for a specific target. Chains are strictly distinguished by `Name`-s , i.e. chains with name `ingress` are not intersected with chains with name `s3`. Chains are stored in serialized format. | <ul><li>Base64-encoded `ID`;</li><li>List of `Rule`-s;</li><li>`MatchType` - defines rule status selection priority.</li></ul> |
|
|
| `Rule` | `Rule` defines which status is returned if `Request` matches all conditions. | <ul><li>`Status`: `Allow`, `AccessDenied`, `QuotaLimitReached`, `NoRuleFound`;</li><li>`Actions` - operation defined by a schema (`GetObject`, `PutContainer` etc.);</li><li>`Resources`;</li><li>`Any` - if `true` then `Reqeust` matches `Rule` if any `Condition` is `true`;</li><li>`Conditions`.</li></ul> |
|
|
| `Name` | `Name` of a chain (do not confuse with chain ID). `Name` defines a layer of `Chain`'s usage, so chains are distinguished by `Name`-s. Basically, `Name` refers to a protocol. | String value (`ingress`, `s3`, `iam`). |
|
|
| `Target` | A scope of request. `Target` can be either simple (only namespace; only container; only user; only groups) or compound (namespace + container). | <ul><li>`Namespace`;</li><li>`Container`;</li><li>`User`;</li><li>`Groups`.</li></ul> |
|
|
| `Engine` | `Engine` checks a request in a scope defined by `Target`. First, it is trying to match a request with rules defined in `LocalOverrideStorage` and, then, in `MorphRuleChainStorage`. | <ul><li>`LocalOverrideStorage` - chains stored in the local override storage have the highest priority</li><li>`MorphRuleChainStorage` - basically, chains stored in `Policy` contract;</li><li>`ChainRouter` - looks up chains and try to match them with `Request`.</li></ul> |
|
|
|
|
#### Details
|
|
|
|
Here some entities are overviewed in more detail.
|
|
|
|
##### Resource
|
|
|
|
`Resource`'s name is strictly formatted, the format is defined by a schema (`native`, `aws` etc.). Examples:
|
|
|
|
```bash
|
|
# The resource is the particular object with the address within Root namespace
|
|
native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/EbxzAdz5LB4uqxuz6crWKAumBNtZyK2rKsqQP7TdZvwr
|
|
# The resource is all objects within the container within Root namespace
|
|
native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/*
|
|
# The resource is the particular container within the namespace
|
|
native:container/namespace1/HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj
|
|
# The resource is all containers within the namespace
|
|
native:container/namespace1/*
|
|
```
|
|
|
|
##### Rule
|
|
|
|
`Rule` works out if:
|
|
|
|
1. a requests's operation matches the rule's `Actions`;
|
|
2. resource name matches the rule's `Resources`;
|
|
3. if all (or at least one if `Any=true`) conditions in `Condition` is met. Each condition defines how to retrieve
|
|
and compare the retrieved value. If `Condition`'s `Object` is set to `Resource` then the value is retrieved from the
|
|
resource's properties (example: container zone attribute). If `Object` is set to `Request`, the it's retrieved from the request's properties (example: actor's public key).
|
|
|
|
###### Name matching
|
|
|
|
`Resource`'s name in `Rule` may contain wildcard '*' that can be considered as a regular expression:
|
|
|
|
```bash
|
|
# The resource is all objects within the container within Root namespace
|
|
native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/*
|
|
```
|
|
|
|
If an incoming request has such a resource name, then names are matched:
|
|
|
|
```bash
|
|
# The resource is all objects within the container within Root namespace
|
|
native:object//HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/EbxzAdz5LB4uqxuz6crWKAumBNtZyK2rKsqQP7TdZvwr
|
|
```
|
|
|
|
If the incoming request has such a resource name that specifies a container's object within namespace, for instance, `namespicy`,
|
|
then matching does not work out:
|
|
|
|
```bash
|
|
# The resource is all objects within the container within `namespicy` namespace:
|
|
native:object/namespicy/HRwWbb1bJjRms33kkA21hy4JdPfARaH3fW9NfuNN6Fgj/EbxzAdz5LB4uqxuz6crWKAumBNtZyK2rKsqQP7TdZvwr
|
|
```
|
|
|
|
##### Engine
|
|
|
|
`Engine` is trying to match the request against **the target** looking up chain rules, firstly, in `LocalOverrideStorage` (these rules are also known as *local overrides*) and then in `MorphRuleChainStorage` (contract `Policy`). Both storages iterate chain rules according to the specified priority of the targets: `namespace` -> `container` -> `user` -> `groups`.
|
|
|
|
#### Diagrams
|
|
|
|
The diagram demonstrates a scenario in Storage node. The request `A` cannot be performed as APE matched
|
|
the request and returned `Access Denied` status. The request `B` is allowed and the client gets `OK` status.
|
|
|
|
|
|
The diagram demonstrates a complex scenario with S3, IAM and Storage node.
|
|
|