5 API Definitions

29.2553GPPRelease 17Stage 3TSUncrewed Aerial System Service Supplier (USS) Services

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

5.1 Naf_Authentication Service API

5.1.1 Introduction

The Naf_Authentication shall use the Naf_Authentication API.

The API URI of the Naf_Authentication API shall be:

{apiRoot}/<apiName>/<apiVersion>

The request URIs used in HTTP requests from the NF service consumer towards the NF service producer shall have the Resource URI structure defined in clause 5.2.4 of TS 29.122 [16], i.e.:

{apiRoot}/<apiName>/<apiVersion>/<apiSpecificSuffixes>

with the following components:

– The {apiRoot} shall be set as described in clause 5.2.4 in 3GPP TS 29.122 [16].

– The <apiName> shall be "naf-auth".

– The <apiVersion> shall be "v1".

– The <apiSpecificSuffixes> shall be set as described in clause 5.1.3.

5.1.2 Usage of HTTP

5.1.2.1 General

HTTP/2, IETF RFC 7540 [11], shall be used as specified in of TS 29.122 [16].

HTTP/2 shall be transported as specified in TS 29.122 [16].

The OpenAPI [6] specification of HTTP messages and content bodies for the Naf_Authentication API is contained in Annex A.

5.1.2.2 HTTP standard headers

5.1.2.2.1 General

See TS 29.122 [16] for the usage of HTTP standard headers.

5.1.2.2.2 Content type

JSON, IETF RFC 8259 [12], shall be used as content type of the HTTP bodies specified in the present specification as specified in TS 29.122 [16]. The use of the JSON format shall be signalled by the content type "application/json".

"Problem Details" JSON object shall be used to indicate additional details of the error in a HTTP response body and shall be signalled by the content type "application/problem+json", as defined in IETF RFC 7807 [13].

NOTE: This release only supports the content type JSON.

5.1.2.3 HTTP custom headers

The mandatory HTTP custom header fields specified in clause 5.2.3.2 of TS 29.500 [4] shall be supported, and the optional HTTP custom header fields specified in clause 5.2.3.3 of TS 29.500 [4] may be supported.

5.1.3 Resources

None

5.1.4 Custom Operations without associated resources

5.1.4.1 Overview

The structure of the custom operation URIs of the Naf_Authentication service is shown in Figure 5.1.4.1-1.

Figure 5.1.4.1-1: Custom operation URI structure of the Naf_Authentication API

Table 5.1.4.1-1 provides an overview of the custom operations and applicable HTTP methods.

Table 5.1.4.1-1: Custom operations without associated resources

Custom operation URI	Mapped HTTP method	Description
{apiRoot}/naf-auth/<apiVersion>/request-auth	POST	Request UAV authentication and authorization and subscribe to notifications triggered by the USS

5.1.4.2 Operation: request-auth

5.1.4.2.1 Description

The operation is used by the NF service consumer to request UAV authentication and authorization and subscribe to notifications triggered by the USS.

5.1.4.2.2 Operation Definition

This operation shall support the response data structures and response codes specified in tables 5.1.4.2.2-1 and 5.1.4.2.2-2.

Table 5.1.4.2.2-1: Data structures supported by the POST Request Body on this resource

Data type	P	Cardinality	Description
UAVAuthInfo	M	1	Represents the data to be used for UAV authentication and authorization

Table 5.1.4.2.2-2: Data structures supported by the POST Response Body on this resource

Data type	P	Cardinality	Response codes	Description
UAVAuthResponse	M	1	200 OK	Successful request of UAV authentication and authorization and subscription to notification of re-authentication and revocation triggered by the USS. If C2 authorization request is sent during UUAA-SM, the final response indicates that at least UUAA has succeeded.
N/A			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative AF.
N/A			308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative AF.
ProblemDetailsAuthenticateAuthorize	O	0..1	403 Forbidden	(NOTE 2)
NOTE 1: The manadatory HTTP error status code for the POST method listed in Table 5.2.6-1 of TS 29.122 [16] also apply. NOTE 2: Failure cases are described in clause 5.1.7.3.

Table 5.1.4.2.2-3: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	String	M	1	An alternative URI representing the end point of an alternative AF.

Table 5.1.4.2.2-4: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI representing the end point of an alternative AF.

5.1.5 Notifications

5.1.5.1 General

This clause specifies the notifications provided by the Naf_Authentication service.

Notifications shall comply to clause 5.2.5 of 3GPP TS 29.122 [16].

Table 5.1.5.1-1: Notifications overview

Notification

Callback URI

HTTP method or custom operation

Description

(service operation)

UAV Notification

{notifyUri}

notify (POST)

Reauthentication, Reauthorization or Revocation notification

5.1.5.2 UAV Notification

5.1.5.2.1 Description

The UAV Notification is used by the USS to trigger reauthentication, reauthorization or revocation notification to a NF service consumer that has subscribed to such notifications. The USS shall notify the NF Service Consumer when reauthentication is required.

5.1.5.2.2 Target URI

The Callback URI "{notifyUri}" shall be used with the callback URI variables defined in table 5.1.5.2.2-1.

Table 5.1.5.2.2-1: Callback URI variables

Name	Definition
notifyUri	String formatted as URI with the Callback Uri

5.1.5.2.3 Standard Methods

5.1.5.2.3.1 POST

This method shall support the request data structures specified in table 5.1.5.2.3.1-1 and the response data structures and response codes specified in table 5.1.5.2.3.2-1.

Table 5.1.5.2.3.1-1: Data structures supported by the POST Request Body

Data type	P	Cardinality	Description
ReauthRevokeNotify	M	1	Contains the reauthentication, reauthorization or revocation information.

Table 5.1.5.2.3.1-2: Data structures supported by the POST Response Body

Data type	P	Cardinality	Response codes	Description
n/a			204 No Content	Successful notification of reauthentication or reauthorization or revocation.
N/A			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative NEF.
N/A			308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative NEF.
NOTE: The mandatory HTTP error status codes for the POST method listed in Table 5.2.6-1 of TS 29.122 [16] also apply.

Table 5.1.5.2.3.1-3: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI representing the end point of an alternative NEF.

Table 5.1.5.2.3.1-4: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI representing the end point of an alternative NEF.

5.1.6 Data Model

5.1.6.1 General

This clause specifies the application data model supported by the Naf_Authentication API.

Table 5.1.6.1-1 specifies the data types defined for the Naf_Authentication service based interface protocol.

Table 5.1.6.1-1: Naf_Authentication specific Data Types

Data type	Clause defined	Description	Applicability
UAVAuthInfo	5.1.6.2.2	Information within Authenticate Request
UAVAuthResponse	5.1.6.2.4	Information within Authenticate Response
AuthResult	5.1.6.3.3	Enumeration indicating authentication result
ReauthRevokeNotify	5.1.6.2.3	Information within notification
NotifyType	5.1.6.3.4	Enumeration Notification type
ProblemDetailsAuthenticateAuthorize	5.1.6.4.1	Data type that extends ProblemDetails.
AdditionInfoAuthenticateAuthorize	5.1.6.2.5	Contains more details (not only the ProblemDetails) in case an UAV authentication request is rejected.
AuthContainer	5.1.6.2.6	Carries the AA related data

Table 5.1.6.1-2 specifies data types re-used by the Naf_Authentication service based interface protocol from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Naf_Authentication service based interface.

Table 5.1.6.1-2: Naf_Authentication re-used Data Types

Data type	Reference	Comments	Applicability
BitRate	TS 29.571 [15]	Bit Rate
Pei	TS 29.571 [15]	Permanent Equipment Identifier
Uri	TS 29.571 [15]	Uri
Gpsi	TS 29.571 [15]	GPSI
IpAddr	TS 29.571 [15]	IP address
LocationArea5G	TS 29.122 [16]	User location
ProblemDetails	TS 29.122 [16]	Represents additional information and details on an error response.
SupportedFeatures	TS 29.571 [15]	Used to negotiate the applicability of the optional features defined in table 5.1.8-1.
RefToBinaryData	TS 29.571 [15]	AA message payload data

5.1.6.2 Structured data types

5.1.6.2.1 Introduction

This clause defines the structures to be used in resource representations.

5.1.6.2.2 Type: UAVAuthInfo

Table 5.1.6.2.2-1: Definition of type UAVAuthInfo

Attribute name	Data type	P	Cardinality	Description	Applicability
gpsi	Gpsi	M	1	GPSI of the UAV
serviceLevelId	string	M	1	Service Level Device Identity of the UAV
ipAddr	IpAddr	O	0..1	When present, this attribute indicates the IP address associated with the PDU session.
authMsg	string	O	0..1	Contains the authentication message or authorization data (which is not present in the initial request) used in the subsequent request messages during multiple round trip message exchanges. This attribute is deprecated; the attribute "authContainer" should be used instead.
authContainer	array(AuthContainer)	O	1..N	Contains the AA related data without the "authResult" attribute. This attribute deprecates "authMsg" attribute.
pei	Pei	O	0..1	PEI associated with the UAV.
notifyUri	Uri	C	0..1	This attribute shall be present in the initial authentication message. It carries the notification URI to receive reauthentication, reauthorization or revocation related notifications
notifyCorrId	string	C	0..1	Notification correlation ID assigned by the NF service consumer. Shall be present when the "notifyUri" attribute is provided.
uavLocInfo	LocationArea5G	O	0..1	This attribute shall contain the UE location information if it is available.
suppFeat	SupportedFeatures	C	0..1	This IE shall be present during the initial authentication and authorization request if at least one optional feature defined in clause 5.1.8 is supported.

5.1.6.2.3 Type: ReauthRevokeNotify

Table 5.1.6.2.3-1: Definition of type ReauthRevokeNotify

Attribute name	Data type	P	Cardinality	Description	Applicability
gpsi	Gpsi	M	1	GPSI of the UAV
serviceLevelId	string	M	1	Service Level Device Identity of the UAV
authMsg	string	C	0..1	Contains the authentication message or authorization data. This attribute shall be present when "notifyType" attribute is set to REAUTHORIZE. This attribute is deprecated; the attribute "authContainer" should be used instead.
authContainer	array(AuthContainer)	C	1..N	Contains the AA related data. This attribute shall be present when "notifyType" attribute is set to REAUTHORIZE. This attribute deprecates "authMsg" attribute.
ipAddr	IpAddr	O	0..1	When present, this IE indicates the IP address associated with the PDU session.
notifyCorrId	string	C	0..1	Notification correlation ID used to identify the request to which the notification relates. It shall be present if the "notifyCorrId" attribute is provided in the request and set to the same value as the "notifyCorrId" attribute of UAVAuthInfo data type.
notifyType	NotifyType	M	1	This attribute shall contain the notification type.

5.1.6.2.4 Type: UAVAuthResponse

Table 5.1.6.2.4-1: Definition of type UAVAuthResponse

Attribute name	Data type		P	Cardinality	Description	Applicability
gpsi	Gpsi		C	0..1	GPSI of the UAV. Shall be present except during PDU Session Modification for C2 Communication procedure.
authResult	AuthResult		C	0..1	Conveys the UAV authentication result (success) . Shall be present if there is no intermediate round-trip messages. This attribute is deprecated; the attribute "authContainer" should be used instead.
authMsg	string		C	0..1	Contains the authentication message or authorization data. Shall be present if the USS triggers intermediate round-trip messages. This attribute is deprecated; the attribute "authContainer" should be used instead.
authContainer	array(AuthContainer)	C		1..N	Contains the AA related data.
serviceLevelId	string		O	0..1	Contains a new Service Level Device Identity of the UAV
authSessAmbr	BitRate		O	0..1	The DN Authorized Session-AMBR.
authProfIndex	string		O	0..1	DN authorization profile index.
suppFeat	SupportedFeatures		C	0..1	This IE shall be present during the initial authentication and authorization response if at least one optional feature defined in clause 5.1.8 is supported.

5.1.6.2.5 Type: AdditionInfoAuthenticateAuthorize

Table 5.1.6.2.5-1: Definition of type AdditionInfoAuthenticateAuthorize

Attribute name

Data type

Cardinality

Description

Applicability

uasResRelInd

boolean

0..1

This attribute is used to indicate if an UAS service related network resource can be released or not, during re-authentication failure.

It shall be included if the "cause" attribute within the ProblemDetails data type is set to "FAILED_AUTH".

When present, it shall be set as follows:

– true: UAS resource release is requested;

– false (default): UAS resource release is not requested.

5.1.6.2.6 Type: AuthContainer

Table 5.1.6.2.6-1: Definition of type AuthContainer

Attribute name	Data type	P	Cardinality	Description	Applicability
authMsgType	AuthMsgType	C	0..1	Type of AA message. Shall be present if more than one AuthContainer’s are carried in the UAVAuthResponse.
authMsgPayload	RefToBinaryData	O	0..1	AA message payload data.
authResult	AuthResult	C	0..1	Shall be present for the final AA response conveying the AA result.

5.1.6.3 Simple data types and enumerations

5.1.6.3.1 Introduction

This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.

5.1.6.3.2 Simple data types

The simple data types defined in table 5.1.6.3.2-1 shall be supported.

Table 5.1.6.3.2-1: Simple data types

Type Name	Type Definition	Description	Applicability

5.1.6.3.3 Enumeration: AuthResult

The enumeration AuthResult represents the result of authentication and/or authorization. It shall comply with the provisions defined in table 5.1.6.3.3-1.

Table 5.1.6.3.3-1: Enumeration AuthResult

Enumeration value	Description	Applicability
AUTH_SUCCESS	The UUAA or C2 authorization has succeeded.
AUTH_FAIL	The UUAA or C2 authorization has failed.

5.1.6.3.4 Enumeration: NotifyType

The enumeration NotifyType represents the type of notification. It shall comply with the provisions defined in table 5.1.6.3.4-1.

Table 5.1.6.3.4-1: Enumeration NotifyType

Enumeration value	Description	Applicability
REAUTHENTICATE	The UAV needs to be reauthenticated.
REAUTHORIZE	Authorization data needs to be updated to UAV.
REVOKE	Revoke UAV authentication and authorization

5.1.6.3.5 Void

5.1.6.3.6 Enumeration: AuthMsgType

The enumeration AuthMsgType represents the type of AA message. It shall comply with the provisions defined in table 5.1.6.3.6-1.

Table 5.1.6.3.6-1: Enumeration AuthMsgType

Enumeration value	Description	Applicability
UUAA	UUAA payload.
C2AUTH	C2 authorization payload.

5.1.6.4 Data types describing alternative data types or combinations of data types

5.1.6.4.1 Type: ProblemDetailsAuthenticateAuthorize

Table 5.1.6.4.1-1: Definition of type ProblemDetailsAuthenticateAuthorize as a list of to be combined data types

Data type	Cardinality	Description	Applicability
ProblemDetails	1	Details of the problem as defined in TS 29.122 [16].
AdditionInfoAuthenticateAuthorize	1	Contains additional information to indicate the handling of the UAS service related network resource, during re-authentication failure.

5.1.7 Error Handling

5.1.7.1 General

Response bodies for error handling, as described in 3GPP TS 29.122 [16], are applicable to the APIs in the present specification unless specified otherwise, with the following clarifications:

– the SCEF is the AF; and

– the SCS/AS is the NEF invoking an API.

In addition, the requirements in the following clauses are applicable for the Naf_Authentication API.

5.1.7.2 Protocol Errors

No specific procedures for the Naf_Authentication service are specified.

5.1.7.3 Application Errors

The application errors defined for the Naf_Authentication service are listed in Table 5.1.7.3-1.

Table 5.1.7.3-1: Application errors

Application Error	HTTP status code	Description
FAILED_AUTH	403 Forbidden	The HTTP request is rejected because the UAV authentication is failed by the USS.

5.1.8 Feature negotiation

The optional features in table 5.1.8-1 are defined for the Naf_Authentication API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of TS 29.122 [16].

Table 5.1.8-1: Supported Features

Feature number	Feature Name	Description

5.1.9 Security

TLS shall be used to support the security communication between the NEF and the AF over N33 interface. The access to the Naf_Authentication API shall be authorized by means of OAuth2 protocol (see IETF RFC 6749 [9]), based on local configuration, using the "Client Credentials" authorization grant. If OAuth2 is used, a client, prior to consuming services offered by the Naf_Authentication API, shall obtain a "token" from the authorization server.

Annex A (normative):
OpenAPI specification