feat: add initial zero trust docs for review #1362
Conversation
Signed-off-by: dovholuknf <[email protected]>
|
related to issue #1351 |
There was a problem hiding this comment.
@dovholuknf I've provided some comments inline.
Overall speaking, this documentation requires some background knowledge from both EdgeX Foundry microservices and https://openziti.io/docs/learn/introduction/ to read through. For readability and easier to understand, I'd suggest to add a step by step quickstart like https://openziti.io/docs/learn/quickstarts/network/local-docker-compose as the initial section, and then put every section under below to further explain the details. We can directly leverage compose files as available from https://github.com/edgexfoundry/edgex-compose as the material of the quickstart.
|
|
||
| * Explicit Authorization: connections should be authenticated before traffic can be sent | ||
| * Cryptographically Verifiable Identities: connections should be authenticated using strong identities | ||
| * Least Privilege Access: identities should have access only the minimum set of services they require |
There was a problem hiding this comment.
| * Least Privilege Access: identities should have access only the minimum set of services they require | |
| * Least Privilege Access: identities should have access to only the minimum set of services they require | |
|
|
||
| EdgeX has adopted and integrated OpenZiti into it's microservice architecture and can now be enabled through | ||
| standard EdgeX configuration mechanisms. In order to build a zero trust overlay network usable by EdgeX, an OpenZiti | ||
| overlay network will need to be available and configured. The EdgeX project provides a docker compose file that deploys |
There was a problem hiding this comment.
It would be nice if we can also provide the link to the docker compose file here.
| ### Example JWT Verification With OpenZiti | ||
|
|
||
| Let's look at an example verification process to understand better how the JWT from the token provider is used to | ||
| authenticate to the OpenZiti overlay. | ||
|
|
||
| 1. After the EdgeX Foundry security bootstrapper completes, a token from the token provider for the target service | ||
| will be available to the service. | ||
| 2. The token is read into memory. | ||
| 3. The token is exchanged with the token provider for a JWT. Here is a representative payload section of a JWT | ||
| delivered to the core-command service: | ||
|
|
||
| { | ||
| "aud": "edgex", | ||
| "exp": 1720809046, | ||
| "iat": 1720808146, | ||
| "iss": "/v1/identity/oidc", | ||
| "name": "core-command", | ||
| "namespace": "root", | ||
| "sub": "790fd597-f773-21a6-158f-ee1158875115" | ||
| } | ||
|
|
||
| Notice the fields contained within the JWT payload, both the issuer (`iss`) field `name` field are important and | ||
| are used in the OpenZiti `ext-jwt-signer` configuration. The `iss` field must match a configured `ext-jwt-signer`. | ||
| 4. The JWT is sent to OpenZiti for verification. | ||
| 5. OpenZiti makes a request to the token provider's JWKS endpoint (as needed) to obtain the necessary key material | ||
| to verify the authenticity of the JWT. | ||
| 6. Once the JWT is verified as authentic, the configured field (in this case `name`) read from the JWT. | ||
| 7. OpenZiti scans all identities for one with an `--externalId` set to the value from the JWT (in this case | ||
| `core-command`) | ||
| 8. If an identity is found with an associated auth policy utilizing the expected value (`core-command`), the | ||
| identity is considered authenticated. |
There was a problem hiding this comment.
Feel a little bit confused about this process. Has this process already implemented into EdgeX Foundry services using Vault or OpenBao as token provider? Do we have an existing compose file that can deploy EdgeX Foundry using such verification process? If this process provided as a reference for users who needs to configure their own token porvider?
If so, maybe provide a tutorial as similar to https://openziti.io/docs/learn/quickstarts/network/local-docker-compose here, and execute some steps to explain the process, such as run up services, point out what configurations in the compose file to look at and change, test the core-command API etc. Would this be easier for users to understand this process?
| A great example of an IP-based underlay service that needs access to EdgeX Foundry services is consul. Consul is | ||
| configured to check the health of services but consul is not OpenZiti-enabled and requires IP-based underlay access | ||
| in order to perform health checks. | ||
|
|
||
| When running in zero trust mode, each service provides the intercept value for the service as input to the consul | ||
| configuration. When a new service is registered in consul and the healthcheck starts, it will only understand how to | ||
| make a classic, IP-based connection to the endpoint which will not succeed. | ||
|
|
||
| To allow consul health checks to succeed another container needs to be deployed. A new container is deployed when | ||
| running in zero trust mode found from ghcr.io/openziti-test-kitchen/healthcheck-proxy/healthcheck-proxy:latest. Read | ||
| the [README.md](https://github.com/openziti-test-kitchen/healthcheck-proxy) to learn more about how to configure it. | ||
| This container starts up and waits for an identity file to be provided to it (which is done during the | ||
| initialization phase by the `openziti-init-entrypoint.sh` script), authorizing the container to make requests to | ||
| EdgeX Foundry services. This identity is created with the `#edgex-healthchecker` role which authorizes the identity | ||
| to connect to all services. The proxy is then configured to only allow specific requests through. By default, the | ||
| proxy will only allow `GET` requests to urls ending with `/ping` and only hostnames ending with `.edgex.ziti` on | ||
| port 80. | ||
|
|
||
| In order to capture these requests, the container leverages the docker network it's part of and has an alias | ||
| assigned for each intercept (all preconfigured). |
There was a problem hiding this comment.
Consul will be removed in EdgeX Foundry v4.0 (see edgexfoundry/edgex-go#4985) and replaced by core-keeper (see edgexfoundry/edgex-go#4783), so we shall consider if this part should be revised to reflect such changes.
| policies allow the operator of the overlay network to authorize individual identities or groups of identities to | ||
| access services, also by name or by grouping. | ||
|
|
||
| When EdgeX Foundry is configured using the `openziti-init-entrypoint.sh` script, it will precreate all the services for |
There was a problem hiding this comment.
For better understanding, I'd suggest to add a section like a step by step tutorial to elaborate more details about how EdgeX Foundry is configured using the openziti-init-entrypoint.sh. I expect this tutorial may include steps such as the prerequisite setup, what repository to clone for the script and setup, how to create openziti overlay network and run up services enabled with openziti, and a test to access core services protected by openziti etc.
| optional service later on, the OpenZiti overlay network will likely have an existing service already. | ||
|
|
||
| When initializing the OpenZiti overlay for EdgeX Foundry, an initial set of services will be configured in the | ||
| OpenZiti overlay network. Below is an incomplete listing of those services For the most complete table, refer to the |
There was a problem hiding this comment.
| OpenZiti overlay network. Below is an incomplete listing of those services For the most complete table, refer to the | |
| OpenZiti overlay network. Below is an incomplete listing of those services. For the most complete table, refer to the |
It seems that the incomplete listing is missing here.
|
|
||
| When initializing the OpenZiti overlay for EdgeX Foundry, an initial set of services will be configured in the | ||
| OpenZiti overlay network. Below is an incomplete listing of those services For the most complete table, refer to the | ||
| `openziti-init-entrypoint.sh` script itself. |
There was a problem hiding this comment.
Suggest to add a link to access the openziti-init-entrypoint.sh script.
| OPENZITI_PERSISTENCE_PATH="/edgex_openziti" | ||
| OPENZITI_EDGEX_ROUTER_NAME="edgex.router" | ||
| OPENZITI_CONTROLLER_ROUTER_NAME="ip-172-31-47-200-edge-router" | ||
| EDGEX_TOKEN_PROVIDER_HOST=edgex-vault |
There was a problem hiding this comment.
| EDGEX_TOKEN_PROVIDER_HOST=edgex-vault | |
| EDGEX_TOKEN_PROVIDER_HOST=edgex-secret-store |
edgex-vault is no longer available in EdgeX Foundery and is replaced by edgex-secret-store using openbao image. (see edgexfoundry/edgex-compose#474)
| OPENZITI_CONTROLLER_ROUTER_NAME="ip-172-31-47-200-edge-router" | ||
|
|
||
| OPENZITI_PERSISTENCE_PATH=/edgex_openziti | ||
| EDGEX_TOKEN_PROVIDER_HOST="edgex-vault" |
There was a problem hiding this comment.
| EDGEX_TOKEN_PROVIDER_HOST="edgex-vault" | |
| EDGEX_TOKEN_PROVIDER_HOST="edgex-secret-store" |
| ``` | ||
| openziti-router: | ||
| container_name: edgex-openziti-router | ||
| image: openziti/ziti-cli:1.1.4 |
There was a problem hiding this comment.
The https://github.com/edgexfoundry/edgex-compose/blob/main/docker-compose-openziti.yml#L4 still uses openziti/ziti-cli:0.34.1
Shall we also update compose file as well for accordance?
PR Checklist
Please check if your PR fulfills the following requirements:
Here's an initial attempt at documenting OpenZIti with EdgeX Foundry