/
README.md
110 lines (69 loc) · 3.73 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
# OPA-Elasticsearch Data Filtering Example
This directory contains an example of how to perform data filtering in
Elasticsearch using the queries provided by OPA's Compile API.
The example server is written in Go and when it receives API requests it asks
OPA for a set of conditions to apply to the Elasticsearch query that serves
the request. OPA is integrated as a library.
## Building
Build the example by running `make build`
## Running the example
1. Run Elasticsearch (with security turned off - the example assumes http and default credentials).
Dockerized example:
```bash
docker run --rm -d -p 9200:9200 -e "xpack.security.enabled=false" -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:8.1.1
```
See Elasticsearch's [Installation docs](https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html) for other methods of installation.
2. Build the policy bundle
```shell
opa build -b policy
```
This will produce a bundle.tar.gz file from the policy/example.rego file.
3. Run nginx server to serve the bundle.
The application will need a bundle server to fetch the policy bundle from. We will use nginx for this.
```shell
docker run --rm -d --name bundle-server -p 8888:80 -v ${PWD}/bundle.tar.gz:/usr/share/nginx/html/bundle.tar.gz:ro nginx:latest
```
4. Start the example server.
This will use the opa-conf.yaml file to configure OPA to download bundles from nginx.
```bash
./opa-es-filtering
```
The server listens on `:8080` and exposes two endpoints `/posts` and `/posts/{post_id}`. OPA is loaded with an example policy from the file `example.rego` which has rules related to both these
endpoints.
5. Open a new window and make a request:
```bash
curl -H "Authorization: bob" localhost:8080/posts | jq .
```
This will return all the posts that `bob` is allowed to see depending on the policy loaded into OPA. All policies are defined in the `example.rego` file.
## Supported OPA Built-in Functions
### Comparison
- [x] ==
- [x] !=
- [x] <
- [x] <=
- [x] >
- [x] >=
### Strings
- [x] contains
### Regex
- [x] re_match
## Support for OPA references
References are used to access nested documents in OPA. OPA policies can be written over deeply nested structures which the server would then translate to Elasticsearch `Nested` queries.
## Generated Elasticsearch queries
For the OPA operators mentioned above, following are Elasticsearch queries generated by the server:
### Term level Queries
- Term Query
- Range Query
- Regexp Query
### Joining Queries
- Nested Query
### Compound Queries
- Bool Query
### Full Text Queries
- Match Query
- Query String Query
## Limitations
- The server is loaded with an Elasticsearch `Index` template which defines the settings and the mapping for the `posts` index which is also created when the server starts.
- The OPA policies should be written according to the fields in the Elasticsearch documents to get the desired results. The manner in which Elasticsearch handles unmapped fields depends on the type of query. For example, a Term query returns no matches if the query refers to a `term` that doesn't point to an object field in the mapping. On the other hand, a Nested query will fail if the defined `path` doesn't point to an object field in the mapping. **To obtain uniform behaviour across queries such that an unmapped `path` in a Nested query does not throw an exception and instead not match any documents for this query, the server generates Nested queries that ignore an unmapped path.**
- The server supports limited OPA operators and returns an error if the OPA policy contains an unsupported operator.
- The server supports only two endpoints `/posts` and `/posts/{post_id}` for fetching posts created when the server starts.