HTTP binding spec

Alternative

The service invocation API allows for the invocation of non-Dapr HTTP endpoints and is the recommended approach. Read “How-To: Invoke Non-Dapr Endpoints using HTTP” for more information.

Setup Dapr component

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.http
  version: v1
  metadata:
  - name: url
    value: "http://something.com"
  - name: MTLSRootCA
    value: "/Users/somepath/root.pem" # OPTIONAL Secret store ref, <path to root CA>, or <pem encoded string>
  - name: MTLSClientCert
    value: "/Users/somepath/client.pem" # OPTIONAL Secret store ref, <path to client cert>, or <pem encoded string>
  - name: MTLSClientKey
    value: "/Users/somepath/client.key" # OPTIONAL Secret store ref, <path to client key>, or <pem encoded string>
  - name: MTLSRenegotiation
    value: "RenegotiateOnceAsClient" # OPTIONAL one of: RenegotiateNever, RenegotiateOnceAsClient, RenegotiateFreelyAsClient
  - name: securityToken # OPTIONAL <token to include as a header on HTTP requests>
    secretKeyRef:
      name: mysecret
      key: "mytoken"
  - name: securityTokenHeader
    value: "Authorization: Bearer" # OPTIONAL <header name for the security token>
  - name: direction # OPTIONAL
    value: "output"
  - name: errorIfNot2XX
    value: "false" # OPTIONAL

Spec metadata fields

How to configure MTLS related fields in Metadata

The values for MTLSRootCA, MTLSClientCert and MTLSClientKey can be provided in three ways:

1. Secret store reference

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.http
  version: v1
  metadata:
  - name: url
    value: http://something.com
  - name: MTLSRootCA
    secretKeyRef:
      name: mysecret
      key: myrootca
auth:
  secretStore: <NAME_OF_SECRET_STORE_COMPONENT>

2. Path to the file: The absolute path to the file can be provided as a value for the field.
3. PEM encoded string: The PEM encoded string can also be provided as a value for the field.

Binding support

This component supports output binding with the following HTTP methods/verbs:

• create : For backward compatibility and treated like a post
• get : Read data/records
• head : Identical to get except that the server does not return a response body
• post : Typically used to create records or send commands
• put : Update data/records
• patch : Sometimes used to update a subset of fields of a record
• delete : Delete a data/record
• options : Requests for information about the communication options available (not commonly used)
• trace : Used to invoke a remote, application-layer loop- back of the request message (not commonly used)

Request

Operation metadata fields

All of the operations above support the following metadata fields

Retrieving data

To retrieve data from the HTTP endpoint, invoke the HTTP binding with a GET method and the following JSON body:

{
  "operation": "get"
}

Optionally, a path can be specified to interact with resource URIs:

{
  "operation": "get",
  "metadata": {
    "path": "/things/1234"
  }
}

Response

The response body contains the data returned by the HTTP endpoint. The data field contains the HTTP response body as a byte slice (Base64 encoded via curl). The metadata field contains:

Example

Requesting the base URL

• Windows
• Linux

curl -d "{ \"operation\": \"get\" }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get" }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Requesting a specific path

• Windows
• Linux

curl -d "{ \"operation\": \"get\", \"metadata\": { \"path\": \"/things/1234\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get", "metadata": { "path": "/things/1234" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Sending and updating data

To send data to the HTTP endpoint, invoke the HTTP binding with a POST, PUT, or PATCH method and the following JSON body:

{
  "operation": "post",
  "data": "content (default is JSON)",
  "metadata": {
    "path": "/things",
    "Content-Type": "application/json; charset=utf-8"
  }
}

Example

Posting a new record

• Windows
• Linux

curl -d "{ \"operation\": \"post\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"path\": \"/things\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "path": "/things" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Using HTTPS

The HTTP binding can also be used with HTTPS endpoints by configuring the Dapr sidecar to trust the server’s SSL certificate.

1. Update the binding URL to use https instead of http.
2. Refer How-To: Install certificates in the Dapr sidecar, to install the SSL certificate in the sidecar.

Example

Update the binding component

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
  namespace: <NAMESPACE>
spec:
  type: bindings.http
  version: v1
  metadata:
  - name: url
    value: https://my-secured-website.com # Use HTTPS

Install the SSL certificate in the sidecar

• Self-Hosted
• Kubernetes

version: '3'
services:
  my-app:
    # ...
  dapr-sidecar:
    image: "daprio/daprd:1.8.0"
    command: [
      "./daprd",
     "-app-id", "myapp",
     "-app-port", "3000",
     ]
    volumes:
        - "./components/:/components"
        - "/tmp/ssl/:/certificates" # Mount the certificates folder to the sidecar container at /certificates
    environment:
      - "SSL_CERT_DIR=/certificates" # Set the environment variable to the path of the certificates folder
    depends_on:
      - my-app

kubectl create secret generic myapp-cert --from-file /tmp/ssl/cert.pem

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: default
  labels:
    app: myapp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
      annotations:
        dapr.io/enabled: "true"
        dapr.io/app-id: "myapp"
        dapr.io/app-port: "8000"
        dapr.io/volume-mounts: "cert-vol:/certificates" # Mount the certificates folder to the sidecar container at /certificates
        dapr.io/env: "SSL_CERT_DIR=/certificates" # Set the environment variable to the path of the certificates folder
    spec:
      volumes:
        - name: cert-vol
          secret:
            secretName: myapp-cert
...

Invoke the binding securely

• Windows
• Linux

curl -d "{ \"operation\": \"get\" }" \
      https://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get" }' \
      https://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Using mTLS or enabling client TLS authentication along with HTTPS

You can configure the HTTP binding to use mTLS or client TLS authentication along with HTTPS by providing the MTLSRootCA, MTLSClientCert, and MTLSClientKey metadata fields in the binding component.

These fields can be passed as a file path or as a pem encoded string.

• If the file path is provided, the file is read and the contents are used.
• If the pem encoded string is provided, the string is used as is. When these fields are configured, the Dapr sidecar uses the provided certificate to authenticate itself with the server during the TLS handshake process.

If the remote server is enforcing TLS renegotiation, you also need to set the metadata field MTLSRenegotiation. This field accepts one of following options:

• RenegotiateNever
• RenegotiateOnceAsClient
• RenegotiateFreelyAsClient.

For more details see the Go RenegotiationSupport documentation.

When to use:

You can use this when the server with which the HTTP binding is configured to communicate requires mTLS or client TLS authentication.

Related links

• Basic schema for a Dapr component
• Bindings building block
• How-To: Trigger application with input binding
• How-To: Use bindings to interface with external resources
• Bindings API reference
• How-To: Install certificates in the Dapr sidecar