From 3752e2a099155f2268daaf86f30329fc60f1d71e Mon Sep 17 00:00:00 2001 From: Jim Marino Date: Tue, 5 Mar 2024 16:58:56 +0100 Subject: [PATCH 1/3] Add DR --- .../2024-03-05_token_refresh/README.md | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/development/decision-records/2024-03-05_token_refresh/README.md diff --git a/docs/development/decision-records/2024-03-05_token_refresh/README.md b/docs/development/decision-records/2024-03-05_token_refresh/README.md new file mode 100644 index 000000000..886c68941 --- /dev/null +++ b/docs/development/decision-records/2024-03-05_token_refresh/README.md @@ -0,0 +1,66 @@ +# Tractus-X Token Refresh + +## Decision + +Implement token refresh for the Tractus-X EDC Data Plane according to the [Tractus-X Refresh Token Grant Profile.]() +This enables provider data planes to implement refresh tokens in an interoperable way for client applications using the +Tractus-X EDC Connector. + +Note refresh token support will be done almost exclusively in Tractus-X EDC, except for a few minor updates to upstream +EDC. + +## Rationale + +Data providers may use short-lived tokens for HTTP client pull data transfers to enhance security. Refresh tokens allow +data access to be maintained using short-lived tokens without starting a new transfer process. + +## Approach + +The upstream EDC `DefaultDataPlaneAccessTokenServiceImpl` will be replaced to create a refresh token pinned to the +client's DID. This TX implementation will use the following upstream EDC enhancements: + +- An upstream EDC decorator that adds the client DID as an extension property to the signaling request. +- Upgrade the `AccessTokenData` type to allow for extensible properties to enable the `AccessTokenDataStore` to persist + the renewal token. + +Tractus-X EDC will implement token refresh based on +the [Trasctus-X Refresh Token Grant Profile](https://github.com/eclipse-tractusx/tractusx-profiles/blob/main/tx/refresh/refresh.token.grant.profile.md) + +### Provider Data Plane + +#### TX DataPlaneAccessTokenService + +An implementation of the `DataPlaneAccessTokenService` will be provided that overrides the +default `DefaultDataPlaneAccessTokenServiceImpl` implementation. The TX implementation will do the following: + +- Create an expiring access token and set the `expiresIn` attribute of the `DataAddress.` +- Create a refresh token that is returned in the `refreshToken` property of the `DataAddress`. +- Provide a configuration option to set the `refreshEndpoint` property of the `DataAddress.` If not set, + the `refreshEndpoint` property will not be included. + +It will be possible for distributions not to include the TX implementation of the `DataPlaneAccessTokenService` and +substitute another or revert to the EDC default implementation. + +The refresh token will be sender-constrained to the client DID passed as part of the `DataFlowStartMessage`. + +#### OAuth 2 Refresh API + +The provider data plane will be extended to add a public API that implements the OAuth2 `refresh_token` grant. The +refresh token will be verified according to the steps laid out in the _Tractus-X Refresh Token Grant Profile._ When a +refresh request is successfully made, a new access token and refresh token will be generated and returned to the client. +If a refresh token request fails due to a validation error, the associated access token and refresh token will be +invalidated. + +### Client-side Token Refresh + +A client will be able to initiate a token refresh request in three ways: + +- Request data through a client data plane instance, which will check the token expiration and issue a refresh request + if required. This behavior will be transparent to the client. +- Request data directly and check if the access token is expired. If the token is expired, the client can call a client + data plane management API to renew the access token. +- Request data directly and handle access token renewal using OAuth 2 directly. + +To support refresh token renewal, an DIM specific extension will be added that requests the authentication JWT to be +signed using a key managed by DIM. This extension can use the same DIM API as the IATP extension. + From 902e64e08c88fa3264f1a062f9a7340502b4bc30 Mon Sep 17 00:00:00 2001 From: Jim Marino Date: Tue, 5 Mar 2024 17:21:43 +0100 Subject: [PATCH 2/3] Update docs/development/decision-records/2024-03-05_token_refresh/README.md Co-authored-by: Paul Latzelsperger <43503240+paullatzelsperger@users.noreply.github.com> --- .../decision-records/2024-03-05_token_refresh/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/decision-records/2024-03-05_token_refresh/README.md b/docs/development/decision-records/2024-03-05_token_refresh/README.md index 886c68941..4a3209d79 100644 --- a/docs/development/decision-records/2024-03-05_token_refresh/README.md +++ b/docs/development/decision-records/2024-03-05_token_refresh/README.md @@ -2,7 +2,7 @@ ## Decision -Implement token refresh for the Tractus-X EDC Data Plane according to the [Tractus-X Refresh Token Grant Profile.]() +Implement token refresh for the Tractus-X EDC Data Plane according to the [Tractus-X Refresh Token Grant Profile](https://github.com/eclipse-tractusx/tractusx-profiles/blob/main/tx/refresh/refresh.token.grant.profile.md). This enables provider data planes to implement refresh tokens in an interoperable way for client applications using the Tractus-X EDC Connector. From aa31d57d3fac362bef40c958b4c4f80cf0fad542 Mon Sep 17 00:00:00 2001 From: Jim Marino Date: Tue, 5 Mar 2024 17:21:53 +0100 Subject: [PATCH 3/3] Update docs/development/decision-records/2024-03-05_token_refresh/README.md Co-authored-by: Paul Latzelsperger <43503240+paullatzelsperger@users.noreply.github.com> --- .../decision-records/2024-03-05_token_refresh/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/decision-records/2024-03-05_token_refresh/README.md b/docs/development/decision-records/2024-03-05_token_refresh/README.md index 4a3209d79..d3f13985f 100644 --- a/docs/development/decision-records/2024-03-05_token_refresh/README.md +++ b/docs/development/decision-records/2024-03-05_token_refresh/README.md @@ -61,6 +61,6 @@ A client will be able to initiate a token refresh request in three ways: data plane management API to renew the access token. - Request data directly and handle access token renewal using OAuth 2 directly. -To support refresh token renewal, an DIM specific extension will be added that requests the authentication JWT to be +To support refresh token renewal, a DIM specific extension will be added that requests the authentication JWT to be signed using a key managed by DIM. This extension can use the same DIM API as the IATP extension.