mirror of https://github.com/dapr/docs.git
Merge branch 'v1.0-rc3' into homepage-refresh
This commit is contained in:
Ori Zohar
GitHub
commit
9305721c31
|
|
@ -32,7 +32,7 @@ spec:
|
|||
- name: spnClientId
|
||||
value: "[your_service_principal_app_id]"
|
||||
- name: spnCertificateFile
|
||||
value : "[pfx_certificate_file_local_path]"
|
||||
value : "[pfx_certificate_file_fully_qualified_local_path]"
|
||||
```
|
||||
{{% alert title="Warning" color="warning" %}}
|
||||
The above example uses secrets as plain strings. It is recommended to use a local secret store such as [Kubernetes secret store]({{< ref kubernetes-secret-store.md >}}) or a [local file]({{< ref file-secret-store.md >}}) to bootstrap secure key storage.
|
||||
|
|
@ -43,9 +43,9 @@ The above example uses secrets as plain strings. It is recommended to use a loca
|
|||
| Field | Required | Details | Example |
|
||||
|--------------------|:--------:|-------------------------------------------------------------------------|--------------------------|
|
||||
| vaultName | Y | The name of the Azure Key Vault | `"mykeyvault"` |
|
||||
| spnTenantId | Y | Your Service Principal Tenant Id | `"spnTenantId"` |
|
||||
| spnClientId | Y | Your Service Principal App Id | `"spnAppId"` |
|
||||
| spnCertificateFile | Y | Your PFX certificate file path. See [configure the component](#configure-the-component) for more details | `"path"` |
|
||||
| spnTenantId | Y | Service Principal Tenant Id | `"spnTenantId"` |
|
||||
| spnClientId | Y | Service Principal App Id | `"spnAppId"` |
|
||||
| spnCertificateFile | Y | PFX certificate file path. <br></br> For Windows the `[pfx_certificate_file_fully_qualified_local_path]` value must use escaped backslashes, i.e. double backslashes. For example `"C:\\folder1\\folder2\\certfile.pfx"`. <br></br> For Linux you can use single slashes. For example `"/folder1/folder2/certfile.pfx"`. <br></br> See [configure the component](#configure-the-component) for more details | `"C:\\folder1\\folder2\\certfile.pfx"`, `"/folder1/folder2/certfile.pfx"` |
|
||||
|
||||
## Setup Key Vault and service principal
|
||||
|
||||
|
|
@ -151,22 +151,22 @@ The above example uses secrets as plain strings. It is recommended to use a loca
|
|||
- name: spnClientId
|
||||
value: "[your_service_principal_app_id]"
|
||||
- name: spnCertificateFile
|
||||
value : "[pfx_certificate_file_local_path]"
|
||||
value : "[pfx_certificate_file_fully_qualified_local_path]"
|
||||
```
|
||||
|
||||
Fill in the metadata fields with your Key Vault details from the above setup process.
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
In Kubernetes mode, you store the certificate for the service principal into the Kubernetes Secret Store and then enable Azure Key Vault secret store with this certificate in Kubernetes secretstore.
|
||||
In Kubernetes, you store the certificate for the service principal into the Kubernetes Secret Store and then enable Azure Key Vault secret store with this certificate in Kubernetes secretstore.
|
||||
|
||||
1. Create a kubernetes secret using the following command:
|
||||
|
||||
```bash
|
||||
kubectl create secret generic [your_k8s_spn_secret_name] --from-file=[pfx_certificate_file_local_path]
|
||||
kubectl create secret generic [your_k8s_spn_secret_name] --from-file=[pfx_certificate_file_fully_qualified_local_path]
|
||||
```
|
||||
|
||||
- `[pfx_certificate_file_local_path]` is the path of PFX cert file you downloaded above
|
||||
- `[pfx_certificate_file_fully_qualified_local_path]` is the path of PFX cert file you downloaded above
|
||||
- `[your_k8s_spn_secret_name]` is secret name in Kubernetes secret store
|
||||
|
||||
2. Create a `azurekeyvault.yaml` component file
|
||||
|
|
@ -192,7 +192,7 @@ spec:
|
|||
- name: spnCertificate
|
||||
secretKeyRef:
|
||||
name: [your_k8s_spn_secret_name]
|
||||
key: [pfx_certificate_file_local_name]
|
||||
key: [pfx_certificate_file_fully_qualified_local_path]
|
||||
auth:
|
||||
secretStore: kubernetes
|
||||
```
|
||||
|
|
|
|||
|
|
@ -140,13 +140,16 @@ It is recommended that a production-ready deployment includes the following sett
|
|||
|
||||
1. Mutual Authentication (mTLS) should be enabled. Note that Dapr has mTLS on by default. For details on how to bring your own certificates, see [here]({{< ref "mtls.md#bringing-your-own-certificates" >}})
|
||||
|
||||
2. Dapr API authentication is enabled (this is the communication between your application and the Dapr sidecar). To secure the Dapr API from unauthorized access, it is recommended to enable Dapr's token based auth. See [here]({{< ref "api-token.md" >}}) for details
|
||||
2. App to Dapr API authentication is enabled. This is the communication between your application and the Dapr sidecar. To secure the Dapr API from unauthorized application access, it is recommended to enable Dapr's token based auth. See [enable API token authentication in Dapr]({{< ref "api-token.md" >}}) for details
|
||||
|
||||
3. All component YAMLs should have secret data configured in a secret store and not hard-coded in the YAML file. See [here]({{< ref "component-secrets.md" >}}) on how to use secrets with Dapr components
|
||||
3. Dapr to App API authentication is enabled. This is the communication between Dapr and your application. This ensures that Dapr knows that it is communicating with an authorized application. See [Authenticate requests from Dapr using token authentication] ({{< ref "app-api-token.md" >}}) for details
|
||||
|
||||
4. The Dapr control plane is installed on a dedicated namespace such as `dapr-system`.
|
||||
4. All component YAMLs should have secret data configured in a secret store and not hard-coded in the YAML file. See [here]({{< ref "component-secrets.md" >}}) on how to use secrets with Dapr components
|
||||
|
||||
5. The Dapr control plane is installed on a dedicated namespace such as `dapr-system`.
|
||||
|
||||
6. Dapr also supports scoping components for certain applications. This is not a required practice, and can be enabled according to your security needs. See [here]({{< ref "component-scopes.md" >}}) for more info.
|
||||
|
||||
Dapr also supports scoping components for certain applications. This is not a required practice, and can be enabled according to your security needs. See [here]({{< ref "component-scopes.md" >}}) for more info.
|
||||
|
||||
## Tracing and metrics configuration
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Enable token based API authentication"
|
||||
linkTitle: "API token auth"
|
||||
title: "Enable API token authentication in Dapr"
|
||||
linkTitle: "Dapr API token authentication"
|
||||
weight: 3000
|
||||
description: "Require every incoming API request to include an authentication token before allowing that request to pass through"
|
||||
description: "Require every incoming API request for Dapr to include an authentication token before allowing that request to pass through"
|
||||
---
|
||||
|
||||
By default, Dapr relies on the network boundary to limit access to its public API. If you plan on exposing the Dapr API outside of that boundary, or if your deployment demands an additional level of security, consider enabling the token authentication for Dapr APIs. This will cause Dapr to require every incoming gRPC and HTTP request for its APIs for to include authentication token, before allowing that request to pass through.
|
||||
|
|
@ -107,6 +107,30 @@ When using gRPC protocol, Dapr will inspect the incoming calls for the API token
|
|||
dapr-api-token[0].
|
||||
```
|
||||
|
||||
## Accessing the token from the app
|
||||
|
||||
### Kubernetes
|
||||
|
||||
In Kubernetes, it's recommended to mount the secret to your pod as an environment variable, as shown in the example below, where a Kubernetes secret with the name `dapr-api-token` is used to hold the token.
|
||||
|
||||
```
|
||||
containers:
|
||||
- name: mycontainer
|
||||
image: myregistry/myapp
|
||||
envFrom:
|
||||
- secretRef:
|
||||
name: dapr-api-token
|
||||
```
|
||||
|
||||
### Self-hosted
|
||||
|
||||
In self-hosted mode, you can set the token as an environment variable for your app:
|
||||
|
||||
```
|
||||
export DAPR_API_TOKEN=<my-dapr-token>
|
||||
```
|
||||
|
||||
## Related Links
|
||||
|
||||
* [Other security related topics](https://github.com/dapr/docs/blob/master/concepts/security/README.md)
|
||||
- Learn about [Dapr security concepts]({{< ref security-concept.md >}})
|
||||
- Learn [HowTo authenticate requests from Dapr using token authentication]({{< ref app-api-token.md >}})
|
||||
|
|
|
|||
|
|
@ -0,0 +1,138 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Authenticate requests from Dapr using token authentication"
|
||||
linkTitle: "App API token authentication"
|
||||
weight: 4000
|
||||
description: "Require every incoming API request from Dapr to include an authentication token"
|
||||
---
|
||||
|
||||
For some building blocks such as pub/sub, service invocation and input bindings, Dapr communicates with an app over HTTP or gRPC.
|
||||
To enable the application to authenticate requests that are arriving from the Dapr sidecar, you can configure Dapr to send an API token as a header (in HTTP requests) or metadata (in gRPC requests).
|
||||
|
||||
## Create a token
|
||||
|
||||
Dapr uses [JWT](https://jwt.io/) tokens for API authentication.
|
||||
|
||||
> Note, while Dapr itself is actually not the JWT token issuer in this implementation, being explicit about the use of JWT standard enables federated implementations in the future (e.g. OAuth2).
|
||||
|
||||
To configure API authentication, start by generating your token using any JWT token compatible tool (e.g. https://jwt.io/) and your secret.
|
||||
|
||||
> Note, that secret is only necessary to generate the token, and Dapr doesn't need to know about or store it
|
||||
|
||||
## Configure app API token authentication in Dapr
|
||||
|
||||
The token authentication configuration is slightly different for either Kubernetes or self-hosted Dapr deployments:
|
||||
|
||||
### Self-hosted
|
||||
|
||||
In self-hosting scenario, Dapr looks for the presence of `APP_API_TOKEN` environment variable. If that environment variable is set while `daprd` process launches, Dapr includes the token when calling an app:
|
||||
|
||||
```shell
|
||||
export APP_API_TOKEN=<token>
|
||||
```
|
||||
|
||||
To rotate the configured token, simply set the `APP_API_TOKEN` environment variable to the new value and restart the `daprd` process.
|
||||
|
||||
### Kubernetes
|
||||
|
||||
In Kubernetes deployment, Dapr leverages Kubernetes secrets store to hold the JWT token. Start by creating a new secret:
|
||||
|
||||
```shell
|
||||
kubectl create secret generic app-api-token --from-literal=token=<token>
|
||||
```
|
||||
|
||||
> Note, the above secret needs to be created in each namespace in which you want to enable app token authentication
|
||||
|
||||
To indicate to Dapr to use the token in the secret when sending requests to the app, add an annotation to your Deployment template spec:
|
||||
|
||||
```yaml
|
||||
annotations:
|
||||
dapr.io/enabled: "true"
|
||||
dapr.io/app-token-secret: "app-api-token" # name of the Kubernetes secret
|
||||
```
|
||||
|
||||
When deployed, the Dapr Sidecar Injector automatically creates a secret reference and injects the actual value into `APP_API_TOKEN` environment variable.
|
||||
|
||||
## Rotate a token
|
||||
|
||||
### Self-hosted
|
||||
|
||||
To rotate the configured token in self-hosted, simply set the `APP_API_TOKEN` environment variable to the new value and restart the `daprd` process.
|
||||
|
||||
### Kubernetes
|
||||
|
||||
To rotate the configured token in Kubernates, update the previously created secret with the new token in each namespace. You can do that using `kubectl patch` command, but the easiest way to update these in each namespace is by using manifest:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: app-api-token
|
||||
type: Opaque
|
||||
data:
|
||||
token: <your-new-token>
|
||||
```
|
||||
|
||||
And then apply it to each namespace:
|
||||
|
||||
```shell
|
||||
kubectl apply --file token-secret.yaml --namespace <namespace-name>
|
||||
```
|
||||
|
||||
To tell Dapr to start using the new token, trigger a rolling upgrade to each one of your deployments:
|
||||
|
||||
```shell
|
||||
kubectl rollout restart deployment/<deployment-name> --namespace <namespace-name>
|
||||
```
|
||||
|
||||
> Note, assuming your service is configured with more than one replica, the key rotation process does not result in any downtime.
|
||||
|
||||
|
||||
## Authenticating requests from Dapr
|
||||
|
||||
Once app token authentication is configured in Dapr, all requests *coming from Dapr* include the token:
|
||||
|
||||
### HTTP
|
||||
|
||||
In case of HTTP, inspect the incoming request for presence of `dapr-api-token` parameter in HTTP header:
|
||||
|
||||
```shell
|
||||
dapr-api-token: <token>
|
||||
```
|
||||
|
||||
### gRPC
|
||||
|
||||
When using gRPC protocol, inspect the incoming calls for the API token on the gRPC metadata:
|
||||
|
||||
```shell
|
||||
dapr-api-token[0].
|
||||
```
|
||||
|
||||
## Accessing the token from the app
|
||||
|
||||
### Kubernetes
|
||||
|
||||
In Kubernetes, it's recommended to mount the secret to your pod as an environment variable.
|
||||
Assuming we created a secret with the name `app-api-token` to hold the token:
|
||||
|
||||
```
|
||||
containers:
|
||||
- name: mycontainer
|
||||
image: myregistry/myapp
|
||||
envFrom:
|
||||
- secretRef:
|
||||
name: app-api-token
|
||||
```
|
||||
|
||||
### Self-hosted
|
||||
|
||||
In self-hosted mode, you can set the token as an environment variable for your app:
|
||||
|
||||
```
|
||||
export APP_API_TOKEN=<my-app-token>
|
||||
```
|
||||
|
||||
## Related Links
|
||||
|
||||
- Learn about [Dapr security concepts]({{< ref security-concept.md >}})
|
||||
- Learn [HowTo Enable API token authentication in Dapr]({{< ref api-token.md >}})
|
||||
Loading…
Reference in New Issue