From d5b9378dfe2da6d19016a9728df3b47a2eb850db Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Tue, 25 Jun 2024 13:31:36 -0400 Subject: [PATCH 1/3] feat: document opa bundle and object/s3 support Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com> --- authorization/overview.mdx | 8 +- configuration/authorization.mdx | 148 ++++++++++++------ configuration/experimental.mdx | 18 --- .../authorization/rbac-with-keycloak.mdx | 6 +- 4 files changed, 109 insertions(+), 71 deletions(-) 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/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 From 28e10261ace0a677295f4a71a5502b4133721fc7 Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Tue, 25 Jun 2024 13:55:45 -0400 Subject: [PATCH 2/3] chore: add missing configuration sections in overview Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com> --- configuration/overview.mdx | 65 +++++++++++++++++++++++++++++++------- 1 file changed, 53 insertions(+), 12 deletions(-) diff --git a/configuration/overview.mdx b/configuration/overview.mdx index a1917f4..ee8380f 100644 --- a/configuration/overview.mdx +++ b/configuration/overview.mdx @@ -231,15 +231,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 @@ -291,9 +316,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 @@ -305,6 +330,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 | From 8929bfaea3b48353f223edca8a5ec8b86975900b Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Tue, 25 Jun 2024 14:06:23 -0400 Subject: [PATCH 3/3] chore: update spelling exceptions Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com> --- .vale/styles/Flipt/spelling-exceptions.txt | 2 ++ 1 file changed, 2 insertions(+) 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