Skip to content

Commit 254d04e

Browse files
desimonedesimone
authored
Revert "Undo 18"
1 parent 7ac4d9b commit 254d04e

39 files changed

+927
-198
lines changed

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Pomerium's documentation is built using [Docusaurus 2](https://docusaurus.io/).
88

99
See [Contributing](https://pomerium.com/docs/community/contributing) for more information on contributing to this project.
1010

11-
The steps below detail installation of this site locally for development.
11+
The steps below detail the installation of this site locally for development.
1212

1313
### Installation
1414

‎content/docs/enterprise/external-data.mdx

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: External Data Sources
3+
sidebar_label: External Data
4+
description: Extend your authorization policies with data from external sources.
5+
---
6+
7+
Pomerium Enterprise Console's external data feature allows you to collect data from sources other than your identity provider (**IdP**) to make context-aware policy decisions. Pomerium provides several data sources as examples, but we encourage you to create (and share with the community) your own integrations to expand your data-driven policies.
8+
9+
See the pages in this section for more information on our example data sources, or learn how to create your own by reviewing our [datasource](https://github.com/pomerium/datasource) repository.

‎content/docs/enterprise/external-data/bamboohr.mdx

+132
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
title: BambooHR
3+
description: Configure the BambooHR external data provider to extend your access policies.
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
The BambooHR integration provides integration with HR data such as group memberships, employment status, out of the office, location, etc.
10+
11+
:::caution
12+
The external data sources we provide are meant to be examples and inspiration for users to create their own data sources. We won't maintain these integrations in perpituity, and changes to the APIs they interact with may break them in the future.
13+
14+
The [datasource](https://github.com/pomerium/datasource) project is open-source, and if the community wishes to provide contributions to keep it working in the future, we will shepherd those updates.
15+
:::
16+
17+
## Install
18+
19+
1. Create new BambooHR API key by navigating to **Your profile** → **API Keys**, and adding a new API Key.
20+
21+
1. In order to correctly parse dates returned by BambooHR API you will need to provide a time zone - either an `UTC` or [IANA Time Zone] database name, i.e. `America/New_York`.
22+
23+
<Tabs>
24+
<TabItem value="compose" label="Docker Compose">
25+
26+
These instructions assume a local testing environment using [Docker Compose]. Adjust as needed for your deployment environment.
27+
28+
1. Add the datasource docker image to Docker Compose:
29+
30+
```yaml showLineNumbers
31+
version: "3"
32+
services:
33+
bamboohr:
34+
image: docker.cloudsmith.io/pomerium/datasource/datasource:main
35+
command:
36+
- bamboohr
37+
- --bamboohr-api-key=$YOUR_API_KEY
38+
- --bamboohr-subdomain=$YOUR_BAMBOOHR_SUBDOMAIN
39+
- --bamboohr-time-zone=America/New_York
40+
- --address=:8080
41+
container_name: bamboohr
42+
restart: always
43+
expose:
44+
- 8080
45+
```
46+
47+
1. Bring up the new container.
48+
49+
</TabItem>
50+
<TabItem value="binary" label="Binary">
51+
52+
These instructions assume a local testing environment. Adjust as needed for your deployment environment.
53+
54+
1. Download the latest [release] of the [Pomerium datasource] project and extract it.
55+
56+
1. Change directory and run the binary:
57+
58+
```sh
59+
cd pomerium-datasource-*
60+
./pomerium-datasource bamboohr --bamboohr-api-key=$YOUR_API_KEY --bamboohr-subdomian=$YOUR_BAMBOOHR_SUBDOMAIN --bamboohr-time-zone=America/New_York
61+
```
62+
63+
The output should resemble:
64+
65+
```sh
66+
{"level":"info","message":"ready"}
67+
```
68+
69+
</TabItem>
70+
</Tabs>
71+
72+
## Configure Configure External Data Source
73+
74+
BambooHR data connector exposes two API endpoints:
75+
76+
- `/employees/all` returns all employees
77+
- `/employees/available` returns employees that are not currently out of the office due to vacation or other leave reasons.
78+
79+
To create new external data record:
80+
81+
1. In the Pomerium Enterprise Console, navigate to **CONFIGURE** → **External Data** and click **+ ADD EXTERNAL DATA SOURCE**.
82+
83+
1. Fill out the following fields:
84+
85+
| Field | Content | Notes |
86+
| :---------- | :----------------------------------------- | :-------------------------------------------------------------------------------- |
87+
| URL | `http://bamboohr:8080/employees/available` | Adjust for the endpoint you'll write policies against. |
88+
| Record type | `pomerium.io/BambooHRAvailable` | As above, adjust to somethinglike pomerium.io/BambooHRAll for the other endpoint. |
89+
| Foreign Key | `user.email` | Pomerium uses the users's email to associate IdP and Bamboo user entries. |
90+
91+
1. Click **SAVE EXTERNAL DATA SOURCE**.
92+
93+
1. Define a new policy. The example policy below only allows access to the persons in the *Marketing* department and only when they are not on vacation.
94+
95+
<Tabs>
96+
<TabItem value="builder" label="Builder">
97+
98+
![Example BambooHR Policy in the Builder view](./img/bamboohr-policy.png)
99+
100+
</TabItem>
101+
<TabItem value="editor" label="Editor">
102+
103+
```yaml showLineNumbers
104+
allow:
105+
and:
106+
- record:
107+
field: department
108+
is: Marketing
109+
type: pomerium.io/BambooHRAvailable
110+
```
111+
112+
</TabItem>
113+
</Tabs>
114+
115+
## Reference
116+
117+
The BambooHR data source provides the following record details; see [BambooHR Field Reference] for details.
118+
119+
- `department`
120+
- `division`
121+
- `status`
122+
- `first_name`
123+
- `last_name`
124+
- `country`
125+
- `state`
126+
127+
[datasource]: https://github.com/pomerium/pomerium
128+
[Docker Compose]: https://docs.docker.com/compose/
129+
[IANA Time Zone]: https://www.iana.org/time-zones
130+
[BambooHR Field Reference]: https://documentation.bamboohr.com/docs/list-of-field-names
131+
[release]: https://github.com/pomerium/datasource/releases
132+
[Pomerium datasource]: https://github.com/pomerium/datasource

‎content/docs/enterprise/external-data/geoip.mdx

+134
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: GeoIP
3+
description: Configure the GeoIP external data provider to extend your access policies.
4+
---
5+
6+
import Tabs from "@theme/Tabs";
7+
import TabItem from "@theme/TabItem";
8+
9+
The GeoIP integration provides provides a list of IP address ranges and their country of origin. This data provider could allow an administrator to restrict, or allow access based on a users' known GeoIP fingerprint.
10+
11+
```json title="Example"
12+
[
13+
{
14+
"$index": { "cidr": "1.0.0.0/24" },
15+
"id": "1.0.0.0/24",
16+
"country": "US",
17+
"state": "",
18+
"city": "",
19+
"zip": "",
20+
"timezone": ""
21+
},
22+
{
23+
"$index": { "cidr": "1.0.1.0/24" },
24+
"id": "1.0.1.0/24",
25+
"country": "CN",
26+
"state": "",
27+
"city": "",
28+
"zip": "",
29+
"timezone": ""
30+
}
31+
]
32+
```
33+
34+
:::caution
35+
The external data sources we provide are meant to be examples and inspiration for users to create their own data sources. We won't maintain these integrations in perpituity, and changes to the APIs they interact with may break them in the future.
36+
37+
The [datasource](https://github.com/pomerium/datasource) project is open-source, and if the community wishes to provide contributions to keep it working in the future, we will shepherd those updates.
38+
:::
39+
40+
## Install
41+
42+
<Tabs>
43+
<TabItem value="compose" label="Docker Compose">
44+
45+
These instructions assume a local testing environment using [Docker Compose]. Adjust as needed for your deployment environment.
46+
47+
1. Download the IP2Location CSV GeoIP database from [ip2location.com].
48+
2. Add the datasource docker image to Docker Compose:
49+
50+
```yaml title="docker-compose.yaml"
51+
services:
52+
ip2location:
53+
image: docker.cloudsmith.io/pomerium/datasource/datasource:main
54+
container_name: ip2location
55+
command:
56+
- ip2location
57+
- /var/ip2location.csv.zip
58+
ports:
59+
- 8080:8080
60+
volumes:
61+
- ${PWD}/IP2LOCATION-LITE-DB1.CSV.ZIP:/var/ip2location.csv.zip
62+
```
63+
64+
3. Bring up the new container.
65+
66+
</TabItem>
67+
<TabItem value="binary" label="Local Binary">
68+
69+
1. Download the latest [release] of the [Pomerium datasource] project and extract it.
70+
2. Change directory and run the binary:
71+
72+
```sh
73+
cd pomerium-datasource-*
74+
./pomerium-datasource ip2location ../IP2LOCATION-LITE-DB1.CSV.ZIP
75+
```
76+
77+
The output should resemble:
78+
79+
```sh
80+
<nil> INF starting ip2location http server address=:8080 file=../IP2LOCATION-LITE-DB1.CSV.ZIP
81+
```
82+
83+
</TabItem>
84+
</Tabs>
85+
86+
## Configure External Data Source
87+
88+
Create an external data source:
89+
90+
1. In the Pomerium Enterprise Console, navigate to **CONFIGURE** → **External Data** and click **+ ADD EXTERNAL DATA SOURCE**.
91+
2. Fill out the following fields:
92+
| Field | Content | Notes |
93+
| :---------- | :-------------------- | :--------------------------------------------------------------------------------------------------- |
94+
| URL | http://localhost:8080 | If you configured the service in Docker Compose with a set container name, you can use that instead. |
95+
| Record type | pomerium.io/GeoIP | |
96+
| Foreign Key | request.ip | |
97+
98+
3. Click **SAVE EXTERNAL DATA SOURCE**.
99+
100+
## Configure Pomerium Enterprise Console
101+
102+
An example policy to restrict access to IP addresses within the United States would look something like this:
103+
104+
<Tabs>
105+
<TabItem value="builder" label="Builder">
106+
107+
![GeoIP Policy in the Builder view](./img/geoip-policy.png)
108+
109+
</TabItem>
110+
<TabItem value="editor" label="Editor">
111+
112+
```yaml showLineNumbers
113+
allow:
114+
and:
115+
- record:
116+
field: country
117+
is: US
118+
type: pomerium.io/GeoIP
119+
```
120+
121+
</TabItem>
122+
</Tabs>
123+
124+
This policy looks at the `country`, and allows access only from IP addresses purportedly in the US.
125+
126+
## Reference
127+
128+
- The ip2location datasource expects one argument when running the binary, the path to the GeoIP database.
129+
- It has an optional flag `--address`, to change the listening port from the default `:8080`.
130+
131+
[docker compose]: https://docs.docker.com/compose/
132+
[ip2location.com]: https://www.ip2location.com/
133+
[pomerium datasource]: https://github.com/pomerium/datasource
134+
[release]: https://github.com/pomerium/datasource/releases

‎content/docs/enterprise/external-data/img/bamboohr-policy.png

31.4 KB
Loading

‎content/docs/enterprise/external-data/img/geoip-policy.png

29.5 KB
Loading

‎content/docs/enterprise/external-data/img/tor-exit-node-policy.png

29.1 KB
Loading

‎content/docs/enterprise/external-data/img/vpn-node-policy.png

28.9 KB
Loading

‎content/docs/enterprise/external-data/img/well-known-ip-range-policy.png

30.9 KB
Loading

‎content/docs/enterprise/external-data/img/zenefits-policy.png

30.1 KB
Loading

0 commit comments

Comments
 (0)