From 326fd9aacd41ec327e9cb8b24ab1f29506799c2e Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Fri, 8 Aug 2025 14:30:24 +0200 Subject: [PATCH 1/8] Update Authentication and authorization section --- documentation/CAMARA-API-Design-Guide.md | 38 ++++++++++++++++++++---- 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 58fd8c60..7ea00e39 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -63,7 +63,7 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH | **Header** | HTTP Headers allow client and server send additional information joined to the request or response. A request header is divided by name (No case sensitive) followed by a colon and the header value (without line breaks). White spaces on the left hand from the value are ignored. | | **HTTP** | Hypertext Transfer Protocol (HTTP) is a communication protocol that allows the information transfer using files (XHTML, HTML…) in World Wide Web. | | **JSON** | The JavaScript Object Notation (JSON) Data Interchange Format [RFC8259](https://datatracker.ietf.org/doc/html/rfc8259) | -| **JWT** | JSON Web Token (JWT) is an open standard based on JSON [RFC7519](https://datatracker.ietf.org/doc/html/rfc7519) | +| **JWT** | JSON Web Token (JWT) is an open standard based on JSON [RFC7519](https://datatracker.ietf.org/doc/html/rfc7519)
JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens [RFC9068](https://datatracker.ietf.org/doc/html/rfc9068) | | **Kebab-case** | Practice in the words denomination where the hyphen is used to separate words. | | **OAuth2** | Open Authorization is an open standard that allows simple Authorization flows to be used in websites or applications. [RFC6749](https://datatracker.ietf.org/doc/html/rfc6749) | | **OIDC** | [OpenId Connect](https://openid.net/specs/openid-connect-core-1_0.html) is standard based on OAuth2 that adds authentication and consent to OAuth2. | @@ -923,11 +923,36 @@ The following points can serve as a checklist to design the security mechanism o - With HTTP/2 or HTTP/3, performance improvements can be achieved due to better optimization and multiplexing of requests. - If HTTP 1.1 is used, usage of _TCP persistent connections_ is RECOMMENDED to achieve comparable performance. -2. **Authentication and authorization must be considered** - - CAMARA uses the authentication and authorization protocols and flows as described in the [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md).\ - -3. **Input parameter validation** +2. **Authentication and authorization** + + CAMARA follows the OAuth2 paradigm that separates authentication and authorization from API access. + + CAMARA uses the authentication and authorization protocols and flows as described in the released version of the [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/). + + All authentication and authorization decisions are bundled in an Authorization Server, which ensures that CAMARA access tokens are only then issued + to the API consumer, + - if the API consumer is registered through the onboarding process + - if the API consumer is using the authorization grant agreed upon during the onboarding process + - grant-type urn:openid:params:grant-type:ciba + - grant-type urn:ietf:params:oauth:grant-type:jwt-bearer + - grant-type authorization_code + - grant-type client_credentials + - if and after the User or API consumer sucessfully authenticated to the Authorization Server + - if the requested Purpose and scopes were agreed upon during the onboarding process + + This separation of concerns simplifies the implementation of the API endpoint that, after validating the access token, can now focus its API implementation. + The access token is created by the API provider's Authorization Server to be consumed by the API provider's API endpoint. + + As described in [Appendix A (Normative): `info.description` template for when User identification can be from either an access token or explicit identifier](#appendix-a-normative-infodescription-template-for-when-user-identification-can-be-from-either-an-access-token-or-explicit-identifier) a three-legged access token is associated with Personal Identifiable Information (PII). + + If the access token is self-contained then the three-legged access token contains PII and the confidentiality of that PII must be protected. + The confidentiallity of the PII in the self-contained access token can be achieved by the API provider's authorization server encrypting + the access token to the API Provider's API endpoint. + It is recommended that self-contained access tokens follow RFC 9068 JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens. + + Note: The alternative to self-contained tokens are opaque access tokens that are e.g. a reference into a database. Authorization Server also often offer token introspection endpoints. The choice of access token type have performance and privacy and security implications. + +4. **Input parameter validation** Validate the request parameters as the first step before they reach the application logic. Implement strong validation checks and immediately reject the request if validation fails. @@ -1282,3 +1307,4 @@ This approach simplifies API usage for API consumers using a three-legged access - If the subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. ``` + From e0ecdc750b790dc9a611feb36f65b8faa85bac79 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Mon, 11 Aug 2025 11:00:35 +0200 Subject: [PATCH 2/8] remove note because that is not an API design guide topic --- documentation/CAMARA-API-Design-Guide.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 7ea00e39..49958366 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -949,8 +949,6 @@ The following points can serve as a checklist to design the security mechanism o The confidentiallity of the PII in the self-contained access token can be achieved by the API provider's authorization server encrypting the access token to the API Provider's API endpoint. It is recommended that self-contained access tokens follow RFC 9068 JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens. - - Note: The alternative to self-contained tokens are opaque access tokens that are e.g. a reference into a database. Authorization Server also often offer token introspection endpoints. The choice of access token type have performance and privacy and security implications. 4. **Input parameter validation** @@ -1308,3 +1306,4 @@ This approach simplifies API usage for API consumers using a three-legged access - If the subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. ``` + From 5934bfbbccfb3aee4cc9db3814457bd81ba80359 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Mon, 11 Aug 2025 11:02:29 +0200 Subject: [PATCH 3/8] remove list of grants/flows --- documentation/CAMARA-API-Design-Guide.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 49958366..9ded7302 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -932,11 +932,7 @@ The following points can serve as a checklist to design the security mechanism o All authentication and authorization decisions are bundled in an Authorization Server, which ensures that CAMARA access tokens are only then issued to the API consumer, - if the API consumer is registered through the onboarding process - - if the API consumer is using the authorization grant agreed upon during the onboarding process - - grant-type urn:openid:params:grant-type:ciba - - grant-type urn:ietf:params:oauth:grant-type:jwt-bearer - - grant-type authorization_code - - grant-type client_credentials + - if the API consumer is using the authorization grant/flow agreed upon during the onboarding process - if and after the User or API consumer sucessfully authenticated to the Authorization Server - if the requested Purpose and scopes were agreed upon during the onboarding process @@ -1307,3 +1303,4 @@ This approach simplifies API usage for API consumers using a three-legged access ``` + From dae99c011828a19f575ac81c28825e454384c034 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Mon, 11 Aug 2025 11:03:06 +0200 Subject: [PATCH 4/8] grammar fix Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> --- documentation/CAMARA-API-Design-Guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 9ded7302..1b84c1c6 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -936,7 +936,8 @@ The following points can serve as a checklist to design the security mechanism o - if and after the User or API consumer sucessfully authenticated to the Authorization Server - if the requested Purpose and scopes were agreed upon during the onboarding process - This separation of concerns simplifies the implementation of the API endpoint that, after validating the access token, can now focus its API implementation. + This separation of concerns simplifies the implementation of the API endpoint that, after validating the access token, can now focus on its API implementation. + The access token is created by the API provider's Authorization Server to be consumed by the API provider's API endpoint. As described in [Appendix A (Normative): `info.description` template for when User identification can be from either an access token or explicit identifier](#appendix-a-normative-infodescription-template-for-when-user-identification-can-be-from-either-an-access-token-or-explicit-identifier) a three-legged access token is associated with Personal Identifiable Information (PII). From bd642be9e5e0dbb23e4e5e8363a71accfa27c895 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Thu, 21 Aug 2025 13:21:23 +0200 Subject: [PATCH 5/8] remove recommening self-contained token RFC 9068 --- documentation/CAMARA-API-Design-Guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index da97a9b3..279d7594 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -63,7 +63,7 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH | **Header** | HTTP Headers allow client and server send additional information joined to the request or response. A request header is divided by name (No case sensitive) followed by a colon and the header value (without line breaks). White spaces on the left hand from the value are ignored. | | **HTTP** | Hypertext Transfer Protocol (HTTP) is a communication protocol that allows the information transfer using files (XHTML, HTML…) in World Wide Web. | | **JSON** | The JavaScript Object Notation (JSON) Data Interchange Format [RFC8259](https://datatracker.ietf.org/doc/html/rfc8259) | -| **JWT** | JSON Web Token (JWT) is an open standard based on JSON [RFC7519](https://datatracker.ietf.org/doc/html/rfc7519)
JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens [RFC9068](https://datatracker.ietf.org/doc/html/rfc9068) | +| **JWT** | JSON Web Token (JWT) is an open standard based on JSON [RFC7519](https://datatracker.ietf.org/doc/html/rfc7519) | | **Kebab-case** | Practice in the words denomination where the hyphen is used to separate words. | | **OAuth2** | Open Authorization is an open standard that allows simple Authorization flows to be used in websites or applications. [RFC6749](https://datatracker.ietf.org/doc/html/rfc6749) | | **OIDC** | [OpenId Connect](https://openid.net/specs/openid-connect-core-1_0.html) is standard based on OAuth2 that adds authentication and consent to OAuth2. | @@ -945,7 +945,6 @@ The following points can serve as a checklist to design the security mechanism o If the access token is self-contained then the three-legged access token contains PII and the confidentiality of that PII must be protected. The confidentiallity of the PII in the self-contained access token can be achieved by the API provider's authorization server encrypting the access token to the API Provider's API endpoint. - It is recommended that self-contained access tokens follow RFC 9068 JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens. 4. **Input parameter validation** @@ -1303,3 +1302,4 @@ This approach simplifies API usage for API consumers using a three-legged access - If the subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. ``` + From 3f6b38165953b5386f0df3d50880c21ea85543f0 Mon Sep 17 00:00:00 2001 From: Axel Nennker Date: Wed, 10 Sep 2025 09:41:49 +0200 Subject: [PATCH 6/8] protect the PII --- documentation/CAMARA-API-Design-Guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 279d7594..fa0f3cbc 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -944,7 +944,7 @@ The following points can serve as a checklist to design the security mechanism o If the access token is self-contained then the three-legged access token contains PII and the confidentiality of that PII must be protected. The confidentiallity of the PII in the self-contained access token can be achieved by the API provider's authorization server encrypting - the access token to the API Provider's API endpoint. + the PII to the API Provider's API endpoint. 4. **Input parameter validation** @@ -1303,3 +1303,4 @@ This approach simplifies API usage for API consumers using a three-legged access ``` + From 47db1244a659dda70e88bd371e4b26234506a299 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 1 Oct 2025 12:02:43 +0200 Subject: [PATCH 7/8] Update documentation/CAMARA-API-Design-Guide.md Co-authored-by: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> --- documentation/CAMARA-API-Design-Guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index fa0f3cbc..7d480414 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -943,7 +943,8 @@ The following points can serve as a checklist to design the security mechanism o As described in [Appendix A (Normative): `info.description` template for when User identification can be from either an access token or explicit identifier](#appendix-a-normative-infodescription-template-for-when-user-identification-can-be-from-either-an-access-token-or-explicit-identifier) a three-legged access token is associated with Personal Identifiable Information (PII). If the access token is self-contained then the three-legged access token contains PII and the confidentiality of that PII must be protected. - The confidentiallity of the PII in the self-contained access token can be achieved by the API provider's authorization server encrypting + The confidentiality of the PII in the self-contained access token can be achieved by the API provider's authorization server encrypting + the PII to the API Provider's API endpoint. 4. **Input parameter validation** From f4c39d476e72c7a329cf2efdd959c24ba8e05709 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 1 Oct 2025 12:05:10 +0200 Subject: [PATCH 8/8] Update CAMARA-API-Design-Guide.md --- documentation/CAMARA-API-Design-Guide.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/documentation/CAMARA-API-Design-Guide.md b/documentation/CAMARA-API-Design-Guide.md index 7d480414..6610dd6a 100644 --- a/documentation/CAMARA-API-Design-Guide.md +++ b/documentation/CAMARA-API-Design-Guide.md @@ -943,9 +943,7 @@ The following points can serve as a checklist to design the security mechanism o As described in [Appendix A (Normative): `info.description` template for when User identification can be from either an access token or explicit identifier](#appendix-a-normative-infodescription-template-for-when-user-identification-can-be-from-either-an-access-token-or-explicit-identifier) a three-legged access token is associated with Personal Identifiable Information (PII). If the access token is self-contained then the three-legged access token contains PII and the confidentiality of that PII must be protected. - The confidentiality of the PII in the self-contained access token can be achieved by the API provider's authorization server encrypting - - the PII to the API Provider's API endpoint. + The confidentiality of the PII in the self-contained access token can be achieved by the API provider's authorization server encrypting the PII to the API Provider's API endpoint. 4. **Input parameter validation** @@ -1305,3 +1303,4 @@ This approach simplifies API usage for API consumers using a three-legged access +