Content for TS 33.122 Word version: 18.3.0
C Access token profile
C.1 General
C.2 Access token profile
C.2.1 General
C.2.2 Token claims
C.3 Obtaining tokens
C.3.1 General
C.3.2 Access token request
C.3.3 Access token response
C.4 Refreshing an access token
C.4.1 Client Credentials Grant
C.4.2 Authorization code grant and PKCE
C.5 Using the token to access API exposing functions
C.6 Token revocation
C.7 Token validation
C.7.1 Access token validation
$ Change history
C (Normative) Access token profile p. 29
C.1 General p. 29
The information in this annex provides a description of two types of access tokens, i.e., the access token used in the 'Method 3 - TLS with OAuth token' authentication and authorisation method (i.e. used for existing CAPIF implementations, see clause 6.5.2.3) and access token used in RNAA (see clause 6.5.3). Characterization of the access token, how to obtain the access token, how to validate the access token, and how to refresh the access token is explained.
An 'Method 3 - TLS with OAuth token' access token or an access token used in RNAA has the following characteristics:
- Shall be encrypted when transported over the CAPIF 1/1e and CAPIF 2/2e interfaces (e.g. using TLS);
- Shall be a bearer type as specified in RFC 6750;
- Shall be encoded as a JSON Web Token as specified in RFC 7519;
- Shall be protected by the JSON signature profile as specified in RFC 7515; and,
- Shall be validated per OAuth 2.0 [4], RFC 7519 and RFC 7515.
C.2 Access token profile p. 29
C.2.1 General p. 29
The 'Method-3 - TLS with OAuth token' access token or an access token used in RNAA contains the token claims described in C.2.2. Token claims of both types of tokens are provided by the CAPIF Core Function and contain authentication and authorization information about the API Invoker. Token claims are used by the API Exposing Function for authorization of API Invoker northbound API requests.
C.2.2 Token claims p. 29
The CAPIF 'Method-3 - TLS with OAuth token' access token or an access token used in RNAA shall convey the following claims as defined in IETF RFC 7519 and IETF RFC 6749.
| Parameter | Description |
|---|---|
| exp | REQUIRED. The expiration time of the access token. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew (not to exceed 30 seconds). |
| client_id | REQUIRED. The identifier of the API Invoker making the API request as previously established with the CAPIF Core Function through onboarding. |
| scope |
REQUIRED. A string containing a space-delimited list, comprising of the following as scopes associated with this token:
|
The CAPIF OAuth 2.0 access token shall additionally convey the following claim for RNAA.
| Parameter | Description |
|---|---|
| resOwnerId | OPTIONAL. Resource owner ID. |
The 'exp'and 'scope' parameters of the access token shall be determined by the CAPIF core function based upon the client_id of the API Invoker provided in the Access Token Request message.
The scope parameter 'List of Services per AEF' shall contain a full or partial list of services which the API Invoker is permitted to access at each AEF.
C.3 Obtaining tokens p. 30
C.3.1 General p. 30
Once an API Invoker has successfully performed onboarding with the CAPIF Core Function, the API Invoker may request the CAPIF 'Method-3 - TLS with OAuth token' access tokens using 'Method 3 - TLS with OAuth token' defined in clause 6.5.2.3 or request access tokens used in RNAA using the methods defined in clause 6.5.3. Figure C.3.1-1 shows the access token request and access token response message exchange.
C.3.2 Access token request p. 30
To obtain an access token, the API Invoker makes a request to the CAPIF Core Function by sending an Access Token Request message with the following parameters using the "application/x-www-form-urlencoded" format, with a character encoding of UTF-8 in the HTTP request entity-body. The access token request parameters are shown in Table C.3.2-1.
| Parameter | Values |
|---|---|
| grant_type | REQUIRED. The value shall be set to "client_credentials" or "authorization_code". |
| client_id | REQUIRED. The identifier of the API Invoker making the request. It shall match the value that was assigned to the API Invoker during the onboarding process. |
| client_cred | OPTIONAL. The client credential that was provided to the API Invoker during the onboarding process. |
| Redirect_uri | OPTIONAL. The value shall be identical with the value in authorization request once authorization code grant or PKCE is used. |
| code | OPTIONAL. The authorization code received from the CCF for RNAA once authorization code grant or PKCE is used. |
| code_verifier | OPTIONAL. If the authorization code grant with PKCE flow is selected, the code verifier is used by the CCF to check the code_challenge according to IETF RFC 7636 once PKCE is used. |
| scope |
OPTIONAL. A string containing a space-delimited list, comprising of the following as scopes associated with this token:
|
If the token is used for RNAA (see clause 6.5.3), the parameter resOwnerID is used for the resource owner ID.
| Parameter | Values |
|---|---|
| resOwnerID | OPTIONAL. Resource owner ID |
C.3.3 Access token response p. 31
If the access token request (i.e. the client credential) is valid and authorized by the CAPIF Core Function, the CAPIF Core Function then returns an access token to the API Invoker in an access token response message; otherwise it will return an error.
The access token response parameters are shown in Table C.3.3-1.
| Parameter | Values |
|---|---|
| access_token | REQUIRED. This is the issued access token. |
| Refresh_token | OPTIONAL. This is the issued refresh token. |
| token_type | REQUIRED. This field shall be "bearer" |
| expires_in | REQUIRED. The lifetime in seconds of the access token. |
| scope | OPTIONAL. The granted scope by the CAPIF core function. |
Upon receiving the access token reponse message, the API Invoker may now use the access token to make authorized northbound API requests to API Exposure Functions as described in clause 6.5.2.3 or clause 6.5.3.
C.4 Refreshing an access token p. 31
C.4.1 Client Credentials Grant |R18| p. 31
To protect against leakage or other compromise, an access token includes an expiration time. If the API Invoker determines that its access token has expired or if the API Invoker receives an indication from the AEF that a fresh access token is needed, the API Invoker shall return to the CAPIF Core Function and repeat the procedure defined in clause C.3.
C.4.2 Authorization code grant and PKCE |R18| p. 32
If the API Invoker determines that its access token has expired or if the API Invoker receives an indication from the AEF that a fresh access token is needed, the API Invoker may use the refresh_token to get a refresh access token as depicted in Section 6 of RFC 6749.
The API Invoker may determine to repeat the procedure defined in clause C.3 to get a new refresh token and access token.
C.5 Using the token to access API exposing functions p. 32
Access tokens of type "bearer" shall be communicated from the API Invoker to AEF by including the access token in the HTTP Authorization Header, per RFC 6750.
The access token is opaque to the API Invoker, meaning that the API Invoker does not have any specific knowledge of the access token itself. The API Invoker shall use the 'expires_in' parameter from the access token response message to determine whether the access token is valid so that it does not send an expired access token to AEFs. If the access token is presented to an AEF and the token is expired or revoked, the AEF should return an error message indicating such to the API Invoker.
C.6 Token revocation p. 32
In order to limit the time validity of a token, the "exp" and "expires_in" parameters shall be used as a method of access token revocation.
Within the claims of a 'Method 3 - TLS with OAuth token' access token, the "exp" parameter shall be used by the AEF to determine whether or not the token has expired. If the current time is beyond the time specified by the "exp" parameter, the associated token shall no longer be considered valid and any requests made with an expired token shall be rejected by the AEF.
Within the claims of an access token response message, the "expires_in" parameter shall be used by the API Invoker to determine validity of the associated token. If the current time is beyond the time specified by the "expires_in" parameter, the associated access token shall no longer be considered valid and no northbound API requests shall be made using the expired access token. The procedure defined in C.3 shall be used to obtain a new access token.
C.7 Token validation p. 32
C.7.1 Access token validation p. 32
A non-RNAA access token, i.e. 'Method 3 - TLS with OAuth token' access token shall be validated according to RFC 7519.
$ Change history p. 33
