From 5ff19df8b22591ae84f11997cd76200a5aa16439 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20St=C3=A4bler?= Date: Wed, 28 Aug 2024 12:13:20 +0200 Subject: [PATCH] Add documentation for event authorization --- config/nav.yml | 1 + config/redirects.yml | 1 + docs/eventing/features/README.md | 1 + docs/eventing/features/authorization.md | 190 ++++++++++++++++++++++++ 4 files changed, 193 insertions(+) create mode 100644 docs/eventing/features/authorization.md diff --git a/config/nav.yml b/config/nav.yml index bf41f544666..ed4d659d718 100644 --- a/config/nav.yml +++ b/config/nav.yml @@ -303,6 +303,7 @@ nav: - EventType auto creation: eventing/features/eventtype-auto-creation.md - Transport Encryption: eventing/features/transport-encryption.md - Sender Identity: eventing/features/sender-identity.md + - Authorization: eventing/features/authorization.md - Eventing with Istio: eventing/features/istio-integration.md - Cross Namespace Event Links: eventing/features/cross-namespace-event-links.md - FAQ: eventing/faq/README.md diff --git a/config/redirects.yml b/config/redirects.yml index 3f1be0a181b..e72d240bbd2 100644 --- a/config/redirects.yml +++ b/config/redirects.yml @@ -11,6 +11,7 @@ plugins: eventing/experimental-features/eventtype-auto-creation.md: eventing/features/eventtype-auto-creation.md eventing/experimental-features/transport-encryption.md: eventing/features/transport-encryption.md eventing/experimental-features/sender-identity.md: eventing/features/sender-identity.md + eventing/experimental-features/authorization.md: eventing/features/authorization.md eventing/features/new-trigger-filters.md: eventing/triggers/README.md eventing/broker/kafka-broker/kafka-configmap.md: eventing/configuration/kafka-channel-configuration.md eventing/broker/create-mtbroker.md: eventing/brokers/create-broker.md diff --git a/docs/eventing/features/README.md b/docs/eventing/features/README.md index 90e87bdb368..bf42fdfb849 100644 --- a/docs/eventing/features/README.md +++ b/docs/eventing/features/README.md @@ -74,6 +74,7 @@ Knative Eventing: | [Knative reference mapping](kreference-mapping.md) | `kreference-mapping` | Provide mappings from a [Knative reference](https://github.com/knative/specs/blob/main/specs/eventing/overview.md#destination) to a templated URI. | Alpha, disabled by default | | [Transport encryption](transport-encryption.md) | `transport-encryption` | Enables components to encrypt traffic using TLS by exposing HTTPS URL. | Beta, disabled by default | | [Sender Identity](sender-identity.md) | `authentication-oidc` | Enables Eventing sources to send authenticated requests and addressables to require authenticated requests. | Alpha, disabled by default | +| [Authorization](authorization.md) | `default-authorization-mode` | Enables Authorization for Eventing sinks. | Alpha, disabled by default | | [Eventing with Istio](istio-integration.md) | `istio` | Enables Eventing components to communicate with workloads in an Istio mesh. | Beta, disabled by default | | [Cross Namespace Event Links](cross-namespace-event-links.md) | `cross-namespace-event-links` | Enables subscriptions and triggers to refer to brokers and channels in different namespaces. | Alpha, disabled by default | diff --git a/docs/eventing/features/authorization.md b/docs/eventing/features/authorization.md new file mode 100644 index 00000000000..8bc179857c6 --- /dev/null +++ b/docs/eventing/features/authorization.md @@ -0,0 +1,190 @@ +# Knative Eventing Authorization + +**Tracking issue**: [#7256](https://github.com/knative/eventing/issues/7256) + +## Overview + +Securing event delivery in Knative Eventing is essential to prevent unauthorized access. To enforce fine-grained control over event delivery, Knative Eventing introduces the `EventPolicy` custom resource, which allows users to specify which entities are authorized to send events to specific consumers within a namespace. + +## Prerequisites + +- [Eventing installation](./../../../install) +- [`authentication-oidc`](./sender-identity.md) feature to be enabled. + +## Compatibility + +Authorization is currently supported for the following components: + +- Brokers: + - [MTChannelBasedBroker](./../brokers/broker-types/channel-based-broker/) + - [Knative Broker for Apache Kafka](./../brokers/broker-types/kafka-broker/) +- Channels: + - [InMemoryChannel](./../channels/channels-crds.md) + - [KafkaChannel](./../channels/channels-crds.md) +- Flows: + - [Sequence](./../flows/sequence/README.md) + - [Parallel](./../flows/parallel.md) +- Others: + - [KafkaSink](./../sinks/kafka-sink.md) + +## Defining an EventPolicy + +An `EventPolicy` defines rules for event delivery by specifying which subjects (service accounts or event sources) are allowed to send events to designated event consumers. + +```yaml +apiVersion: eventing.knative.dev/v1alpha1 +kind: EventPolicy +metadata: + name: my-event-policy + namespace: default +spec: + to: + - ref: + apiVersion: eventing.knative.dev/v1 + kind: Broker + name: my-broker + - selector: + apiVersion: eventing.knative.dev/v1 + kind: Trigger + matchLabels: + app: special-app + from: + - ref: + apiVersion: sources.knative.dev/v1 + kind: PingSource + name: my-source + namespace: another-namespace + - sub: system:serviceaccount:default:trusted-app + - sub: "system:serviceaccount:default:other-*" + filters: + - cesql: "type IN ('order.created', 'order.updated', 'order.canceled')" + - exact: + type: com.github.push +``` + +### Specify for who the `EventPolicy` applies + +The `.spec.to` section specifies **where** the events are allowed to be sent. This field is optional; if left empty, the policy applies to all resources within the namespace. + +There are two ways to define these targets: + +1. `to.ref`: + * **Definition**: Directly references a specific resource. + * **Example**: In the `EventPolicy` above, the `my-broker` Broker is directly referenced. This means the `EventPolicy` applies to this specific `Broker`. + * **Use Case**: Use `to.ref` when you want to protect a specific resource by name. + ```yaml + to: + - ref: + apiVersion: eventing.knative.dev/v1 + kind: Broker + name: my-broker + ``` +2. `to.selector`: + * **Definition**: Uses a label selector to match multiple resources of a specific type. + * **Example**: The `EventPolicy` includes a `Trigger` with labels matching `app: special-app`. This means the `EventPolicy` applies to all `Triggers` with these labels. + * **Use Case**: Use `to.selector` when you want the `EventPolicy` to apply to a group of resources that share common labels. + + ```yaml + to: + - selector: + apiVersion: eventing.knative.dev/v1 + kind: Trigger + matchLabels: + app: special-app + ``` + +### Specify who is allowed to send events + +The `.spec.from` section specifies **who** is allowed to send events to the targets defined in `.spec.to`. There are two ways to define these sources: + +1. `from.ref`: + * **Definition**: Directly references a specific event source resource. + * **Example**: The `my-source` `PingSource` in another namespace is referenced, meaning this specific source is allowed to send events. + * **Use Case**: Use `from.ref` when you want to authorize a specific event source. + ```yaml + from: + - ref: + apiVersion: sources.knative.dev/v1 + kind: PingSource + name: my-source + namespace: another-namespace + ``` + +2. `from.sub`: + + * **Definition**: Specifies a subject, such as a service account, that is allowed to send events. It can include wildcard patterns as a postfix (`*`) for broader matching. + * **Example**: The `EventPolicy` allows events from the `trusted-app` service account in the default namespace and any service account in `default` namespace that starts with `other-`. + * **Use Case**: Use `from.sub` to allow specific users or service accounts, or to apply wildcard patterns for more flexibility. + ```yaml + from: + - sub: system:serviceaccount:default:trusted-app + - sub: "system:serviceaccount:default:other-*" + ``` + +### Advanced CloudEvent filtering criterias + +The `.spec.filters` section is optional and specifies additional criteria that the event itself must meet to be allowed. If the filters are specified, an event must match at least one of them to be accepted. `.spec.filters` accepts the same filter dialects as [Triggers](../triggers/README.md#supported-filter-dialects). + +### Summary of `.spec` fields: + +* `to.ref` targets a specific resource. +* `to.selector` targets a set of resources based on labels. +* `from.ref` authorizes a specific event source resource. +* `from.sub` authorizes specific users, service accounts, or patterns of accounts. +* `.spec.filters` allows to define advanced CloudEvent filtering criterias + +## EventPolicy status + +The status of an `EventPolicy` provides information about resolved sources and readiness: + +```yaml +status: + from: + - system:serviceaccount:default:my-source-oidc-sources.knative.dev-pingsource + - system:serviceaccount:default:trusted-app + - "system:serviceaccount:default:other-*" + conditions: + - type: Ready + status: "True" + - type: SubjectsResolved + status: "True" +``` + +## Applying EventPolicies to Resources + +Event consumers, such as a `Broker`, will list the applying EventPolicies in their status: + +```yaml +apiVersion: eventing.knative.dev/v1 +kind: Broker +metadata: + name: my-broker +spec: + ... +status: + ... + policies: + - name: my-event-policy + apiVersion: v1alpha1 + conditions: + - type: Ready + status: "True" + - type: EventPoliciesReady + status: "True" +``` + +The `EventPoliciesReady` condition indicates whether all applicable EventPolicies for a resource are ready and have been successfully applied. + +## Default Authorization Mode and Rejection Behavior + +When no `EventPolicy` applies to a resource, Knative Eventing falls back to the default authorization mode, configurable via the `defaultAuthorizationMode` feature flag. The available modes are: + +* `allow-all`: All requests are allowed. +* `deny-all`: All requests are denied, enforcing the creation of EventPolicies. +* `allow-same-namespace`: Only requests from subjects within the same namespace are allowed. (Default) + +If a request does not pass any applicable `EventPolicy`, it will be rejected with a `403 Forbidden` HTTP status code, ensuring that unauthorized event deliveries are blocked. + +## Summary + +The `EventPolicy` resource in Knative Eventing offers a powerful way to control event delivery securely. By defining which sources can send events to specific consumers, users can ensure that only authorized entities interact within their event-driven architecture.