Merge branch 'v1.11' into issue_3503

daprdocs/content/en/concepts/security-concept.md

@@ -211,6 +211,21 @@ The Dapr threat model is below.
 
 ## Security audit
 
+### June 2023
+
+In June 2023, Dapr completed a fuzzing audit done by Ada Logics.
+
+The audit achieved the following:
+
+- OSS-Fuzz integration
+- 39 new fuzzers for Dapr
+- Fuzz test coverage for Dapr Runtime, Kit and Components-contrib
+- All fuzzers running continuously after the audit has completed
+
+You can find the full report [here](/docs/Dapr-june-2023-fuzzing-audit-report.pdf).
+
+3 issues were found during the audit.
+
 ### February 2021
 
 In February 2021, Dapr went through a 2nd security audit targeting its 1.0 release by Cure53.

daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-cloudevents.md

@@ -14,9 +14,15 @@ Dapr uses CloudEvents to provide additional context to the event payload, enabli
 - Content-type for proper deserialization of event data
 - Verification of sender application
 
-## CloudEvents example
+You can choose any of three methods for publish a CloudEvent via pub/sub:
 
-A publish operation to Dapr results in a cloud event envelope containing the following fields:
+1. Send a pub/sub event, which is then wrapped by Dapr in a CloudEvent envelope.
+1. Replace specific CloudEvents attributes provided by Dapr by overriding the standard CloudEvent properties.
+1. Write your own CloudEvent envelope as part of the pub/sub event.
+
+## Dapr-generated CloudEvents example
+
+Sending a publish operation to Dapr automatically wraps it in a CloudEvent envelope containing the following fields:
 
 - `id`
 - `source`
@@ -30,7 +36,9 @@ A publish operation to Dapr results in a cloud event envelope containing the fol
 - `time`
 - `datacontenttype` (optional)
 
-The following example demonstrates a cloud event generated by Dapr for a publish operation to the `orders` topic that includes a W3C `traceid` unique to the message, the `data` and the fields for the CloudEvent where the data content is serialized as JSON.
+The following example demonstrates a CloudEvent generated by Dapr for a publish operation to the `orders` topic that includes:
+- A W3C `traceid` unique to the message
+- The `data` and the fields for the CloudEvent where the data content is serialized as JSON
 
 ```json
 {
@@ -55,20 +63,112 @@ As another example of a v1.0 CloudEvent, the following shows data as XML content
 
 ```json
 {
-    "specversion" : "1.0",
+  "topic": "orders",
-    "type" : "xml.message",
+  "pubsubname": "order_pub_sub",
-    "source" : "https://example.com/message",
+  "traceid": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01",
-    "subject" : "Test XML Message",
+  "tracestate": "",
-    "id" : "id-1234-5678-9101",
+  "data" : "<note><to></to><from>user2</from><message>Order</message></note>",
-    "time" : "2020-09-23T06:23:21Z",
+  "id" : "id-1234-5678-9101",
-    "datacontenttype" : "text/xml",
+  "specversion" : "1.0",
-    "data" : "<note><to>User1</to><from>user2</from><message>hi</message></note>"
+  "datacontenttype" : "text/xml",
+  "subject" : "Test XML Message",
+  "source" : "https://example.com/message",
+  "type" : "xml.message",
+   "time" : "2020-09-23T06:23:21Z"
 }
 ```
 
+## Replace Dapr generated CloudEvents values
+
+Dapr automatically generates several CloudEvent properties. You can replace these generated CloudEvent properties by providing the following optional metadata key/value:
+
+- `cloudevent-id`: overrides `id`
+- `cloudevent-source`: overrides `source`
+- `cloudevent-type`: overrides `type`
+- `cloudevent-traceid`: overrides `traceid`
+- `cloudevent-tracestate`: overrides `tracestate`
+- `cloudevent-traceparent`: overrides `traceparent`
+
+The ability to replace CloudEvents properties using these metadata properties applies to all pub/sub components.
+
+### Example
+
+For example, to replace the `source` and `id` values from [the CloudEvent example above]({{< ref "#cloudevents-example" >}}) in code:
+
+{{< tabs "Python" ".NET" >}}
+ <!-- Python -->
+{{% codetab %}}
+
+```python
+with DaprClient() as client:
+    order = {'orderId': i}
+    # Publish an event/message using Dapr PubSub
+    result = client.publish_event(
+        pubsub_name='order_pub_sub',
+        topic_name='orders',
+        publish_metadata={'cloudevent-id: 'd99b228f-6c73-4e78-8c4d-3f80a043d317', cloudevent-source: 'payment'}
+    )
+```
+
+{{% /codetab %}}
+
+ <!-- .NET -->
+{{% codetab %}}
+
+```csharp
+var order = new Order(i);
+using var client = new DaprClientBuilder().Build();
+
+// Override cloudevent metadata
+var metadata = new Dictionary<string,string>() {
+    { "cloudevent.source", "payment" },
+    { "cloudevent.id", "d99b228f-6c73-4e78-8c4d-3f80a043d317" }
+}
+
+// Publish an event/message using Dapr PubSub
+await client.PublishEventAsync("order_pub_sub", "orders", order, metadata);
+Console.WriteLine("Published data: " + order);
+
+await Task.Delay(TimeSpan.FromSeconds(1));
+```
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+
+The JSON payload then reflects the new `source` and `id` values:
+
+
+```json
+{
+  "topic": "orders",
+  "pubsubname": "order_pub_sub",
+  "traceid": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01",
+  "tracestate": "",
+  "data": {
+    "orderId": 1
+  },
+  "id": "d99b228f-6c73-4e78-8c4d-3f80a043d317",
+  "specversion": "1.0",
+  "datacontenttype": "application/json; charset=utf-8",
+  "source": "payment",
+  "type": "com.dapr.event.sent",
+  "time": "2020-09-23T06:23:21Z",
+  "traceparent": "00-113ad9c4e42b27583ae98ba698d54255-e3743e35ff56f219-01"
+}
+```
+
+{{% alert title="Important" color="warning" %}}
+While you can replace `traceid`/`traceparent` and `tracestate`, doing this may interfere with tracing events and report inconsistent results in tracing tools. It's recommended to use Open Telementry for distributed traces. [Learn more about distributed tracing.]({{< ref tracing-overview.md >}})  
+
+{{% /alert %}}
+
+
 ## Publish your own CloudEvent
 
 If you want to use your own CloudEvent, make sure to specify the [`datacontenttype`]({{< ref "pubsub-overview.md#setting-message-content-types" >}}) as `application/cloudevents+json`.
+
 If the CloudEvent that was authored by the app does not contain the [minimum required fields](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#required-attributes) in the CloudEvent specification, the message is rejected. Dapr adds the following fields to the CloudEvent if they are missing:
 
 - `time`

daprdocs/content/en/developing-applications/integrations/gRPC-integration.md

@@ -132,7 +132,7 @@ The following steps will show how to create an app that exposes a server for wit
     	"github.com/golang/protobuf/ptypes/empty"
     
     	commonv1pb "github.com/dapr/dapr/pkg/proto/common/v1"
-    	pb "github.com/dapr/go-sdk/dapr/proto/runtime/v1"
+    	pb "github.com/dapr/dapr/pkg/proto/runtime/v1"
     	"google.golang.org/grpc"
     )
     ```

daprdocs/content/en/reference/api/bindings_api.md

@@ -37,6 +37,45 @@ If running on kubernetes apply the component to your cluster.
 
 > **Note:** In production never place passwords or secrets within Dapr component files. For information on securely storing and retrieving secrets using secret stores refer to [Setup Secret Store]({{< ref setup-secret-store >}})
 
+### Binding direction (optional)
+
+In some scenarios, it would be useful to provide additional information to Dapr to indicate the direction supported by the binding component. 
+Providing the supported binding direction helps the Dapr sidecar avoid the `"wait for the app to become ready"` state, where it waits indefinitely for the application to become available.
+
+You can specify the `direction` field as part of the component's metadata. The valid values for this field are: 
+- `"input"`
+- `"output"`
+- `"input, output"`
+
+Here a few scenarios when the `"direction"` metadata field could help:
+
+- When an application (detached from the sidecar) runs as a serverless workload and is scaled to zero, the `"wait for the app to become ready"` check done by the Dapr sidecar becomes pointless.
+
+- If the detached Dapr sidecar is scaled to zero and the application reaches the sidecar (before even starting an HTTP server), the `"wait for the app to become ready"` deadlocks the app and the sidecar into waiting for each other.
+
+### Example
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: kafkaevent
+spec:
+  type: bindings.kafka
+  version: v1
+  metadata:
+  - name: brokers
+    value: "http://localhost:5050"
+  - name: topics
+    value: "someTopic"
+  - name: publishTopic
+    value: "someTopic2"
+  - name: consumerGroup
+    value: "group1"
+  - name: "direction"
+    value: "input, output"
+```
+
 ## Invoking Service Code Through Input Bindings
 
 A developer who wants to trigger their app using an input binding can listen on a `POST` http endpoint with the route name being the same as `metadata.name`.

daprdocs/content/en/reference/components-reference/supported-middleware/middleware-bearer.md

@@ -22,22 +22,30 @@ spec:
   version: v1
   metadata:
     - name: audience
-      value: "<your token audience; e.g. the application's client ID>"
+      value: "<your token audience; i.e. the application's client ID>"
     - name: issuer
       value: "<your token issuer, e.g. 'https://accounts.google.com'>"
 
     # Optional values
     - name: jwksURL
-      value: "https://accounts.google.com/.well-known/openid-configuration"
+      value: "<JWKS URL, e.g. 'https://accounts.google.com/.well-known/openid-configuration'>"
 ```
+
 ## Spec metadata fields
 
 | Field | Required | Details | Example |
 |-------|:--------:|---------|---------|
 | `audience` | Y | The audience expected in the tokens. Usually, this corresponds to the client ID of your application that is created as part of a credential hosted by a OpenID Connect platform. | 
-| `issuer` | Y | The issuer authority, which is the value expected in the issuer claim in the tokens. | `"https://accounts.google.com"`, `"https://login.salesforce.com"`
+| `issuer` | Y | The issuer authority, which is the value expected in the issuer claim in the tokens. | `"https://accounts.google.com"`
 | `jwksURL` | N | Address of the JWKS (JWK Set containing the public keys for verifying tokens). If empty, will try to fetch the URL set in the OpenID Configuration document `<issuer>/.well-known/openid-configuration`.  | `"https://accounts.google.com/.well-known/openid-configuration"`
 
+Common values for `issuer` include:
+
+- Auth0: `https://{domain}`, where `{domain}` is the domain of your Auth0 application
+- Azure AD: `https://login.microsoftonline.com/{tenant}/v2.0`, where `{tenant}` should be replaced with the tenant ID of your application, as a UUID
+- Google: `https://accounts.google.com`
+- Salesforce (Force.com): `https://login.salesforce.com`
+
 ## Dapr configuration
 
 To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware.md">}}).

daprdocs/content/en/reference/resource-specs/component-schema.md

@@ -26,7 +26,7 @@ spec:
     value: [METADATA-VALUE]
 ```
 
-## Fields
+## Spec fields
 
 | Field              | Required | Details | Example |
 |--------------------|:--------:|---------|---------|

daprdocs/content/en/reference/resource-specs/configuration-schema.md

@@ -0,0 +1,105 @@
+---
+type: docs
+title: "Configuration spec"
+linkTitle: "Configuration"
+description: "The basic spec for a Dapr Configuration resource"
+weight: 5000
+---
+
+The `Configuration` is a Dapr resource that is used to configure the Dapr sidecar, control-plane, and others.
+
+## Sidecar format
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+  name: <REPLACE-WITH-NAME>
+  namespace: <REPLACE-WITH-NAMESPACE>
+spec:
+  api:
+    allowed:
+      - name: <REPLACE-WITH-API>
+        version: <VERSION>
+        protocol: <HTTP-OR-GRPC>
+  tracing:
+    samplingRate: <REPLACE-WITH-INTEGER>
+    stdout: true
+    otel:
+      endpointAddress: <REPLACE-WITH-ENDPOINT-ADDRESS>
+      isSecure: false
+      protocol: <HTTP-OR-GRPC>
+  httpPipeline: # for incoming http calls
+    handlers:
+      - name: <HANDLER-NAME>
+        type: <HANDLER-TYPE>
+  appHttpPipeline: # for outgoing http calls
+    handlers:
+      - name: <HANDLER-NAME>
+        type: <HANDLER-TYPE>
+  secrets:
+    scopes:
+      - storeName: <NAME-OF-SCOPED-STORE>
+        defaultAccess: <ALLOW-OR-DENY>
+        deniedSecrets: <REPLACE-WITH-DENIED-SECRET>
+  components:
+    deny:
+      - <COMPONENT-TO-DENY>
+  accessControl:
+    defaultAction: <ALLOW-OR-DENY>
+    trustDomain: <REPLACE-WITH-TRUST-DOMAIN>
+    policies:
+      - appId: <APP-NAME>
+        defaultAction: <ALLOW-OR-DENY>
+        trustDomain: <REPLACE-WITH-TRUST-DOMAIN>
+        namespace: "default"
+        operations:
+          - name: <OPERATION-NAME>
+            httpVerb: ['POST', 'GET']
+            action: <ALLOW-OR-DENY>
+```
+
+### Spec fields
+
+| Field              | Required | Details | Example |
+|--------------------|:--------:|---------|---------|
+| accessControl      | N        | Applied to Dapr sidecar for the called application. Enables the configuration of policies that restrict what operations calling applications can perform (via service invocation) on the called appliaction.  | [Learn more about the `accessControl` configuration.]({{< ref invoke-allowlist.md >}}) |
+| api                | N        | Used to enable only the Dapr sidecar APIs used by the application.  | [Learn more about the `api` configuration.]({{< ref api-allowlist.md >}}) |
+| httpPipeline       | N        | Configure API middleware pipelines | [Middleware pipeline configuration overview]({{< ref "configuration-overview.md#middleware" >}})<br>[Learn more about the `httpPipeline` configuration.]({{< ref "middleware.md#configure-api-middleware-pipelines" >}}) |
+| appHttpPipeline    | N        | Configure application middleware pipelines | [Middleware pipeline configuration overview]({{< ref "configuration-overview.md#middleware" >}})<br>[Learn more about the `appHttpPipeline` configuration.]({{< ref "middleware.md#configure-app-middleware-pipelines" >}}) |
+| components         | N        | Used to specify a denylist of component types that can't be initialized. | [Learn more about the `components` configuration.]({{< ref "configuration-overview.md#disallow-usage-of-certain-component-types" >}}) |
+| features           | N        | Defines the preview features that are enabled/disabled. | [Learn more about the `features` configuration.]({{< ref preview-features.md >}}) |
+| logging            | N        | Configure how logging works in the Dapr runtime. | [Learn more about the `logging` configuration.]({{< ref "configuration-overview.md#logging" >}})  |
+| metrics            | N        | Enable or disable metrics for an application. | [Learn more about the `metrics` configuration.]({{< ref "configuration-overview.md#metrics" >}}) |
+| nameResolution     | N        | Name resolution configuration spec for the service invocation building block. | [Learn more about the `nameResolution` configuration per components.]({{< ref supported-name-resolution.md >}}) |
+| secrets            | N        | Limit the secrets to which your Dapr application has access.  | [Learn more about the `secrets` configuration.]({{< ref secret-scope.md >}}) |
+| tracing            | N        | Turns on tracing for an application. | [Learn more about the `tracing` configuration.]({{< ref "configuration-overview.md#tracing" >}}) |
+
+
+## Control-plane format
+
+The `daprsystem` configuration file installed with Dapr applies global settings and is only set up when Dapr is deployed to Kubernetes. 
+
+```yml
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+  name: daprsystem
+  namespace: default
+spec:
+  mtls:
+    enabled: true
+    allowedClockSkew: 15m
+    workloadCertTTL: 24h
+```
+
+### Spec fields
+
+| Field              | Required | Details | Example |
+|--------------------|:--------:|---------|---------|
+| mtls               | N        | Defines the mTLS configuration | `allowedClockSkew: 15m`<br>`workloadCertTTL:24h`<br>[Learn more about the `mtls` configuration.]({{< ref "configuration-overview.md#mtls-mutual-tls" >}}) |
+
+
+## Related links
+
+- [Learn more about how to use configuration specs]({{< ref configuration-overview.md >}})

daprdocs/content/en/reference/resource-specs/httpendpoints-schema.md

@@ -10,7 +10,7 @@ aliases:
 
 The `HTTPEndpoint` is a Dapr resource that is used to enable the invocation of non-Dapr endpoints from a Dapr application.
 
-## HTTPEndpoint format
+## Format
 
 ```yaml
 apiVersion: dapr.io/v1alpha1

daprdocs/content/en/reference/resource-specs/resiliency-schema.md

@@ -8,6 +8,8 @@ description: "The basic spec for a Dapr resiliency resource"
 
 The `Resiliency` Dapr resource allows you to define and apply fault tolerance resiliency policies. Resiliency specs are applied when the Dapr sidecar starts. 
 
+## Format
+
 ```yml
 apiVersion: dapr.io/v1alpha1
 kind: Resiliency

daprdocs/content/en/reference/resource-specs/subscription-schema.md

@@ -11,7 +11,7 @@ The `Subscription` Dapr resource allows you to subscribe declaratively to a topi
 - `v2alpha` (default spec)
 - `v1alpha1` (deprecated)
 
-## `v2alpha1`
+## `v2alpha1` format
 
 The following is the basic `v2alpha1` spec for a `Subscription` resource. `v2alpha1` is the default spec for the subscription API.
 
@@ -48,7 +48,7 @@ scopes:
 | bulksubscribe | N | Enable bulk subscribe properties. | `true`, `false` |
 
 
-## `v1alpha1`
+## `v1alpha1` format
 
 The following is the basic version `v1alpha1` spec for a `Subscription` resource. `v1alpha1` is now deprecated.