Content for TS 33.122 Word version: 19.2.0
6.6 Security procedures for CAPIF-3/4/5/6 reference points
6.7 Security procedures for updating security method
6.8 Security procedure for API invoker offboarding
6.9 Security procedures for CAPIF-7/7e reference points
6.10 Security procedures for CAPIF-3e/4e/5e/6e reference points
6.11 Security procedures for CAPIF-8 reference point
6.12 Authorization for finer level service API access
6.13 Security procedures for CAPIF interconnection
6.14 Authorization procedure in a nested API invocation
...
...
6.6 Security procedures for CAPIF-3/4/5/6 reference points p. 24
To ensure security of the interfaces between CAPIF entities within a trusted domain, namely CAPIF-3, CAPIF-4, CAPIF-5, and CAPIF-6:
- TLS shall be used to provide integrity protection, replay protection and confidentiality protection. The support of TLS is mandatory. Security profiles for TLS implementation and usage shall follow the provisions given in TS 33.310, Annex E.
- Certificate based mutual authentication shall be performed between the CAPIF entities using TLS. Certificate based authentication shall follow the profiles given in clauses 6.1.3a and 6.1.4a of TS 33.310. The structure of the PKI used for the certificate is out of scope of the present document.
6.7 Security procedures for updating security method p. 24
As specified in TS 23.222, the CAPIF core function shall receive updates to AEF authentication and authorization method from API publishing function. In case that the AEF updates its authentication and authorization method and API invoker uses the old authentication and authorization method to invoke the service API, the AEF shall send a failure response to the API invoker with an indicator that indicates the authentication and authorization method used by the API invoker is incorrect. The API invoker shall contact the CAPIF core function to get the updated authentication and authorization method. Then the API invoker shall invoke the service API using the updated authentication and authorization method.
6.8 Security procedure for API invoker offboarding p. 24
Pre-conditions:
- The API invoker has been onboarded successfully.
Step 0.
TLS session is established successfully between the CAPIF core function and the API invoker.
Step 1.
An event occurs within the API invoker to trigger the offboarding action.
Step 2.
The API invoker shall send Offboard API invoker request message to the CAPIF core function, including the CAPIF core function specific API invoker ID which was assigned by the CAPIF core function during the onboarding procedure.
Step 3.
The CAPIF core function shall verify the API invoker ID received in step 2 and check that the corresponding profile exists for this API invoker. With successful verification of the API invoker ID and its profile, the CAPIF core function shall cancel the enrolment of the API invoker and delete the API invoker profile. This includes deletion of API invoker certificate, service API authentication and authorization information, and onboard secret (if applicable). Depending on the operator policy, the CAPIF core function may retain the information of the offboarded API invoker.
Step 4.
The CAPIF core function sends Offboard API invoker response message, indicating the successful offboarding of the API invoker.
Step 5.
The API invoker shall delete the information, such as API invoker ID, Service API authentication / authorization information, API invoker certificate, Onboard_Secret (if applicable).
Step 6.
The CAPIF core function shall tear down the TLS session with the API invoker.
Step 7.
The CAPIF core function shall send Event notification message to the API exposing function to indicate that this API invoker is no longer valid.
Step 8.
The API exposing function shall delete the security related information associated with this API invoker depending on the method that was used previously to authenticate the API invoker, e.g. AEF PSK (TLS-PSK method as described in subclause 6.5.2.1), root certificate to validate the API invoker certificate (PKI method as described in subclause 6.5.2.2), access token (OAuth 2.0 method as described in subclause 6.5.2.3 of the present document, respectively).
Step 9.
The API exposing function shall tear down the TLS connection with the API invoker.
Step 10.
The API exposing function shall return Event notification acknowledge message to indicate that the security related information associated with this API invoker is successfully deleted and thus the API invoker no longer an acknowledged user.
6.9 Security procedures for CAPIF-7/7e reference points |R16| p. 26
To ensure security of the interfaces between API Exposing functions (Topology hiding entities and destination AEF handling service APIs), namely CAPIF-7 and CAPIF-7e:
- Security procedures as specified in clause 6.4 of this specification for CAPIF-2 reference point shall be used for secure communication, authentication and authorization, between the AEFs belonging to same trust domain over CAPIF-7 reference point.
- Security procedures as specified in the clause 6.5 of this specification for CAPIF-2e reference point shall be used for secure communication, authentication and authorization, between the AEFs belonging to different trust domains over CAPIF-7e reference point.
6.10 Security procedures for CAPIF-3e/4e/5e/6e reference points |R16| p. 26
To ensure security of the interfaces between CAPIF entities between different trusted domains (CCF domain and API Provider Domain), namely CAPIF-3e, CAPIF-4e, CAPIF-5e, and CAPIF-6e:
- TS 33.210 shall be applied to secure messages on the reference points unless specified otherwise; and
- TS 33.310 may be applied regarding the use of certificates with the security mechanisms of TS 33.210 unless otherwise specified in the present document.
6.11 Security procedures for CAPIF-8 reference point |R19| p. 26
TLS shall be used to provide integrity protection, replay protection and confidentiality protection.
Authentication of CCF shall be based on the CCF's certificates following the profiles specified in clauses 6.1.3a and 6.1.4a of TS 33.310.
Authentication of ROF is left to implementation.
6.12 Authorization for finer level service API access |R19| p. 27
The authorization function shall support finer level authorization as specified in TS 23.222. In both RNAA and non-RNAA scenarios, finer level service API access authorization can be used to limit access to specific services, specific service operations and/or resources.
To enable finer level service API access, the authorization request or access token request (from API invoker to the CCF/Authorization Server) includes the requested service, service operations and/or resource(s) at the respective granularity. For RNAA, the request may also include the resource owner ID.
If the API invoker is authorized, the CCF responds to the API invoker with an access token including finer level authorization information, or an authorization code.
The following procedures are adapted to support finer level authorization:
Clause 6.5.3.2 on Authorization using OAuth client credential flow:
- The access token request message may also include details on finer level authorization.
- The authorization request may also include finer level authorization information.
- The CCF shall also check the finer level authorization if included in the request.
- The additional information in the Authorization Revocation Request message may also include information for finer level authorization.
- The scope can also include a list of service operation(s) and/or resource(s).
- The scope can also include a list of service operation(s) and/or resource(s).
6.13 Security procedures for CAPIF interconnection |R19| p. 27
6.13.1 General p. 27
The CAPIF provider A and CAPIF provider B host the CAPIF in their trust domains as specified in clause 6.2.2 of TS 23.222. The designated CAPIF core function of the CAPIF provider A interconnects with the designated CAPIF core function of the CAPIF provider B over CAPIF-6/6e interface.
The following clauses 6.13.2 and 6.13.3 details security aspects of the scenario where, the API invoker is onboarded to CCF-B of the CAPIF provider B and the target AEF is registered to CCF-A of CAPIF provider A.
6.13.2 Security method negotiation p. 27
For security method negotiation procedure in CAPIF interconnection, clause 6.3.1.2 shall be followed with the following enhancement:
- The API invoker shall send the security method request to the CCF-B.
- In case where CCF-B is in possession of the security method(s) as specified in clause 8.25.3.1 of TS 23.222, CCF-B shall select a security method to be used over CAPIF-2/2e reference point for each AEF based on the access scenarios and AEF capabilities.
- In case where CCF-B is not in possession of the security method(s), based on the AEF details received from the API invoker, CCF-B identifies the CCF-A where the AEF is registered and sends the request to CCF-A to either get the supported list of security method(s) of AEF or to get a selected security method. The request to CCF-A shall include AEF details and may include the API invoker ID and security method supported by API invoker (e.g., to enable CCF-A to select the security method). The CCF-A shall provide to CCF-B either the list of supported security methods of AEF or the selected security method. If the list of supported security methods of AEF is received, the CCF-B shall select a security method to be used over CAPIF-2/2e reference point for each AEF based on the access scenarios and AEF capabilities.
- The CCF-B shall send Security Method Response message to the API invoker indicating the selected security method for each AEF.
6.13.3 Authentication and authorization procedure p. 28
For the authentication and authorization between the API invoker onboarded to CCF-B in CAPIF provider B and AEF registered to the CCF-A in CAPIF provider A, the procedures as defined in clause 6.5.2 shall be followed with the enhancements as specified in this clause.
6.13.3.1 Method 1: Using TLS-PSK p. 28
- The API invoker in CAPIF provider domain B shall include the API invoker ID in the authentication initiation request message sent to the target AEF in CAPIF provider domain A for CAPIF interconnection.
- Based on the AEF details available at the API invoker, which indicates the AEF belongs to CCF-A, the authentication initiation request message shall include the information for identification of the CCF-B.
- The AEF in CAPIF provider domain shall request for security information (AEFPSK) from CCF-A to perform authentication and secure connection establishment with the API invoker, if the AEF does not have a security information. The request shall include the API invoker ID and the CCF-B ID (if received from the API invoker).
- When CCF-A receives the request message for security information from the AEF, CCF-A fetches the security information related to the chosen security method (TLS-PSK: AEFPSK), based on API invoker ID and CCF-B ID.
- If the CCF-A does not have security information of the API invoker locally available, CCF-A shall request the security information from CCF-B over CAPIF-6/6e reference point based on the received API invoker ID, and the available AEF details (including the service API interface information). The CCF-B shall provide the TLS-PSK related security information (AEFPSK) to CCF-A.
- The CCF-A shall provide the received security information to the AEF.
- After sending the authentication initiation response, API invoker in CAPIF provider domain B and AEF in CAPIF provider domain A establish a TLS connection using the security information obtained.
- After successful authentication of API invoker and AEF, the AEF shall authorize the API invoker's service API invocation request based on authorization information obtained from CCF-A. If CCF-A does not have sufficient information for authorization, CCF-A shall fetch additional information related to the API invoker from CCF-B based on the business relationship.
6.13.3.2 Method 2: Using PKI p. 28
The API invoker onboarded to CCF-B and the AEF registered to CCF-A shall follow the procedure in subclause 6.13.3.1 with the following adaptation to establish dedicated secure session over CAPIF-2e using TLS based on certificate based mutual authentication.
- For fetching the security information related to the chosen security method (TLS-PKI) the CCF-B includes only the API invoker ID.
- The CCF-B shall provide the security information (API invoker's root CA certificate) to the AEF via CCF-A, for allowing the AEF to validate the API invoker's certificate.
6.13.3.3 Method 3: TLS with OAuth Token p. 29
- The API invoker shall send the access token request message to the onboarded CCF-B, CCF-B determines that the service API requested is provided by the AEFs in CAPIF provider domain A. In interconnection scenario, the parameter 'scope' in Access token request message is required.
- The CCF-B sends the access token request message to the CCF in CAPIF provider domain A with the information as specified in Annex C.3.2. In interconnection scenario, the Onboard_secret is not included in the access token request message to the CCF-A. The CCF-A generates and provides an access token and returns it in an Access Token Response message to the API invoker via CCF-B as specified in clause 6.5.2.3.
- On CAPIF-2e, the API invoker authenticates to the AEF by establishing a TLS session with the AEF as specified in clause 6.13.3.1 or 6.13.3.2.
- With successful authentication to the AEF on CAPIF-2e, the API invoker shall initiate invocation of a 3GPP northbound API with the AEF including the access token in northbound API invocation request as per OAuth 2.0. The AEF verifies the integrity of the access token by verifying the CCF's signature to validate the access permission for the requested service API as specified in clause 6.5.2.3.
6.14 Authorization procedure in a nested API invocation |R19| p. 29
The nested API invocation scenario is a scenario where an API invocation towards a first API exposing function (AEF-1) triggers that this API exposing function (AEF-1) requests an API invocation towards a second API exposing function (AEF-2), i.e., AEF-1 becomes API Invoker towards AEF-2. Both belong to the same API provider domain. In this scenario, the CAPIF may reduce the authorization information inquiries for a nested API invocation using procedure described in this clause.
The authorization of API invocation triggered towards the second API exposing function uses token exchange procedure as specified in RFC 8693, where the access token of the API invoker to be used towards AEF-1 is used as the subject token as per the RFC 8693. AEF-1 before triggering API invocation towards AEF-2, invokes the token exchange request towards the CCF by sending the subject token to receive a new access token. AEF-1 uses the received new access token towards AEF-2 for nested API invocation.
Step 1.
API invoker - 1 invokes the AEF-1 service by using the access token obtained from the CCF/Authorization Function.
Step 2.
Based on the service API invocation request, AEF-1 verifies the access token and decides to invoke another service API exposed by AEF-2.
Step 3a.
AEF-1 sends a token exchange request message to CCF, to get a token to invoke the service API in AEF-2. The token exchange request message contains grant_type, the access token as the subject_token, optionally an actor_token, and optionally scope for the desired scope of the requested token. The grant-type is set as the token-exchange.
Step 3b.
The CCF validates whether the requesting AEF-1 is allowed for accessing the requested service API of AEF-2. Also, the CCF validates the access token in the request message that is provided by the API invoker to AEF-1. After successful validation, the CCF generates a new access token to allow AEF-1 to invoke the service API on AEF-2. The CCF checks whether the received token is an RNAA token and if so issues the new token as an RNAA token which includes the AEF ID in the (act) actor claim optionally, the API invoker ID, the resource owner ID and the scope, in addition to the standard access token claims as specified in clause C.2.2. The CCF responds to AEF-1 with the token exchange response message including the newly issued access token and optionally the scope (if required) for service API invocation on AEF-2.
Step 4.
AEF-1, sends a service API invocation request to AEF-2 with the authorization information i.e., access token received in step 3b.
Step 5.
AEF-2 checks whether the API invoker is authorized to invoke the requested service API based on the received token and if allowed, AEF-2 sends a service API invocation response.
Step 6.
The API invoker receives from AEF-1 the service API invocation response after the service API invocation from AEF-2.
