diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index 3334cc3..22fb967 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -28,7 +28,18 @@ info: * **Notification URL and token**: Developers may provide a callback URL (`sink`) for receiving an async response. This is an optional parameter. If `sink` is included, it is RECOMMENDED for the client to provide as well the `sinkCredential` - property to protect the notification endpoint. In the current version,`sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT` if provided. + property to protect the notification endpoint. In the current version, `sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT` if provided. + + Using `credentialType: PRIVATE_KEY_JWT` requires the JWT authentication parameters to be pre-configured + out-of-band between the API consumer and the API provider as part of the onboarding process. No response of + this API returns `sinkCredential`, so the provider's `jwksUri` is never conveyed in-band. Unlike an event + subscription, this operation creates no resource to read back, the same static `jwksUri` would be repeated on + every `202` response, and the callback may be delivered before the API consumer has processed that response. + If `PRIVATE_KEY_JWT` is requested and no JWK Set is configured for the API consumer, the API returns the + error response `422 PRIVATE_KEY_JWT_NOT_CONFIGURED`. A failure to authenticate against the API consumer's + authorization server when the callback is delivered cannot be detected while the request is being processed, + and is therefore reported in the callback with property `status` set to `OPERATION_NOT_COMPLETED`. + When an asynchronous response is requested, the 202 response of the API will include an `operationId` property. This `operationId` property will also be sent in the callback notification. The purpose of the `operationId` is to correlate an asynchronous response with its corresponding request. @@ -86,16 +97,10 @@ info: The standard behaviour of the API is synchronous, although for large area requests the API may behave asynchronously. An API invoker can enforce - asynchronous behaviour by providing a callback URL (sink) in the request, + asynchronous behaviour by providing a callback URL (`sink`) in the request, in this case the API sends a callback to the callback URL provided with the - result of the request. If sink is included, it is RECOMMENDED for the - client to provide as well the sinkCredential property to protect the - notification endpoint. In the current version, sinkCredential.credentialType - MUST be set to ACCESSTOKEN if provided. When an asynchronous response is - requested, the 202 response of the API will include an `operationId` - property. This `operationId` property will also be sent in the callback - notification. The purpose of the `operationId` is to correlate an - asynchronous response with its corresponding request. + result of the request. See the **Notification URL and token** definition + above for the details about `sink`, `sinkCredential` and `operationId`. ## Error handling: @@ -684,10 +689,11 @@ components: code: INVALID_ARGUMENT message: Invalid input GENERIC_400_INVALID_CREDENTIAL: + description: Invalid sink credential type value: status: 400 code: INVALID_CREDENTIAL - message: "Only Access token is supported" + message: Only Access token or Private key JWT are supported GENERIC_400_INVALID_TOKEN: value: status: 400 @@ -741,6 +747,7 @@ components: - Indicated request is too big for synchronous processing and asynchronous processing is not enabled ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SYNC_RESPONSE", "message": "The indicated request is too big for synchronous processing and asynchronous processing is not enabled") - The requested `areaType` is not supported by the MNO ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE", "message": "The requested areaType is not supported by the MNO") - Indicated service level is not supported ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL", "message": "The service level provided is not supported") + - `sinkCredential.credentialType` is set to `PRIVATE_KEY_JWT` but no JWK Set is configured for the API consumer ("code": "PRIVATE_KEY_JWT_NOT_CONFIGURED", "message": "No JWK Set configured for PRIVATE_KEY_JWT authentication.") headers: x-correlator: $ref: '../common/CAMARA_common.yaml#/components/headers/x-correlator' @@ -761,6 +768,7 @@ components: - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SYNC_RESPONSE - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL + - PRIVATE_KEY_JWT_NOT_CONFIGURED examples: PREDICTIVE_CONNECTIVITY_DATA_422_UNSUPPORTED_REQUEST: value: @@ -792,6 +800,12 @@ components: status: 422 code: PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL message: The service level provided is not supported + GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED: + description: Private key JWT sink credential type is used but no configuration was pre-shared + value: + status: 422 + code: PRIVATE_KEY_JWT_NOT_CONFIGURED + message: No JWK Set configured for PRIVATE_KEY_JWT authentication. examples: ConnectivityDataSupportedAreaResponseExample: description: Connectivity data supported area response example diff --git a/code/Test_definitions/predictive-connectivity-data.feature b/code/Test_definitions/predictive-connectivity-data.feature index 003d682..5953d39 100644 --- a/code/Test_definitions/predictive-connectivity-data.feature +++ b/code/Test_definitions/predictive-connectivity-data.feature @@ -130,7 +130,7 @@ Feature: CAMARA Predictive Connectivity Data API, vwip @predictive_connectivity_data_07_async_success_scenario Scenario: Validate success async response for a request when sink is provided - # Property "$.sink" is set with a valid public accessible HTTPs endpoint + # Property "$.sink" is set with a valid publicly accessible HTTPS endpoint Given the request body property "$.area" is set to a valid testing area within supported regions And the request body properties "$.startTime" and "$.endTime" are valid future date-times, with "$.endTime" later than "$.startTime" And the request body property "$.serviceLevel" is set to a valid communication service level @@ -147,7 +147,7 @@ Feature: CAMARA Predictive Connectivity Data API, vwip @predictive_connectivity_data_08_async_operation_not_completed_scenario Scenario: Validate async callback when operation fails - # Property "$.sink" is set with a valid public accessible HTTPs endpoint + # Property "$.sink" is set with a valid publicly accessible HTTPS endpoint Given the request body property "$.area" is set to a valid testing area within supported regions And the request body properties "$.startTime" and "$.endTime" are valid future date-times, with "$.endTime" later than "$.startTime" And the request body property "$.serviceLevel" is set to a valid communication service level @@ -158,7 +158,7 @@ Feature: CAMARA Predictive Connectivity Data API, vwip And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" And the response includes property "$.operationId" - And there have been some problem processing the request asynchronously + And there has been a problem processing the request asynchronously And the request with the response body will be received at the address of the request property "$.sink" with property "$.operationId" equal to response property "$.operationId" And the request will have header "Authorization" set to "Bearer " + the value of the request property "$.sinkCredential.accessToken" And the request body complies with the OAS schema at "/components/schemas/ConnectivityDataAsyncResponse" @@ -272,7 +272,7 @@ Feature: CAMARA Predictive Connectivity Data API, vwip | $.endTime | @predictive_connectivity_data_400.03_invalid_service_level - Scenario: Error 400 when serviceLevel has not a valid value + Scenario: Error 400 when serviceLevel does not have a valid value Given the request body property "$.serviceLevel" is not set to "C2", "STREAM_4K" or "BEST_EFFORT" When the request "retrieveConnectivity" is sent Then the response status code is 400 @@ -293,7 +293,7 @@ Feature: CAMARA Predictive Connectivity Data API, vwip And the response property "$.message" contains a user friendly text @predictive_connectivity_data_400.05_invalid_network_type - Scenario: Error 400 when networkType has not a valid value + Scenario: Error 400 when networkType does not have a valid value Given the request body property "$.networkType" is not set to a "4G" or "5G" When the request "retrieveConnectivity" is sent Then the response status code is 400 @@ -346,7 +346,7 @@ Feature: CAMARA Predictive Connectivity Data API, vwip @predictive_connectivity_data_400.09_invalid_url Scenario: Invalid sink - Given the request body property "$.sink" is not set to an url + Given the request body property "$.sink" is not set to a URL When the request "retrieveConnectivity" is sent Then the response status code is 400 And the response header "x-correlator" has same value as the request header "x-correlator"