Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: document opa bundle and object/s3 support #241

Merged
merged 5 commits into from
Jun 26, 2024
Merged

feat: document opa bundle and object/s3 support #241

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d5b9378
feat: document opa bundle and object/s3 support
markphelps Jun 25, 2024
28e1026
chore: add missing configuration sections in overview
markphelps Jun 25, 2024
8929bfa
chore: update spelling exceptions
markphelps Jun 25, 2024
0de3a09
Merge branch 'main' into opa-bundle-docs
markphelps Jun 26, 2024
12d8605
Merge branch 'main' into opa-bundle-docs
markphelps Jun 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .vale/styles/Flipt/spelling-exceptions.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
affordance
APIs
auditable
azblob
backoff
boolean
caddy
Expand All @@ -23,6 +24,7 @@ flipt
flipt's
Gitlab
gitops
googlecloud
grafana
grpc
hostname
Expand Down
8 changes: 3 additions & 5 deletions authorization/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,9 @@
Flipt supports the ability to secure its core API routes with authorization.

<Info>
Flipt authorization is **experimental** and **disabled** (not required) by default.
Flipt authorization is **disabled** (not required) by default.

To enable authorization, you must set the `experimental.authorization.enabled` configuration option to `true` in your Flipt [configuration file](/configuration/overview#configuration-file).

See the [experimental](/configuration/experimental) section for more information on how to enable experimental features.
Head to the [Configuration: Authorization](/configuration/authorization) section to learn how to enable it.

</Info>

Expand Down Expand Up @@ -61,7 +59,7 @@
policies before deploying them.
</Tip>

It's up to you to define the policies that make sense for your organization. During policy evaluation, Flipt will pass the incoming request context to OPA, which will then evaluate the policy against that context.
It's up to you to define the policies that make sense for your organization. During policy evaluation, Flipt will pass the incoming request context to the built in Open Policy Agent, which will then evaluate the policy against that context.

Check warning on line 62 in authorization/overview.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.SentenceLength] Write short sentences (less than 25 words).

Raw Output:
{"message": "[Openly.SentenceLength] Write short sentences (less than 25 words).", "location": {"path": "authorization/overview.mdx", "range": {"start": {"line": 62, "column": 78}}}, "severity": "WARNING"}

Check warning on line 62 in authorization/overview.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "authorization/overview.mdx", "range": {"start": {"line": 62, "column": 110}}}, "severity": "WARNING"}

Check warning on line 62 in authorization/overview.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.Terms] Prefer 'personal digital assistant' over 'Agent'.

Raw Output:
{"message": "[Microsoft.Terms] Prefer 'personal digital assistant' over 'Agent'.", "location": {"path": "authorization/overview.mdx", "range": {"start": {"line": 62, "column": 177}}}, "severity": "WARNING"}

Check warning on line 62 in authorization/overview.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "authorization/overview.mdx", "range": {"start": {"line": 62, "column": 190}}}, "severity": "WARNING"}

The context provided to OPA includes the following fields:

Expand Down
148 changes: 103 additions & 45 deletions configuration/authorization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,6 @@
---

<Warning>
Flipt authorization is **experimental** and **disabled** (not required) by default.

To enable authorization, you must set the `experimental.authorization.enabled` configuration option to `true` in your Flipt [configuration file](/configuration/overview#configuration-file).

Once authorization has been set to `required: true` all management API routes will require a valid authentication session as well.

The UI will require a session-compatible authentication method (e.g. [OIDC](/authentication/methods#openid-connect)) to be enabled.
Expand All @@ -19,30 +15,29 @@
```yaml config.yaml
authorization:
required: true

# required while authorization is still experimental
experimental:
authorization:
enabled: true
```

When authorization is set to `required`, the API will ensure valid credentials are present on all management API requests.

See the [Authorization: Overview](/authorization/overview) documentation for more details on Flipt's API authorization handling.

## Policies
## Backends

Flipt uses [Open Policy Agent (OPA)](https://www.openpolicyagent.org/) to enforce authorization policies. OPA is a general-purpose policy engine that can be used to enforce policies across the stack.

### Local
Flipt supports sourcing policies and external data from various backends. Currently, Flipt supports the following backends:

Currently, Flipt only supports local policy files. These policy files must be valid [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) files.
- [Local](#local)
- [Bundle](#bundle)
- [Object Store](#object)

<Note>
In the future we plan to support other policy source backends such as git,
object store, and others. If you have a specific use case, please get in
touch!
</Note>
## Local

Flipt supports loading policy and external data from the local filesystem.

### Policies

For configuring policies, the files must be valid [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) files.

You can specify the path to the policy file in the `policy` object in the `authorization` configuration object.

Expand All @@ -63,63 +58,126 @@

You can learn more about policies in our [Authorization: Overview](/authorization/overview#policies) documentation.

### Polling Interval
#### Polling Interval

Check warning on line 61 in configuration/authorization.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.Titles] 'Polling Interval' should be in sentence case

Raw Output:
{"message": "[Openly.Titles] 'Polling Interval' should be in sentence case", "location": {"path": "configuration/authorization.mdx", "range": {"start": {"line": 61, "column": 6}}}, "severity": "WARNING"}

Flipt will poll the policy file for changes at a regular interval. By default, Flipt will poll the policy file every 5 minutes. You can adjust this interval by setting the `poll_interval` field in the `policy` object.

```yaml
authorization:
required: true
policy:
backend: local
local:
backend: local
local:
policy:
path: "policy.rego"
poll_interval: "1m"
```

## External Data
### External Data

Check warning on line 75 in configuration/authorization.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.Titles] 'External Data' should be in sentence case

Raw Output:
{"message": "[Openly.Titles] 'External Data' should be in sentence case", "location": {"path": "configuration/authorization.mdx", "range": {"start": {"line": 75, "column": 5}}}, "severity": "WARNING"}

In addition to policies that can be used to enforce authorization rules, Flipt also provides a way to pass external data to the policy evaluation.
In addition to policies that can be used to enforce authorization rules, Flipt also provides a way to pass external data to the policy evaluation from the local filesystem. These data objects **must be valid JSON objects**.

Check warning on line 77 in configuration/authorization.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.SentenceLength] Write short sentences (less than 25 words).

Raw Output:
{"message": "[Openly.SentenceLength] Write short sentences (less than 25 words).", "location": {"path": "configuration/authorization.mdx", "range": {"start": {"line": 77, "column": 1}}}, "severity": "WARNING"}

Check warning on line 77 in configuration/authorization.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.So] Don't start a sentence with 'so '

Raw Output:
{"message": "[Openly.So] Don't start a sentence with 'so '", "location": {"path": "configuration/authorization.mdx", "range": {"start": {"line": 77, "column": 82}}}, "severity": "WARNING"}

This can be done by setting the `data` object in the `authorization` configuration object.

### Local

Currently, Flipt only supports local data objects. These data objects **must be valid JSON objects**.

<Note>
In the future we plan to support other data source backends such as git,
object store, and others. If you have a specific use case, please get in
touch!
</Note>

You can specify the path to the data file in the `data` object in the `authorization` configuration object.

```yaml
authorization:
required: true
policy:
backend: local
local:
backend: local
local:
policy:
path: "policy.rego"
data:
backend: local
local:
data:
path: "data.json"
```

You can learn more about using data with policies in our [Authorization: Overview](/authorization/overview#external-data) documentation.

### Polling Interval
#### Polling Interval

Check warning on line 94 in configuration/authorization.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.Titles] 'Polling Interval' should be in sentence case

Raw Output:
{"message": "[Openly.Titles] 'Polling Interval' should be in sentence case", "location": {"path": "configuration/authorization.mdx", "range": {"start": {"line": 94, "column": 6}}}, "severity": "WARNING"}

Like policies, Flipt will poll data files for changes at a regular interval. By default, Flipt will poll the data file every 30 seconds. You can adjust this interval by setting the `poll_interval` field in the `data` object.

```yaml
authorization:
required: true
data:
backend: local
local:
backend: local
local:
data:
path: "data.json"
poll_interval: "1m"
```

## Bundle

Flipt supports loading policy and external data from OPA bundles. Bundles are a way to package policy and data files together as a single unit.

You can read more about creating and using OPA bundles in the [OPA documentation](https://www.openpolicyagent.org/docs/latest/management-bundles/).

Bundles can be hosted on a remote server and downloaded by Flipt at regular intervals. Some of the services that OPA bundles support out of the box include:

- [HTTP](https://www.openpolicyagent.org/docs/latest/management-bundles/#bundle-service-api)
- [S3](https://www.openpolicyagent.org/docs/latest/management-bundles/#amazon-s3)
- [Azure Blob Storage](https://www.openpolicyagent.org/docs/latest/management-bundles/#azure-blob-storage)
- [Google Cloud Storage](https://www.openpolicyagent.org/docs/latest/management-bundles/#google-cloud-storage)
- [OCI Registry](https://www.openpolicyagent.org/docs/latest/management-bundles/#oci-registry)

Bundle support is enabled by setting the `backend` field to `bundle` in the `authorization` configuration object.

The `bundle` backend requires a valid `configuration` object to be set. This configuration definition is the same as the OPA bundle [service configuration](https://www.openpolicyagent.org/docs/latest/configuration/).

Check warning on line 124 in configuration/authorization.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.

Raw Output:
{"message": "[Microsoft.Avoid] Don't use 'backend'. See the A-Z word list for details.", "location": {"path": "configuration/authorization.mdx", "range": {"start": {"line": 124, "column": 14}}}, "severity": "WARNING"}

```yaml
authorization:
required: true
backend: bundle
bundle:
configuration: |
services:
- name: acmecorp
url: https://example.com/service/v1
credentials:
bearer:
token: "bGFza2RqZmxha3NkamZsa2Fqc2Rsa2ZqYWtsc2RqZmtramRmYWxkc2tm"

bundles:
authz:
service: acmecorp
resource: somedir/bundle.tar.gz
polling:
min_delay_seconds: 10
max_delay_seconds: 20
```

## Object

Similar to our [object storage](/configuration/storage#object) support for Flipt flag data, Flipt also supports loading policy and external data from object storage.

Technically, this is a subset of the bundle backend, but it is useful for those who want to provide a simplified configuration for loading policy and data from object storage, without the need to configure the bundle service directly.

The `object` backend requires a valid `type` to be configured. This is similar to the object storage configuration for Flipt flag data as it also requires valid credentials to access the object storage service.

The credentials are read from environment variables at Flipt start time.

```bash
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
```

```yaml
authorization:
required: true
backend: object
object:
type: s3
s3:
region: us-east-1
bucket: flipt_policy_bundles
# optional: bucket prefix for locating bundle files
prefix: production
# optional: for non-AWS hosted S3
endpoint: http://localhost:9009
```

<Note>
Currently Flipt only supports the `s3` object storage type directly. If you require support for other object storage types, please [let us know](https://github.com/flipt-io/flipt/issues/new).

Alternatively as a workaround, you can use the bundle backend to load policy and data from other object storage types. Follow the [OPA bundle documentation](https://www.openpolicyagent.org/docs/latest/management-bundles/) for more information.

</Note>
18 changes: 0 additions & 18 deletions configuration/experimental.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,24 +62,6 @@ experimental:
sign up for an account.
</Note>

### Authorization

Introduced in `v1.43.0`.

[Flipt Authorization](/authorization/overview) enables you to control access to your feature data with fine-grained permissions and infinite flexibility.

Our authorization system leverages Open Policy Agent (OPA), which gives you the power to define custom policies that control who can access your feature data and what actions they can perform.

To enable the Flipt Authorization experimental feature, set the `experimental.authorization.enabled` configuration option to `true`.

```yaml config.yaml
experimental:
authorization:
enabled: true
```

To learn more about Flipt Authorization, see the [Authorization](/authorization/overview) documentation.

## Deprecations

Once an experimental feature is promoted to a stable feature or is removed, it will move to a deprecated status. Depending on the feature, you may need to take action to migrate to the new stable feature or remove the deprecated feature from your configuration.
Expand Down
65 changes: 53 additions & 12 deletions configuration/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,15 +252,40 @@ export FLIPT_CORS_ALLOWED_ORIGINS="http://localhost:3000 http://localhost:3001"

### Authorization

| Property | Description | Default | Since |
| ---------------------------------- | ------------------------------------------------------ | ------- | ------- |
| authorization.required | Enable or disable authorization validation on requests | false | v1.43.0 |
| authorization.policy.backend | The backend to use for authorization policies (local) | local | v1.43.0 |
| authorization.policy.local.path | Path to the local policy file | | v1.43.0 |
| authorization.policy.poll_interval | Interval to poll the policy file for changes | 5m | v1.43.0 |
| authorization.data.backend | The backend to use for authorization data (local) | local | v1.43.0 |
| authorization.data.local.path | Path to the local data file | | v1.43.0 |
| authorization.data.poll_interval | Interval to poll the data file for changes | 30s | v1.43.0 |
| Property | Description | Default | Since |
| ---------------------- | --------------------------------------------------------------------- | ------- | ------- |
| authorization.required | Enable or disable authorization validation on requests | false | v1.43.0 |
| authorization.backend | The backend to use for authorization policies (local, bundle, object) | local | v1.45.0 |

#### Authorization Backend: Local

| Property | Description | Default | Since |
| ---------------------------------------- | -------------------------------------------- | ------- | ------- |
| authorization.local.policy.path | Path to the local policy file | | v1.45.0 |
| authorization.local.policy.poll_interval | Interval to poll the policy file for changes | 5m | v1.45.0 |
| authorization.local.data.path | Path to the local data file | | v1.45.0 |
| authorization.local.data.poll_interval | Interval to poll the data file for changes | 30s | v1.45.0 |

#### Authorization Backend: Bundle

| Property | Description | Default | Since |
| ---------------------------------- | ------------------------------------ | ------- | ------- |
| authorization.bundle.configuration | Configuration for the bundle service | | v1.45.0 |

#### Authorization Backend: Object

| Property | Description | Default | Since |
| ------------------------- | ----------------------------- | ------- | ------- |
| authorization.object.type | The type of object store (s3) | s3 | v1.45.0 |

##### Authorization Backend Object: S3

| Property | Description | Default | Since |
| -------------------------------- | ------------------------------------------- | ------- | ------- |
| authorization.object.s3.region | The AWS region to use for S3 object storage | | v1.45.0 |
| authorization.object.s3.bucket | The S3 bucket to use for object storage | | v1.45.0 |
| authorization.object.s3.prefix | The S3 prefix to use for object storage | | v1.45.0 |
| authorization.object.s3.endpoint | The S3 endpoint to use for object storage | | v1.45.0 |

### Database

Expand Down Expand Up @@ -312,9 +337,9 @@ export FLIPT_CORS_ALLOWED_ORIGINS="http://localhost:3000 http://localhost:3001"

#### Storage Object

| Property | Description | Default | Since |
| ------------------- | -------------------------------------- | ------- | ------- |
| storage.object.type | The type of object storage to use (s3) | s3 | v1.25.0 |
| Property | Description | Default | Since |
| ------------------- | ------------------------------------------------------------ | ------- | ------- |
| storage.object.type | The type of object storage to use (s3, azblob, googlecloud ) | s3 | v1.25.0 |

##### Storage Object: S3

Expand All @@ -326,6 +351,22 @@ export FLIPT_CORS_ALLOWED_ORIGINS="http://localhost:3000 http://localhost:3001"
| storage.object.s3.endpoint | The S3 endpoint to use for object storage | | v1.25.0 |
| storage.object.s3.poll_interval | The interval to poll S3 for changes | 30s | v1.25.0 |

##### Storage Object: Azure Blob

| Property | Description | Default | Since |
| ----------------------------------- | -------------------------------------------------------- | ------- | ------- |
| storage.object.azblob.endpoint | The Azure Blob Store endpoint to use for object storage | | v1.34.0 |
| storage.object.azblob.container | The Azure Blob Store container to use for object storage | | v1.34.0 |
| storage.object.azblob.poll_interval | The interval to poll Azure Blob Store for changes | 30s | v1.34.0 |

##### Storage Object: Google Cloud Storage

| Property | Description | Default | Since |
| ---------------------------------------- | --------------------------------------------------------- | ------- | ------- |
| storage.object.googlecloud.bucket | The Google Cloud Storage bucket to use for object storage | | v1.35.0 |
| storage.object.googlecloud.prefix | The Google Cloud Storage prefix to use for object storage | | v1.35.0 |
| storage.object.googlecloud.poll_interval | The interval to poll Google Cloud Storage for changes | 30s | v1.35.0 |

#### Storage OCI

| Property | Description | Default | Since |
Expand Down
6 changes: 3 additions & 3 deletions guides/operation/authorization/rbac-with-keycloak.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,10 +158,10 @@ authentication:

authorization:
required: true
policy:
backend: local
backend: local
local:
path: "policy.rego"
policy:
path: "policy.rego"
```

### Step 3: Run Flipt
Expand Down
Loading