From a58530639d4c239566bd4fcca5d66df4710a47a2 Mon Sep 17 00:00:00 2001
From: Mark Phelps <209477+markphelps@users.noreply.github.com>
Date: Wed, 26 Jun 2024 12:41:56 -0400
Subject: [PATCH] feat: document opa bundle and object/s3 support (#241)
* feat: document opa bundle and object/s3 support
Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com>
* chore: add missing configuration sections in overview
Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com>
* chore: update spelling exceptions
Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com>
---------
Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com>
---
.vale/styles/Flipt/spelling-exceptions.txt | 2 +
authorization/overview.mdx | 8 +-
configuration/authorization.mdx | 148 ++++++++++++------
configuration/experimental.mdx | 18 ---
configuration/overview.mdx | 65 ++++++--
.../authorization/rbac-with-keycloak.mdx | 6 +-
6 files changed, 164 insertions(+), 83 deletions(-)
diff --git a/.vale/styles/Flipt/spelling-exceptions.txt b/.vale/styles/Flipt/spelling-exceptions.txt
index 7cd4873..d85eb69 100644
--- a/.vale/styles/Flipt/spelling-exceptions.txt
+++ b/.vale/styles/Flipt/spelling-exceptions.txt
@@ -1,6 +1,7 @@
affordance
APIs
auditable
+azblob
backoff
boolean
caddy
@@ -23,6 +24,7 @@ flipt
flipt's
Gitlab
gitops
+googlecloud
grafana
grpc
hostname
diff --git a/authorization/overview.mdx b/authorization/overview.mdx
index f12e953..02a8399 100644
--- a/authorization/overview.mdx
+++ b/authorization/overview.mdx
@@ -6,11 +6,9 @@ description: This document describes how to enable and use authorization with Fl
Flipt supports the ability to secure its core API routes with authorization.
-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.
@@ -61,7 +59,7 @@ You can find more information on how to write Rego policies in the [OPA document
policies before deploying them.
-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.
The context provided to OPA includes the following fields:
diff --git a/configuration/authorization.mdx b/configuration/authorization.mdx
index c5b2cdd..a799552 100644
--- a/configuration/authorization.mdx
+++ b/configuration/authorization.mdx
@@ -4,10 +4,6 @@ description: This document describes how to configure Flipt's authorization mech
---
-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.
@@ -19,30 +15,29 @@ Flipt supports the ability to secure its core API routes by setting the `require
```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)
-
- 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!
-
+## 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.
@@ -63,63 +58,126 @@ package flipt.authz.v1
You can learn more about policies in our [Authorization: Overview](/authorization/overview#policies) documentation.
-### Polling Interval
+#### Polling Interval
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
-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**.
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**.
-
-
- 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!
-
-
-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
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/).
+
+```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
+```
+
+
+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.
+
+
diff --git a/configuration/experimental.mdx b/configuration/experimental.mdx
index a852e5f..03c35db 100644
--- a/configuration/experimental.mdx
+++ b/configuration/experimental.mdx
@@ -62,24 +62,6 @@ experimental:
sign up for an account.
-### 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.
diff --git a/configuration/overview.mdx b/configuration/overview.mdx
index db96e93..9f03767 100644
--- a/configuration/overview.mdx
+++ b/configuration/overview.mdx
@@ -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
@@ -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
@@ -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 |
diff --git a/guides/operation/authorization/rbac-with-keycloak.mdx b/guides/operation/authorization/rbac-with-keycloak.mdx
index 1f5d952..cfb8d8f 100644
--- a/guides/operation/authorization/rbac-with-keycloak.mdx
+++ b/guides/operation/authorization/rbac-with-keycloak.mdx
@@ -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