diff --git a/code/common/.sync-manifest.yaml b/code/common/.sync-manifest.yaml index fbce3ef..0de41d2 100644 --- a/code/common/.sync-manifest.yaml +++ b/code/common/.sync-manifest.yaml @@ -1,6 +1,7 @@ sources: - repository: Commonalities - release: r4.2 + release: r4.3 files: - CAMARA_common.yaml: f5122885eab0d3bc7424cf26e2087d4d02c9b96d - CAMARA_event_common.yaml: 9d74ec530af38045dc3d02772407a1d2d4f2f746 + CAMARA_common.yaml: 73895974478c1d8fffd2ba7b7a6553eec1a145b1 + CAMARA_event_common.yaml: 42e72db4f3e8562b93b54b6182c40afb2b850d48 + info-description-templates.yaml: 1c7928d2cf51c70b8cdea7b4e5fdbaa75f7d984b diff --git a/code/common/CAMARA_common.yaml b/code/common/CAMARA_common.yaml index f512288..7389597 100644 --- a/code/common/CAMARA_common.yaml +++ b/code/common/CAMARA_common.yaml @@ -12,7 +12,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip - x-camara-commonalities: 0.8.0-rc.2 + x-camara-commonalities: 0.8.0 components: securitySchemes: diff --git a/code/common/CAMARA_event_common.yaml b/code/common/CAMARA_event_common.yaml index 9d74ec5..42e72db 100644 --- a/code/common/CAMARA_event_common.yaml +++ b/code/common/CAMARA_event_common.yaml @@ -11,7 +11,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip - x-camara-commonalities: 0.8.0-rc.2 + x-camara-commonalities: 0.8.0 components: securitySchemes: @@ -316,6 +316,7 @@ components: description: REQUIRED. An access token is a token granting access to the target resource. type: string maxLength: 4096 + writeOnly: true accessTokenExpiresUtc: type: string format: date-time @@ -329,6 +330,7 @@ components: accessTokenType: description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string + writeOnly: true enum: - bearer required: @@ -338,9 +340,30 @@ components: PrivateKeyJWTCredential: type: object - description: Use PRIVATE_KEY_JWT to get an access token. The authorization server information needed for this type of sink credential (token endpoint, client ID, JWKS URL) is shared upfront between the client and the CAMARA entity. This type of credential is to be used by clients that have an authorization server. + description: Use PRIVATE_KEY_JWT to get an access token. This type of credential is to be used by clients that have an authorization server. allOf: - $ref: "#/components/schemas/SinkCredential" + - type: object + properties: + clientId: + description: The client ID used to authenticate when requesting an access token using PRIVATE_KEY_JWT. + type: string + maxLength: 128 + writeOnly: true + tokenUri: + description: The URI where to request an access token using PRIVATE_KEY_JWT. + type: string + format: uri + maxLength: 2048 + pattern: ^https:\/\/.+$ + writeOnly: true + jwksUri: + description: The URI used to request the public key to verify that the JWT assertion was signed by PRIVATE_KEY_JWT. + type: string + format: uri + maxLength: 2048 + pattern: ^https:\/\/.+$ + readOnly: true # ───────────────────────────────────────────────────────────────────────── # Section 5: Subscription lifecycle data diff --git a/code/common/info-description-templates.yaml b/code/common/info-description-templates.yaml new file mode 100644 index 0000000..1c7928d --- /dev/null +++ b/code/common/info-description-templates.yaml @@ -0,0 +1,116 @@ +# Mandatory `info.description` text templates for CAMARA API specs. +# +# This file is owned by Commonalities and synchronised into every onboarded +# CAMARA API repository as `code/common/info-description-templates.yaml` by the +# cache-common mechanism. Do not edit in API repositories. +# +# Each top-level key is a template name (lowercase-hyphenated, derived from +# the heading of its template). The `content` field holds the text that an +# API specification MUST embed as-is inside its `info.description`, bracketed +# by the BEGIN / END HTML-comment markers that are part of the content. +# +# Indentation is chosen so that copying the BEGIN..END region from this file +# into a target spec's `info.description` (`info:` column 0 -> `description: |` +# column 2 -> text column 4) preserves indentation with no fixup. +# +# Sources: +# - CAMARA API Design Guide (Commonalities) +# - CAMARA-API-access-and-user-consent.md (IdentityAndConsentManagement) +# If this file and a source document disagree, the source document wins; this +# file is regenerated to match. + +# Universal - mandatory in every CAMARA API. +# Source: +# IdentityAndConsentManagement/documentation/CAMARA-API-access-and-user-consent.md +# section "Mandatory template for `info.description` in CAMARA API specs" + +info: + x-camara-commonalities: 0.8.0 + +authorization-and-authentication: + content: | + + # Authorization and authentication + + The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. + + The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. + + In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. + + +# Universal - mandatory in every CAMARA API. +# Source: +# Commonalities/documentation/CAMARA-API-Design-Guide.md section 3.2.3 +# "Error Responses - Mandatory Template for `info.description` in CAMARA API" +additional-error-responses: + content: | + + # Additional CAMARA error responses + + The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. + + Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. + + As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + + +# Universal - mandatory in every CAMARA API targeting Commonalities r4.3 or later. +# Source: +# Commonalities/documentation/CAMARA-API-Design-Guide.md section 3.2.4 +# "Request Body Strictness - Mandatory Template for `info.description` in CAMARA API" +request-body-strictness: + content: | + + # Request body strictness + + This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response. + + +# Opt-in - applicable to APIs where the subject of an operation can be +# identified either implicitly from a three-legged access token or explicitly +# from a `device` object. Mutually exclusive with `identifying-phone-number-from-access-token`. +# Source: +# Commonalities/documentation/CAMARA-API-Design-Guide.md Appendix A, +# filled in with the `device` / `device` object choice. +identifying-device-from-access-token: + content: | + + # Identifying the device from the access token + + This API requires the API consumer to identify a device as the subject of the API as follows: + - When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided. + - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token. + + This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. + + ## Error handling: + + - If the subject cannot be identified from the access token and the optional `device` object is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. + + - If the subject can be identified from the access token and the optional `device` object 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 is identified by these two methods, as the server is unable to make this comparison. + + +# Opt-in - applicable to APIs where the subject of an operation can be +# identified either implicitly from a three-legged access token or explicitly +# from a `phoneNumber` field. Mutually exclusive with `identifying-device-from-access-token`. +# Source: +# Commonalities/documentation/CAMARA-API-Design-Guide.md Appendix A, +# filled in with the `phone number` / `phoneNumber` field choice. +identifying-phone-number-from-access-token: + content: | + + # Identifying the phone number from the access token + + This API requires the API consumer to identify a phone number as the subject of the API as follows: + - When the API is invoked using a two-legged access token, the subject will be identified from the optional `phoneNumber` field, which therefore MUST be provided. + - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token. + + This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. + + ## Error handling: + + - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. + + - If the subject can be identified from the access token and the optional `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 phone number is identified by these two methods, as the server is unable to make this comparison. +