Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added some scenarios to the architecture #47

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open

Added some scenarios to the architecture #47

Changes from 3 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
eca1c7c
add some workload scenarios
joe-venafi Dec 9, 2024
89b38b9
Added cross domain scenario
joe-venafi Dec 11, 2024
d8cc092
fix whitespace
joe-venafi Dec 11, 2024
209ea27
Update draft-ietf-wimse-arch.md
jsalowey Dec 23, 2024
c4e70a8
Update draft-ietf-wimse-arch.md
jsalowey Dec 23, 2024
2b68098
Update draft-ietf-wimse-arch.md
jsalowey Dec 23, 2024
dd0dc0c
Update draft-ietf-wimse-arch.md
jsalowey Dec 23, 2024
5fc2e58
Update draft-ietf-wimse-arch.md
jsalowey Dec 23, 2024
aaeac35
Update draft-ietf-wimse-arch.md
jsalowey Dec 23, 2024
eb75c8c
Update draft-ietf-wimse-arch.md
jsalowey Dec 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
216 changes: 214 additions & 2 deletions draft-ietf-wimse-arch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,220 @@ Both X.509 certificate and workload identity token credentials consist of two pa

The certificate or WIT is presented during authentication, however the private key is kept secret and only used in cryptographic computation to prove that the presenter has access to the private key corresponding to the public key.



## Workload Identity System Scenarios

### Basic Workload Identity Scenario

~~~aasvg
+------------------------------------------------------------+
| |
| |
+-----+ +--------------+ |
| | | | (3) |
| | +---> Workload 1 +-------------------+ |
| G | | | | | |
| a | | +-------^------+ | |
| t | | | | |
+------------+ | e | | | (1) | |
| | (2) | w | (3) | | | |
| App Client +----->| a +-----+ +-------+-------+ | |
| | | y | | | +-------+------+ |
+------------+ | +-----+ | CA/Credential | (1) | | |
| S | (4) | | Service +----------> Workload 3 | |
| e | | | | | | |
| r | | +-------+-------+ +-------+------+ |
| v | | | | |
| i | | | (1) | |
| c | | | | |
| e | | +-------v------+ | |
| | | | | (4) | |
| | +---> Workload 2 +-------------------+ |
| | | | |
+-----+ +--------------+ |
| |
| |
| Internal Trust Domain |
jsalowey marked this conversation as resolved.
Show resolved Hide resolved
+------------------------------------------------------------+
~~~~
{: #arch-basic title="Basic example workload application system."}


The above diagram presents a basic workload application system. The large box represents a trust boundary within which the workload application is hosted. Within this example
jsalowey marked this conversation as resolved.
Show resolved Hide resolved
there are three workloads, a gateway, that accepts external clients and a CA/credential service that issues workload identity credentials for the trust domain. External
to the workload application system there is an application client that calls APIs on workloads.

Here is a brief summary of each component

* Trust Domain

The large box represents the internal trust domain of the application that is composed of several workloads. A trust domain may have a more complex internal structure with more workloads, multiple gateways, internal infrastructure, and other services.
jsalowey marked this conversation as resolved.
Show resolved Hide resolved

* Workload

Three workloads are shown. Each workload is an instance of running software executing for a specific purpose. Workloads obtain their identity credentials from a Credentials Service (1) and use them to authenticate to other workloads and systems in the process
of sending and receiving requests to and from external systems or other internal workloads.

* Gateway Service

A gateway service typically acts as an intermediary between the internal application trust domain and external systems. The gateway is responsible for ensuring appropriate isolation between external and internal domains. It also routes incoming requests to the correct workload.
The gateway may also handle authentication, token exchange, and token transformation.

* CA/Credential Service

In this diagram the token/Credential service is a service responsible for issuing workload identities to workloads in the internal trust domain. The credentials are often X.509 based or JWT based.
jsalowey marked this conversation as resolved.
Show resolved Hide resolved

High level flows within the diagram

* (1) Workload Identity Credential Distribution

Workloads typically retrieve their workload identity credentials early in their lifecycle from a credentials service associated with their trust domain. The protocol interaction for
obtaining credentials varies with deployment and is not detailed here.

* (2) Application client Requests

Clients send API requests to the application. In the example above, the gateway routes the request to the correct workload. In addition, the gateway may assist in authenticating the incoming request and provide information resulting from the authentication to the target workload. The authentication exchange is not covered in detail in this example.
The client request is typically made over HTTPS, but other protocols may be used in some systems. The gateway usually terminates the TLS session so it has visibility into the request in order to route it correctly.

* (3) API request to workload 1

The gateway is configured to forward requests to the correct workload. The gateway often modifies the request to include specific authentication information about the application client and to remove any information that should not be forwarded internally. The gateway authenticates the workload before forwarding the request. This authentication usually uses TLS. The target workload may authenticate the gateway using TLS or some other means. As part of servicing the request the workload must make a request to another workload in the system. In this scenario the workload is making a request to workload 3 over HTTPS. Workload 1 may be able to authenticate the identity of workload 3 through the TLS protocol to ensure it is making a request of the right party. Workload 3 will authenticate workload 1 using its workload identity credentials. If the workload identity credentials are X.509 certificates then this can happen through TLS client authentication (mutual TLS). Alternatively, the workloads can use a JWT based authentication mechanism to authenticate on another. Workload three can use the authenticated identity of workload 1 to determine which APIs workload 1 is authorized 2 and to associated the authenticated identity with logs and other audit information.

* (4) API request to workload 2

Similarly to the previous flow, the gateway may determine that for another API call, the application client's request needs to be handled by workload 2. The case behaves the same as the previous flow except that the gateway may need to authenticate workload 2 before forwarding traffic to it. Workload 3 will then authorize and audit the request based on the authenticated identity of workload 2. Workload 2 and workload 1 may be authorized to use different APIs on workload 3. If workload 1 or 2 makes an API request that it is not authorized for, then workload 3 will reject the request.

### Context and workload Identity

~~~aasvg
+----------------------------------------------+
| |
| +----------------+ |
+--+--+ | | |
| +------------------>| Context | |
| | (3) | | |
| |<------------------+ Service | |
| | (c) | | |
| G | +----------------+ |
| a | |
(1) | t | |
+-------+ | e | +------------+ +-------------+ |
| App | (2) | w | (4) | | (5) | | |
| Client+---->| a +----->| workload 1 +----->| workload 2 | |
+-------+ (a) | y | (c) | | (c) | | |
| | +------------+ +-------------+ |
| S | |
| e | |
| r | |
| v | |
| i | |
| c | |
| e | |
| | |
+--+--+ |
| |
| |
| Internal Trust Domain |
jsalowey marked this conversation as resolved.
Show resolved Hide resolved
+----------------------------------------------+

~~~~
{: #arch-context title="Context example workload application system."}

In many cases the application system uses other security context information about the request during authorization and auditing. The following is a basic scenario that illustrates the propagation of security context in the workload system.
Some of the components and interactions have been removed from the previous scenario for simplicity.

* Context Service
This scenario adds a context service component which is responsible for creating security context based on authentication and other calculations. Context can be represented in many ways; it can be a plaintext data structure, a signed data structure such as a jwt or a pointer used to lookup the context as a data structure stored somewhere else. In one common example, creating the context may involve a token exchange converting an OAuth 2.0 access token into a different token format, such as a transaction token, that is understood by internal services.

* (1) Initial Authentication
In the initial authentication the gateway service obtains credentials it can use with the gateway service. This authentication may involve several steps and may be performed by an external entity such as an identity provider. The authentication process will result in a credential that the gateway service can evaluate. For example, the credential could be an OAuth Access token.
If the client already has an access token that it can use to authenticate to the gateway, such as an X.509 certificate, then it may skip this step.

* (2) Application Client Request
The application client makes a request to the gateway over HTTPS. The client may be authenticated to the gateway through TLS client authentication (mutual TLS) or through a credential such as an access token obtained in step 1.

* (3) Establishing the request context
The gateway service requests a security context token (c) from a token service. This process may entail sending an access token (a) along with other information to a token exchange endpoint to obtain the context token, which contains information about the entity accessing the system. This context is typically only relevant to the internal system and is not returned to the client.
The gateway may use alternative mechanisms to get the internal security context information (c).

* (4) Forwarding Request to Workload
The gateway forwards the request along with the context information (c) to the appropriate workload. A bearer token, such as an access token (a), is not usually forwarded as it is only meant for external access. The workload uses information in the context token in applying authorization policy to the application client's request.
If the workload does not receive a context token, then it will deny requests that rely on information from the token.

* (5) Making Additional Workload Originated Requests
The workload may need to make requests of other workloads. When making these requests, the workload includes the context information so Workload 2 can authorize and audit the request. Workload 2 may have a policy requiring Workload 1 to authenticate its service identity and provide valid context information (c) to access certain APIs.


### Cross-Domain Communication
~~~aasvg
+----------------------------------------------+
| |
+--+--+ |
| | |
| G | |
| a | |
| t | |
+-------+ | e | +------------+ +-------------+ |
| App | (1) | w | (2) | | (4) | | |
| Client+---->| a +----->| workload 1 +----->| workload 2 | |
+-------+ (a) | y | (c) | | (c) | | |
| | +-+---------++ ++--------+---+ |
| S | | | | |
| e | (3)| (5)|(c) | |
| r | | | | |
| v | | +-+--------++ | |
| i | | | Token | | |
| c | | | | (6)|(t) |
| e | | | Service | | |
| | | +-----------+ | |
+--+--+ | | |
| | | |
| | | |
| | Internal Trust|Domain|
jsalowey marked this conversation as resolved.
Show resolved Hide resolved
+-----------+---------------------------+------+
| |
| |
| |
| |
| |
+-------v--------+ +------------v--+
| Infrastructure | | External |
| | | |
| Service | | Service |
+----------------+ +---------------+

~~~~
{: #arch-cross title="External request workload application system."}

In many applications workloads must make requests of infrastructure that operates as a different trust domain or external services that are in a separate trust domain. Figure {{arch-cross}} shows this scenario. The scenario shows some new components described below.
Components and interactions from previous scenarios are still relevant to this example, but are omitted for simplicity.

* Token Service - the token service is responsible for exchanging information that is internal to the system such as service identity and/or security context information for a token that can be presented to an external service to gain access to infrastructure or an external service. Note that in some cases the token service may reside in the external trust domain or there may be token services in both the internal trust domain and the external trust domain. In some cases the workload will need to contact both the internal token service and an external token service in order to gain access to infrastructure or external service.
jsalowey marked this conversation as resolved.
Show resolved Hide resolved

* Infrastructure Service - this service is often part of the application, but it is managed by an infrastructure provider and may require different information to access it.

* External Service - this service is distinct from the application and hosted in a separate trust domain. This trust domain often has different access requirements that workloads in the internal trust domain.

Some example interactions in this scenario:

* (1) The application client is making requests with authentication information as in the other scenarios

* (2) The gateway forwards the request to the appropriate workload with the security context information

* (3) The workload needs to access an infrastructure service and, because it is managed by the same organization, it authenticates to the service directly using its workload credentials.

* (4) Workload 1 contacts Workload 2 to perform an operation. This request is accompanied by a security context as in the other scenarios.

* (5) Workload 2 determines it needs to communicate with an external service. In order to gain access to this service it must first obtain a token/credential (t) that it can use externally. It authenticates to the token service using its workload identity and provides security context information. The token service determines what type of externally usable token to issue to the workload.

* (6) Workload 2 uses this new token/credential (t) to access the external service.

* Note that in (3) and (6) the workload may need to authenticate to an external token service to obtain an access token to access the system in the foreign trust domain.


## Workload Identity Use Cases

### Bootstrapping Workload Identity

[TODO: this section will need to be updated to discuss workload identifier as a concept as well]
Expand Down Expand Up @@ -165,8 +379,6 @@ How the workload obtains its identity credentials and interacts with the agent i
* Local API - the identity credential is provided through an API, such as a local domain socket (for example SPIFFE or QEMU guest agent) or network API (for example Cloud Provider Metadata Server).
* Environment Variables - identity credential may also be injected into workloads using operating system environment variables.

## Workload Identity Use Cases

### Service Authentication

One of the most basic use cases for workload identity is authentication of one workload to another, such as in the case where one service is making a request to another service as part of a larger, more complex application. Following authentication, the request to the service offered by the workload needs to be authorized. Even in this simple case the identity of a workload is often composed of many attributes such as:
Expand Down
Loading