From c2fc0a18da2886da9d4a04f7d75291b822b10001 Mon Sep 17 00:00:00 2001 From: Josh van Leeuwen Date: Mon, 18 Sep 2023 19:21:34 +0100 Subject: [PATCH] Reference: pubsub pulsar OIDC authentication (#3655) * Adds `OIDC` authentication to pulsar pubsub options Signed-off-by: joshvanl * Updates the pulsar OIDC authentication docs to use `oauth2` fields. Signed-off-by: joshvanl * Put pulsar authentication options into different sections Signed-off-by: joshvanl * Update daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md Co-authored-by: Mark Fussell Signed-off-by: Josh van Leeuwen * Update daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md Co-authored-by: Mark Fussell Signed-off-by: Josh van Leeuwen * Update daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md Co-authored-by: Mark Fussell Signed-off-by: Josh van Leeuwen --------- Signed-off-by: joshvanl Signed-off-by: Josh van Leeuwen Co-authored-by: Mark Fussell Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> --- .../supported-pubsub/setup-pulsar.md | 72 ++++++++++++++++++- 1 file changed, 71 insertions(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md index 45726e25363..a41aaee1f6f 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md @@ -73,7 +73,6 @@ The above example uses secrets as plain strings. It is recommended to use a [sec |--------------------|:--------:|---------|---------| | host | Y | Address of the Pulsar broker. Default is `"localhost:6650"` | `"localhost:6650"` OR `"http://pulsar-pj54qwwdpz4b-pulsar.ap-sg.public.pulsar.com:8080"`| | enableTLS | N | Enable TLS. Default: `"false"` | `"true"`, `"false"` | -| token | N | Enable Authentication. | [How to create pulsar token](https://pulsar.apache.org/docs/en/security-jwt/#generate-tokens)| | tenant | N | The topic tenant within the instance. Tenants are essential to multi-tenancy in Pulsar, and spread across clusters. Default: `"public"` | `"public"` | | consumerID | N | Used to set the subscription name or consumer ID. | `"channel1"` | namespace | N | The administrative unit of the topic, which acts as a grouping mechanism for related topics. Default: `"default"` | `"default"` @@ -91,6 +90,77 @@ The above example uses secrets as plain strings. It is recommended to use a [sec | subscribeType | N | Pulsar supports four kinds of [subscription types](https://pulsar.apache.org/docs/3.0.x/concepts-messaging/#subscription-types). Default: `"shared"` | `"shared"`, `"exclusive"`, `"failover"`, `"key_shared"`| | partitionKey | N | Sets the key of the message for routing policy. Default: `""` | | +### Authenticate using Token + +To authenticate to pulsar using a static [JWT token](https://pulsar.apache.org/docs/en/security-jwt), you can use the following metadata field: + +| Field | Required | Details | Example | +|--------|:--------:|---------|---------| +| token | N | Token used for authentication. | [How to create Pulsar token](https://pulsar.apache.org/docs/en/security-jwt/#generate-tokens)| + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: messagebus +spec: + type: pubsub.pulsar + version: v1 + metadata: + - name: host + value: "pulsar.example.com:6650" + - name: token + secretKeyRef: + name: pulsar + key: token +``` + +### Authenticate using OIDC + +Since `v3.0`, [Pulsar supports OIDC authentication](https://pulsar.apache.org/docs/3.0.x/security-openid-connect/). +To enable OIDC authentication, you need to provide the following OAuth2 parameters to the component spec. +OAuth2 authentication cannot be used in combination with token authentication. +It is recommended that you use a secret reference for the client secret. +The pulsar OAuth2 authenticator is not specifically complaint with OIDC so it is your responsibility to ensure fields are compliant. For example, the issuer URL must use the `https` protocol, the requested scopes include `openid`, etc. +If the `oauth2TokenCAPEM` field is omitted then the system's certificate pool is used for connecting to the OAuth2 issuer if using `https`. + +| Field | Required | Details | Example | +|--------|:--------:|---------|---------| +| oauth2TokenURL | N | URL to request the OIDC client_credentials token from. Must not be empty. | "https://oauth.example.com/o/oauth2/token"` | +| oauth2TokenCAPEM | N | CA PEM certificate bundle to connect to the OAuth2 issuer. If not defined, the system's certificate pool will be used. | `"---BEGIN CERTIFICATE---\n...\n---END CERTIFICATE---"` | +| oauth2ClientID | N | OIDC client ID. Must not be empty. | `"my-client-id"` | +| oauth2ClientSecret | N | OIDC client secret. Must not be empty. | `"my-client-secret"` | +| oauth2Audiences | N | Comma separated list of audiences to request for. Must not be empty. | `"my-audience-1,my-audience-2"` | +| oauth2Scopes | N | Comma separated list of scopes to request. Must not be empty. | `"openid,profile,email"` | + + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: messagebus +spec: + type: pubsub.pulsar + version: v1 + metadata: + - name: host + value: "pulsar.example.com:6650" + - name: oauth2TokenURL + value: https://oauth.example.com/o/oauth2/token + - name: oauth2TokenCAPEM + value: "---BEGIN CERTIFICATE---\n...\n---END CERTIFICATE---" + - name: oauth2ClientID + value: my-client-id + - name: oauth2ClientSecret + secretKeyRef: + name: pulsar-oauth2 + key: my-client-secret + - name: oauth2Audiences + value: "my.pulsar.example.com,another.pulsar.example.com" + - name: oauth2Scopes + value: "openid,profile,email" +``` + ### Enabling message delivery retries The Pulsar pub/sub component has no built-in support for retry strategies. This means that sidecar sends a message to the service only once and is not retried in case of failures. To make Dapr use more spohisticated retry policies, you can apply a [retry resiliency policy]({{< ref "policies.md#retries" >}}) to the Pulsar pub/sub component. Note that it will be the same Dapr sidecar retrying the redelivery the message to the same app instance and not other instances.