From b08d9cdcbdcae3fe505ba5ff2c60f2a88803db0e Mon Sep 17 00:00:00 2001 From: ID Bot Date: Fri, 18 Oct 2024 14:16:42 +0000 Subject: [PATCH] Script updating gh-pages from f2a01f1. [ci skip] --- ...nt-assertion-in-workload-environments.html | 941 ++++++++++-------- ...ent-assertion-in-workload-environments.txt | 360 ++++--- 2 files changed, 737 insertions(+), 564 deletions(-) diff --git a/arndt/move_to_informational/draft-ietf-wimse-client-assertion-in-workload-environments.html b/arndt/move_to_informational/draft-ietf-wimse-client-assertion-in-workload-environments.html index a1509e0..5d0d361 100644 --- a/arndt/move_to_informational/draft-ietf-wimse-client-assertion-in-workload-environments.html +++ b/arndt/move_to_informational/draft-ietf-wimse-client-assertion-in-workload-environments.html @@ -1138,44 +1138,55 @@

Workloads often require access to external resources to perform their tasks. For example, access to a database, a web server or another workload. These resources are protected by an authorization server and can only be accessed with an access token. The challenge for workloads is to get this access token issued.

Traditionally, workloads can be provisioned with client secrets credentials and use the client_credential flow to retrieve an access token. This model comes with a set of challenges that make it insecure and high-maintaince. Client secrets need to be manually provisioned and rotated. They can be stolen and used by attackers to impersonate the workload.

-

A solution to this problem is to not provision secret material to the workload itself but use the workload platform to attest for that workload. Many workload platforms offer a credential, in most cases a JWT token. Signed by a platform-internal authorization server, this credential attests the workload and its attributes. Based on [RFC7521] and its JWT profile [RFC7523], this credential can then be used as a client assertion towards a different authorization server. Figure 1 illustrates this interaction.

-
-
-
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - External - Authorization - Domain - Authorization - Server - Protected - Resource - 2) - present - assertion - 3) - access - Workload - Platform - Credential - Workload - issued - by - 1) - get - Platform - - -
-
-
Figure 1: -OAuth2 Assertion Flow in generic Workload Environment -
-
-

The figure outlines the following steps which are applicable in any pattern.

- -

This specifiation defines this flow in more detail based on common pattern seen in the industry and gives reccomendations.

+

A solution to this problem is to not provision secret material to the workload itself but use the workload platform to attest for that workload. Many workload platforms offer a credential, in most cases a JWT token. Signed by a platform-internal authorization server, this credential attests the workload and its attributes. Based on [RFC7521] and its JWT profile [RFC7523], this credential can then be used as a client assertion towards a different authorization server.

@@ -1289,98 +1215,249 @@

The terms 'workload' and 'container' are used interchangeably.

-
+
-

-3. Patterns +

+3. OAuth Assertion in Workload Environments

-
+
-

-3.1. Kubernetes +

+3.1. Overview

-

In Kubernetes, the primary concept of machine identity is implemented through "service accounts" [KubernetesServiceAccount]. These accounts can be explicitly created or a default one is automatically assigned. Service accounts utilize JSON Web Tokens (JWTs) [RFC7519] as their credential format, with these tokens being cryptographically signed by the Kubernetes Control Plane.

-

Service accounts serve multiple authentication purposes within the Kubernetes ecosystem. They are used to authenticate to Kubernetes APIs, between different workloads and to access external resources (which is particularly relevant to the scope of this document).

-

To programatically use service accounts, workloads can:

+

Figure 1 illustrates a generic pattern that applies across all of the patterns described in Section 4:

+
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + External + Authorization + Domain + Authorization + Server + Protected + Resource + 3) + access + token + 4) + access + 2) + present + assertion + Workload + Platform + Credential + Workload + issued + by + 1) + get + Platform + + +
+
+
Figure 1: +OAuth2 Assertion Flow in generic Workload Environment +
+
+

The figure outlines the following steps which are applicable in any pattern.

  • -

    use the Token Request API [TokenReviewV1] of the control plane

    +

    1) retrieve credential issued by platform. The way this is acchieved and whether this is workload or platform initiated differs based on the platform.

  • -

    have the token projected into the file system of the workload. This is commonly referred to as "projected service accout token".

    +

    2) present credential as an assertion towards an authorization server in an external authorization domain. This step uses the assertion_grant flow defined in [RFC7521] and, in case of JWT format, [RFC7523].

    +
    • +
  • +

    3) On success, an access token is returned to the workload to access the protected resource.

    +
    • +
  • +

    4) The aaccess token is used to access the protected resource in the external authorization domain.

-

Both options allow workloads to:

+

Accessing different protected resources may require steps 2) to 4) again with different scope parameters. Accessing a protected resource in an entirely different authorization domain often requires the entire flow to be followed again, to retrieve a new platform-issued credential with an audience for the other authorization server. This, however, differs based on the platform and implementation.

+
+
+
+
+

+3.2. Credential format +

+

For the scope of this document we focus on JSON Web Token credential formats. Other formats such as X.509 certificates are possible but not as widely seen as JSON Web Tokens.

+

The claims in the present assertion vary greatly based on use case and actual platform, but a minimum set of claims are seen across all of them. [RFC7523] describes them in detail and according to it, all MUST be present.

+
+
+{
+  "iss": "https://example.org",
+  "sub": "my-workload",
+  "aud": "custom-audience",
+  "exp": 1729248124
+}
+
+
+

For the scope of this specification, the claims can be described the following. Everything from [RFC7523] applies.

+
+
iss
+
+

The issuer of the workload platform. While this can have any format, it is important to highlight that many authorization servers leverage OpenID Connect [OIDC] and/or OAuth 2.0 Authorization Server Metadata [RFC8414] to retrieve JSON Web Keys [RFC7517] for validation purposes.

+
+
+
sub
+
+

Subject which identifies the workload within the domain/workload platform instance.

+
+
+
audience
+
+

One or many audiences the platform issued credential is eligable for. This is crucial when presenting the credential as an assertion towards the external authorization server which MUST identify itself as an audience present in the assertion.

+
+
+
+
+
+
+
+
+
+

+4. Patterns +

+
+
+

+4.1. Kubernetes +

+

In Kubernetes, the primary concept of machine identity is implemented through "service accounts" [KubernetesServiceAccount]. These accounts can be explicitly created or a default one is automatically assigned. Service accounts utilize JSON Web Tokens (JWTs) [RFC7519] as their credential format, with these tokens being cryptographically signed by the Kubernetes Control Plane.

+

Service accounts serve multiple authentication purposes within the Kubernetes ecosystem. They are used to authenticate to Kubernetes APIs, between different workloads and to access external resources (which is particularly relevant to the scope of this document).

+

To programatically use service accounts, workloads can:

+
    +
  • +

    use the Token Request API [TokenReviewV1] of the control plane

    +
    • +
  • +

    have the token projected into the file system of the workload. This is commonly referred to as "projected service accout token".

    +
    • +
+

Both options allow workloads to:

    -
  • -

    specify a custom audience. Possible audiences can be restricted based on policy.

    +
  • +

    specify a custom audience. Possible audiences can be restricted based on policy.

    • -
  • -

    specify a custom lifetime. Maximum lifetime can be restricted by policy.

    +
  • +

    specify a custom lifetime. Maximum lifetime can be restricted by policy.

    • -
  • -

    bind the token lifetime to an object lifecycle. This allows the token to be invalidated when the object is deleted. For example, when a Kubernetes Deployment is removed from the server. It is important to highlight, that invalidation is only in effect if the Token Review API [TokenReviewV1] of Kubernetes is used to validate the token.

    +
  • +

    bind the token lifetime to an object lifecycle. This allows the token to be invalidated when the object is deleted. For example, when a Kubernetes Deployment is removed from the server. It is important to highlight, that invalidation is only in effect if the Token Review API [TokenReviewV1] of Kubernetes is used to validate the token.

-

To validate service account tokens, Kubernetes offers workloads to:

+

To validate service account tokens, Kubernetes offers workloads to:

    -
  • -

    make us of the Token Review API [TokenReviewV1]. This API introspects the token, makes sure it hasn't been invalidated and returns the claims.

    +
  • +

    make us of the Token Review API [TokenReviewV1]. This API introspects the token, makes sure it hasn't been invalidated and returns the claims.

    • -
  • -

    mount the public keys used to sign the tokens into the file system of the workload. This allows workloads to decentrally validate the tokens signature.

    +
  • +

    mount the public keys used to sign the tokens into the file system of the workload. This allows workloads to decentrally validate the tokens signature.

    • -
  • -

    Optionally, a JSON Web Key Set [RFC7517] is exposed via a webserver. This allows the Service Account Token to be validated outside of the cluster and without line of sight towards the actual Kubernetes Control Plane API.

    +
  • +

    Optionally, a JSON Web Key Set [RFC7517] is exposed via a webserver. This allows the Service Account Token to be validated outside of the cluster and without line of sight towards the actual Kubernetes Control Plane API.

-
-
- +
+
+ - + - - - - - - - - + + + + + + + + + + - + - + - - + + - + - - + + - - - - - - - - - + + + + + + + + + + - - - + + + + External Authorization @@ -1389,51 +1466,57 @@

Server Protected Resource - 3) - present - assertion - 4) + 3) + present + assertion + 5) access - Kubernetes - Cluster - Workload - 1) - schedule - 2) - project - service - account - token - Kubernetes - Control - Plane + 4) + access + token + Kubernetes + Cluster + Workload + 1) + schedule + 2) + project + service + account + token + Kubernetes + Control + Plane - +

Figure 2: OAuth2 Assertion Flow in a Kubernetes Workload Environment
-

The steps shown in Figure 2 are:

+

The steps shown in Figure 2 are:

    -
  • -

    1) The Kubernetes Control Plane schedules the workload. This is much simplified and technically happens asynchronously.

    +
  • +

    1) The Kubernetes Control Plane schedules the workload. This is much simplified and technically happens asynchronously.

    +
    • +
  • +

    2) The Kubernetes Control Plane projects the service account token into the workload. This step is also much simplified and technically happens alongside the scheduling with step 1.

    • -
  • -

    2) The Kubernetes Control Plane projects the service account token into the workload. This step is also much simplified and technically happens alongside the scheduling with step 1.

    +
  • +

    3) Workloads present the project service account token as a client assertion towards an external authorization server according to [RFC7523].

    • -
  • -

    3) Workloads present the project service account token as a client assertion towards an external authorization server according to [RFC7523]. An access token is returned to the workload as a result.

    +
  • +

    4) On success, an access token is returned to the workload to access the protected resource.

    • -
  • -

    4) The access token issued by the external authorization server is used by the workload to access the projected resource.

    +
  • +

    5) The access token is used to access the protected resource in the external authorization domain.

-

As an example, the following JSON showcases the claims a Kubernetes Service Account token carries.

+

As an example, the following JSON showcases the claims a Kubernetes Service Account token carries.

-
+ 
 {
   "aud": [  # matches the requested audiences, or the API server's default audiences when none are explicitly requested
@@ -1471,57 +1554,60 @@
-
+

-3.2. Secure Production Identity Framework For Everyone (SPIFFE) +4.2. Secure Production Identity Framework For Everyone (SPIFFE)

-

Secure Production Identity Framework For Everyone, also known as SPIFFE, is a cloud native compute foundation (CNCF) adopted project which defines an API definitioned called "Workload API" to delivery machine identity to workloads. Workloads can retrieve either X509 based or JWT credentials without the need to authenticate making it very easy to use. How workloads authenticate on the API is not part of the specification. It is common to use platform metadata from the operating system and the workload platform for authentication on the Workload API.

-

For the scope of this document, the JWT formatted credential is the most relevant one. SPIFFE referres to it as "JWT-SVID" (JWT - Single Verifyable Identity Document).

-

Workloads are required to specify at least one audience when requesting a JWT-SVID from the Workload API.

-

To allow validation, SPIFFE offers

+

Secure Production Identity Framework For Everyone, also known as SPIFFE, is a cloud native compute foundation (CNCF) adopted project which defines an API definitioned called "Workload API" to delivery machine identity to workloads. Workloads can retrieve either X509 based or JWT credentials without the need to authenticate making it very easy to use. How workloads authenticate on the API is not part of the specification. It is common to use platform metadata from the operating system and the workload platform for authentication on the Workload API.

+

For the scope of this document, the JWT formatted credential is the most relevant one. SPIFFE referres to it as "JWT-SVID" (JWT - Single Verifyable Identity Document).

+

Workloads are required to specify at least one audience when requesting a JWT-SVID from the Workload API.

+

To allow validation, SPIFFE offers

    -
  • -

    to download a set JWK encoded public keys that can be used to validate JWT signatures. In SPIFFE this is referred to as the "JWT trust bundle".

    +
  • +

    to download a set JWK encoded public keys that can be used to validate JWT signatures. In SPIFFE this is referred to as the "JWT trust bundle".

    • -
  • -

    invoke a validation method on the Workload API to validate JWT-SVIDs

    +
  • +

    invoke a validation method on the Workload API to validate JWT-SVIDs

-

Additionally, many SPIFFE deployments choose to separately publish the signing keys as a JSON Web Key Set on a web server to allow validation where the Workload API is not available.

-

The following figure illustrates how a workload can use its JWT-SVID to access a protected resource outside of SPIFFE.

+

Additionally, many SPIFFE deployments choose to separately publish the signing keys as a JSON Web Key Set on a web server to allow validation where the Workload API is not available.

+

The following figure illustrates how a workload can use its JWT-SVID to access a protected resource outside of SPIFFE.

-
-
+
+
- - + + - - + + + + - - + + - - + + - - + + - - - + + + + @@ -1529,7 +1615,8 @@

- + + External Authorization @@ -1538,13 +1625,16 @@

Server Protected Resource - 2) - present - assertion - 3) - access - Workload - Platform + 2) + present + assertion + 4) + access + 3) + access + token + Workload + Platform Workload 1) get @@ -1553,287 +1643,310 @@

Workload API - +

Figure 4: OAuth2 Assertion Flow in a SPIFFE Environment
-

The steps shown in Figure 4 are:

+

The steps shown in Figure 4 are:

    -
  • -

    1) The workload retrieves JWT-SVID from the SPIFFE Workload API.

    +
  • +

    1) The workload request a JWT-SVID from the SPIFFE Workload API with an audience that identifies the external authorization server.

    +
    • +
  • +

    2) The workload presents the JWT-SVID as a client assertion in the assertion flow based on [RFC7523].

    • -
  • -

    2) The workload presents the JWT-SVID as a client assertion in the assertion flow based on [RFC7523]. An access token is returned to the workload.

    +
  • +

    3) On success, an access token is returned to the workload to access the protected resource.

    • -
  • -

    3) The access token returned in the previous step is used by the workload to access a protected resource.

    +
  • +

    4) The access token is used to access the protected resource in the external authorization domain.

-

The claims of a JWT-SVID for example looks like this.

-
-
+
The claims of a JWT-SVID for example looks like this.
+~~~json
 {
   "aud": [
-    "my-audience"
+    "external-authorization-server"
   ],
   "exp": 1729087175,
   "iat": 1729086875,
   "sub": "spiffe://example.org/myservice"
 }
-
-
+~~~

+

TODO: write about "iss" in JWT-SVID.

-
+

-3.3. Cloud Providers +4.3. Cloud Providers

-

Workload in cloud platforms can have any shape or form. Historically, virtual machines were the most common, with the introduction of containerization, hosted container environment or Kubernetes clusters were introduced, and lately, serverless functions are offered. Regardless of the actual workload packaging, distribution and runtime platform, all are in need of identity.

-

To create a common identity interface across cloud services and offerings, the pattern of an Instance Metadata Endpoint has been established by the biggest cloud providers. Next to the option for workloads to get metadata about themselves, it also allows them to receive identity. The credential types offered can vary. JWT, however, is the one that is common across all of them. The issued credential allows proof to anyone it is being presented to, that the workload platform has attested the workload and it can be considered authenticated.

-

Within a cloud provider the issued credential can often directly be used to access resources of any kind across the platform making integration between the services easy and credential less. While the term is technically missleading, from a user perspective, no credential needs to be issued, provisioned, rotated or revoked, as everything is handled internally by the platform.

-

Resources outside of the platform, for example resources or workloads in other clouds, generic web servers or on-premise resources, are most of the time, however, protected by different domains and authorization servers and deny the platform issued credential. In this scenario, the pattern of using the platform issued credential as an assertion in the context of [RFC7521], for JWT particularly [RFC7523] towards the authorization server that protected the resource to get an access token.

+

Workload in cloud platforms can have any shape or form. Historically, virtual machines were the most common, with the introduction of containerization, hosted container environment or Kubernetes clusters were introduced, and lately, serverless functions are offered. Regardless of the actual workload packaging, distribution and runtime platform, all are in need of identity.

+

To create a common identity interface across cloud services and offerings, the pattern of an Instance Metadata Endpoint has been established by the biggest cloud providers. Next to the option for workloads to get metadata about themselves, it also allows them to receive identity. The credential types offered can vary. JWT, however, is the one that is common across all of them. The issued credential allows proof to anyone it is being presented to, that the workload platform has attested the workload and it can be considered authenticated.

+

Within a cloud provider the issued credential can often directly be used to access resources of any kind across the platform making integration between the services easy and credential less. While the term is technically missleading, from a user perspective, no credential needs to be issued, provisioned, rotated or revoked, as everything is handled internally by the platform.

+

Resources outside of the platform, for example resources or workloads in other clouds, generic web servers or on-premise resources, are most of the time, however, protected by different domains and authorization servers and deny the platform issued credential. In this scenario, the pattern of using the platform issued credential as an assertion in the context of [RFC7521], for JWT particularly [RFC7523] towards the authorization server that protected the resource to get an access token.

-
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - External - Authorization - Domain - Authorization - Server - Protected - Resource - B1) - present - assertion - B2) - access - Cloud - 1) - get - identity - Workload - Instance - Metadata - A1) - access - Service/ - Endpoint - Protected - Resource + External + Authorization + Domain + Authorization + Server + Protected + Resource + B1) + present + as + assertion + B3) + access + B2) + access + token + Cloud + 1) + get + identity + Workload + Instance + Metadata + A1) + access + Service/ + Endpoint + Protected + Resource - +
Figure 5: OAuth2 Assertion Flow in a cloud environment
-

The steps shown in Figure 5 are:

+

The steps shown in Figure 5 are:

    -
  • -

    1) The workload retrieves identity from the Instance Metadata Endpoint.

    +
  • +

    1) The workload retrieves identity from the Instance Metadata Endpoint.

-

In case the workload needs to access a resource within the cloud (protected by the same authorization server that issued the workload identity)

+

In case the workload needs to access a resource within the cloud (protected by the same authorization server that issued the workload identity)

    -
  • -

    A1) The workload directly access the protected resource with the credential issued in step 1.

    +
  • +

    A1) The workload directly access the protected resource with the credential issued in step 1.

-

In case the workload needs to access a resource outside of the cloud (protected by a different authorization server). This can also be the same cloud but different context (tenant, account).

+

In case the workload needs to access a resource outside of the cloud (protected by a different authorization server). This can also be the same cloud but different context (tenant, account).

    -
  • -

    B1) The workload presents cloud-issued credential as an assertion towards the external authorization server using [RFC7523]. An access token is returned to the workload.

    +
  • +

    B1) The workload presents cloud-issued credential as an assertion towards the external authorization server using [RFC7523].

    +
    • +
  • +

    B2) On success, an access token is returned to the workload to access the protected resource.

    • -
  • -

    B2) Using the access token from step B1, the workload is able to access the protected resource in the external authorization domain.

    +
  • +

    B3) Using the access token, the workload is able to access the protected resource in the external authorization domain.

-
+

-3.4. Continues integration/deployment systems +4.4. Continues integration/deployment systems

-

Continous integration and deployment systems allow their pipelines/workflows to receive identity every time they run. Particularly in situations where build outputs need to be uploaded to resources protected by other authorization server, deployments need to be made, or more generally, protected resources to be accessed, [RFC7523] is used to federate the pipeline/workflow identity to an identity of the other authorization server.

+

Continous integration and deployment systems allow their pipelines/workflows to receive identity every time they run. Particularly in situations where build outputs need to be uploaded to resources protected by other authorization server, deployments need to be made, or more generally, protected resources to be accessed, [RFC7523] is used to federate the pipeline/workflow identity to an identity of the other authorization server.

-
-
- - - - - - +
+
+ + + + + - - - - - + + + + + + + - - - - - - + + + + + + + - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + External Authorization Domain - Authorization - Server - Protected - Resource - 3) - present - assertion - 4) - access - Task - (Workload) - 1)schedules - 2)retrieve - identity - Continuous - Integration - / - Deployment - Platform + Authorization + Server + Protected + Resource + 3) + present + assertion + 4) + access + 4) + access + token + Task + (Workload) + 1)schedules + 2)retrieve + identity + Continuous + Integration + / + Deployment + Platform - +
Figure 6: OAuth2 Assertion Flow in a continous integration/deployment environment
-

The steps shown in Figure 6 are:

+

The steps shown in Figure 6 are:

    -
  • -

    1) The continuous integration / deployment platform (CI-CD platform) schedules a task (considered a workload) to be performed.

    +
  • +

    1) The continuous integration / deployment platform (CI-CD platform) schedules a task (considered a workload) to be performed.

    +
    • +
  • +

    2) The workload is able to retrieve identity from the CI-CD platform. This can differ based on the platform and potentially is already supplied during scheduling phase in step 1.

    • -
  • -

    2) The workload is able to retrieve identity from the CI-CD platform. This can differ based on the platform and potentially is already supplied during scheduling phase in step 1.

    +
  • +

    3) The workload presents the CI-CD issued credential as an assertion towards the authorization server in the external authorization domain based on [RFC7521]. In case of JWT also [RFC7523].

    • -
  • -

    3) The workload presents the CI-CD issued credential as an assertion towards the authorization server in the external authorization domain based on [RFC7521]. In case of JWT also [RFC7523]. The authorization server returns an access token to the workload.

    +
  • +

    4) On success, an access token is returned to the workload to access the protected resource.

    • -
  • -

    4) Using the access token from step 3, the workload is able to access the protected resource in the external authorization domain.

    +
  • +

    5) Using the access token, the workload is able to access the protected resource in the external authorization domain.

-

Tokens of different providers look different, but all of them contain claims carrying the basic context of the executed tasks such as source code management data (e.g. git branch), initiation and more.

+

Tokens of different providers look different, but all of them contain claims carrying the basic context of the executed tasks such as source code management data (e.g. git branch), initiation and more.

-
+

-4. Security Considerations +5. Security Considerations

-

This entire document is about security.

+

This entire document is about security.

-
+

-5. IANA Considerations +6. IANA Considerations

-

This document does not require actions by IANA.

+

This document does not require actions by IANA.

-
+

-6. Acknowledgements +7. Acknowledgements

-

Add your name here.

+

Add your name here.

-
+

-7. References +8. References

-
+

-7.1. Normative References +8.1. Normative References

[RFC2119]
@@ -1872,9 +1985,9 @@

-
+

-7.2. Informative References +8.2. Informative References

[KubernetesServiceAccount]
diff --git a/arndt/move_to_informational/draft-ietf-wimse-client-assertion-in-workload-environments.txt b/arndt/move_to_informational/draft-ietf-wimse-client-assertion-in-workload-environments.txt index 712a527..5b5560c 100644 --- a/arndt/move_to_informational/draft-ietf-wimse-client-assertion-in-workload-environments.txt +++ b/arndt/move_to_informational/draft-ietf-wimse-client-assertion-in-workload-environments.txt @@ -67,17 +67,20 @@ Table of Contents 1. Introduction 2. Terminology - 3. Patterns - 3.1. Kubernetes - 3.2. Secure Production Identity Framework For Everyone (SPIFFE) - 3.3. Cloud Providers - 3.4. Continues integration/deployment systems - 4. Security Considerations - 5. IANA Considerations - 6. Acknowledgements - 7. References - 7.1. Normative References - 7.2. Informative References + 3. OAuth Assertion in Workload Environments + 3.1. Overview + 3.2. Credential format + 4. Patterns + 4.1. Kubernetes + 4.2. Secure Production Identity Framework For Everyone (SPIFFE) + 4.3. Cloud Providers + 4.4. Continues integration/deployment systems + 5. Security Considerations + 6. IANA Considerations + 7. Acknowledgements + 8. References + 8.1. Normative References + 8.2. Informative References Authors' Addresses 1. Introduction @@ -102,34 +105,48 @@ Table of Contents this credential attests the workload and its attributes. Based on [RFC7521] and its JWT profile [RFC7523], this credential can then be used as a client assertion towards a different authorization server. - Figure 1 illustrates this interaction. - +----------------------------------------------------------+ - | External Authorization Domain | - | | - | +-------------------------+ +--------------------+ | - | | | | | | - | | Authorization Server | | Protected Resource | | - | | | | | | - | +------------^------------+ +------------^-------+ | - | | | | - +--------------+-------------------------------+-----------+ - | | - 2) present assertion 3) access - | | - | +-------------------------+ - | | - +--------------+-----+-------------------------------------+ - | | | Workload Platform | - | | | | - | +-----------+-----+---+ +------------------+ | - | | | | Credential | | - | | Workload +-----------> issued by | | - | | | 1) get | Platform | | - | +---------------------+ +------------------+ | - | | - | | - +----------------------------------------------------------+ +2. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in BCP + 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + The terms 'workload' and 'container' are used interchangeably. + +3. OAuth Assertion in Workload Environments + +3.1. Overview + + Figure 1 illustrates a generic pattern that applies across all of the + patterns described in Section 4: + + +----------------------------------------------------------+ + | External Authorization Domain | + | | + | +-------------------------+ +--------------------+ | + | | | | | | + | | Authorization Server | | Protected Resource | | + | | | | | | + | +-------^---------+-------+ +----------^---------+ | + +---------+---------+------------------------+-------------+ + | | | + | 3) access token 4) access + | | | + 2) present assertion | | + | | +------------------+ + | | | + +---------+---------+-----+--------------------------------+ + | | | | Workload Platform | + | | | | | + | +------+---------v-----+---+ +-------------+ | + | | | | Credential | | + | | Workload +-----------> issued by | | + | | | 1) get | Platform | | + | +--------------------------+ +-------------+ | + +----------------------------------------------------------+ Figure 1: OAuth2 Assertion Flow in generic Workload Environment @@ -143,28 +160,63 @@ Table of Contents * 2) present credential as an assertion towards an authorization server in an external authorization domain. This step uses the assertion_grant flow defined in [RFC7521] and, in case of JWT - format, [RFC7523]. As a result of this flow, an access token is - returned to the workload. + format, [RFC7523]. - * 3) use access token from the previous step to access a protected - resource in the external authorization domain. + * 3) On success, an access token is returned to the workload to + access the protected resource. - This specifiation defines this flow in more detail based on common - pattern seen in the industry and gives reccomendations. + * 4) The aaccess token is used to access the protected resource in + the external authorization domain. -2. Terminology + Accessing different protected resources may require steps 2) to 4) + again with different scope parameters. Accessing a protected + resource in an entirely different authorization domain often requires + the entire flow to be followed again, to retrieve a new platform- + issued credential with an audience for the other authorization + server. This, however, differs based on the platform and + implementation. - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and - "OPTIONAL" in this document are to be interpreted as described in BCP - 14 [RFC2119] [RFC8174] when, and only when, they appear in all - capitals, as shown here. +3.2. Credential format - The terms 'workload' and 'container' are used interchangeably. + For the scope of this document we focus on JSON Web Token credential + formats. Other formats such as X.509 certificates are possible but + not as widely seen as JSON Web Tokens. + + The claims in the present assertion vary greatly based on use case + and actual platform, but a minimum set of claims are seen across all + of them. [RFC7523] describes them in detail and according to it, all + MUST be present. + + { + "iss": "https://example.org", + "sub": "my-workload", + "aud": "custom-audience", + "exp": 1729248124 + } -3. Patterns + For the scope of this specification, the claims can be described the + following. Everything from [RFC7523] applies. -3.1. Kubernetes + iss + The issuer of the workload platform. While this can have any + format, it is important to highlight that many authorization + servers leverage OpenID Connect [OIDC] and/or OAuth 2.0 + Authorization Server Metadata [RFC8414] to retrieve JSON Web Keys + [RFC7517] for validation purposes. + + sub + Subject which identifies the workload within the domain/workload + platform instance. + + audience + One or many audiences the platform issued credential is eligable + for. This is crucial when presenting the credential as an + assertion towards the external authorization server which MUST + identify itself as an audience present in the assertion. + +4. Patterns + +4.1. Kubernetes In Kubernetes, the primary concept of machine identity is implemented through "service accounts" [KubernetesServiceAccount]. These @@ -222,16 +274,18 @@ Table of Contents | | | | | | | | Authorization Server | | Protected Resource | | | | | | | | - | +------------^-------------+ +----------^---------+ | - | | | | - +--------------+--------------------------+-------------+ - | | - 3) present assertion 4) access - | | - +--------------+--------------------------+-------------+ - | | +------------+ Kubernetes | - | | | Cluster | - | +---------+-------------+----+ | + | +------^-------------+-----+ +----------^---------+ | + | | | | | + +--------+-------------+------------------+-------------+ + | | | + 3) present assertion | 5) access + | | | + | 4) access token | + | | | + +--------+-------------+------------------+-------------+ + | | | +------------+ Kubernetes | + | | | | Cluster | + | +---+-------------v-----+----+ | | | | | | | Workload | | | | | | @@ -262,11 +316,13 @@ Table of Contents * 3) Workloads present the project service account token as a client assertion towards an external authorization server according to - [RFC7523]. An access token is returned to the workload as a - result. + [RFC7523]. + + * 4) On success, an access token is returned to the workload to + access the protected resource. - * 4) The access token issued by the external authorization server is - used by the workload to access the projected resource. + * 5) The access token is used to access the protected resource in + the external authorization domain. As an example, the following JSON showcases the claims a Kubernetes Service Account token carries. @@ -301,7 +357,7 @@ Table of Contents Figure 3: Example Kubernetes Service Account Token claims -3.2. Secure Production Identity Framework For Everyone (SPIFFE) +4.2. Secure Production Identity Framework For Everyone (SPIFFE) Secure Production Identity Framework For Everyone, also known as SPIFFE, is a cloud native compute foundation (CNCF) adopted project @@ -342,16 +398,16 @@ Table of Contents | | | | | | | | Authorization Server | | Protected Resource | | | | | | | | - | +----------^------------+ +--------^-------------+ | - | | | | - +--------------+-------------------------+----------------+ - | | - 2) present assertion 3) access - | | - +--------------+-------------------------+----------------+ - | | | Workload | - | +-----------+-------------------------+----+ Platform | - | | | | + | +-----^-----------------+ +--------^-------------+ | + +---------+------------+-----------------+----------------+ + | | | + 2) present assertion | 4) access + | | | + | 3) access token | + | | | + +---------+------------+-----------------+----------------+ + | +------+------------v-----------------+----+ Workload | + | | | Platform | | | Workload | | | | | | | +---------------------+--------------------+ | @@ -369,27 +425,26 @@ Table of Contents The steps shown in Figure 4 are: - * 1) The workload retrieves JWT-SVID from the SPIFFE Workload API. + * 1) The workload request a JWT-SVID from the SPIFFE Workload API + with an audience that identifies the external authorization + server. * 2) The workload presents the JWT-SVID as a client assertion in the - assertion flow based on [RFC7523]. An access token is returned to - the workload. + assertion flow based on [RFC7523]. - * 3) The access token returned in the previous step is used by the - workload to access a protected resource. + * 3) On success, an access token is returned to the workload to + access the protected resource. - The claims of a JWT-SVID for example looks like this. + * 4) The access token is used to access the protected resource in + the external authorization domain. - { - "aud": [ - "my-audience" - ], - "exp": 1729087175, - "iat": 1729086875, - "sub": "spiffe://example.org/myservice" - } + The claims of a JWT-SVID for example looks like this. ~~~json { + "aud": [ "external-authorization-server" ], "exp": 1729087175, "iat": + 1729086875, "sub": "spiffe://example.org/myservice" } ~~~ + + TODO: write about "iss" in JWT-SVID. -3.3. Cloud Providers +4.3. Cloud Providers Workload in cloud platforms can have any shape or form. Historically, virtual machines were the most common, with the @@ -424,38 +479,38 @@ Table of Contents [RFC7523] towards the authorization server that protected the resource to get an access token. - +---------------------------------------------------+ - | External Authorization Domain | - | | - | +----------------------+ +---------------------+ | - | | | | | | - | | Authorization Server | | Protected Resource | | - | | | | | | - | +-----------^----------+ +----------^----------+ | - | | | | - +-------------+------------------------+------------+ - | | - | | - B1) present assertion B2) access - | | - | +-------------------+ - +-------------+----+--------------------------------+ - | | | Cloud | - | | | | - | +---------+----+---+ 1) get +----------+ | - | | | identity | | | - | | Workload +---------------> Instance | | - | | | | | | - | +---------+--------+ | Metadata | | - | | | | | - | A1) access | Service/ | | - | | | Endpoint | | - | +---------v------------+ | | | - | | | +----------+ | - | | Protected Resource | | - | | | | - | +----------------------+ | - +---------------------------------------------------+ + +-----------------------------------------------------+ + | External Authorization Domain | + | | + | +------------------------+ +---------------------+ | + | | | | | | + | | Authorization Server | | Protected Resource | | + | | | | | | + | +------^------------+----+ +----------^----------+ | + | | | | | + +--------+------------+------------------+------------+ + | | | + B1) present as assertion | B3) access + | | | + | B2) access token | + | | +--------------+ + +--------+------------+---+------------------------------+ + | | | | Cloud | + | | | | | + | +----+------------v---+--+ 1) get +----------+ | + | | | identity | | | + | | Workload +--------------> Instance | | + | | | | | | + | +-----------+------------+ | Metadata | | + | | | | | + | A1) access | Service/ | | + | | | Endpoint | | + | +-----------v------------+ | | | + | | | +----------+ | + | | Protected Resource | | + | | | | + | +------------------------+ | + +--------------------------------------------------------+ Figure 5: OAuth2 Assertion Flow in a cloud environment @@ -476,14 +531,15 @@ Table of Contents the same cloud but different context (tenant, account). * B1) The workload presents cloud-issued credential as an assertion - towards the external authorization server using [RFC7523]. An - access token is returned to the workload. + towards the external authorization server using [RFC7523]. - * B2) Using the access token from step B1, the workload is able to - access the protected resource in the external authorization - domain. + * B2) On success, an access token is returned to the workload to + access the protected resource. -3.4. Continues integration/deployment systems + * B3) Using the access token, the workload is able to access the + protected resource in the external authorization domain. + +4.4. Continues integration/deployment systems Continous integration and deployment systems allow their pipelines/ workflows to receive identity every time they run. Particularly in @@ -495,19 +551,22 @@ Table of Contents +----------------------------------------------------------+ | External Authorization Domain | - | | | +--------------------------+ +---------------------+ | | | | | | | | | Authorization Server | | Protected Resource | | | | | | | | - | +-----------^--------------+ +------------^--------+ | - | | | | - +-------------+---------------------------------+----------+ - | | - 3) present assertion 4) access - | | - +-------------+---------------------------------+----------+ + | +-------^-------------+----+ +------------^--------+ | + | | | | | + +---------+-------------+-----------------------+----------+ + | | | + 3) present assertion | 4) access + | | | + | 4) access token | + | | | + +---------+-------------v-----------------------+----------+ + | | | Task (Workload) | + | | +--------^---------------------------+---------------------+ | | 1)schedules 2)retrieve identity @@ -534,32 +593,33 @@ Table of Contents * 3) The workload presents the CI-CD issued credential as an assertion towards the authorization server in the external authorization domain based on [RFC7521]. In case of JWT also - [RFC7523]. The authorization server returns an access token to - the workload. + [RFC7523]. + + * 4) On success, an access token is returned to the workload to + access the protected resource. - * 4) Using the access token from step 3, the workload is able to - access the protected resource in the external authorization - domain. + * 5) Using the access token, the workload is able to access the + protected resource in the external authorization domain. Tokens of different providers look different, but all of them contain claims carrying the basic context of the executed tasks such as source code management data (e.g. git branch), initiation and more. -4. Security Considerations +5. Security Considerations This entire document is about security. -5. IANA Considerations +6. IANA Considerations This document does not require actions by IANA. -6. Acknowledgements +7. Acknowledgements Add your name here. -7. References +8. References -7.1. Normative References +8.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, @@ -597,7 +657,7 @@ Table of Contents DOI 10.17487/RFC8414, June 2018, . -7.2. Informative References +8.2. Informative References [KubernetesServiceAccount] "Kubernetes Service Account", May 2024,