6 API Definitions

29.5263GPP5G SystemNetwork Slice-Specific and SNPN Authentication and Authorization servicesRelease 17Stage 3TS

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

6.1 Nnssaaf_NSSAA Service API

6.1.1 Introduction

The Nnssaaf_NSSAA service shall use the Nnssaaf_NSSAA API.

The API URI of the Nnssaaf_NSSAA API shall be:

{apiRoot}/<apiName>/<apiVersion>

The request URIs used in HTTP request from the NF service consumer towards the NF service producer shall have the Resource URI structure defined in clause 4.4.1 of 3GPP TS 29.501 [5], i.e.:

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

with the following components:

– The {apiRoot} shall be set as described in 3GPP TS 29.501 [5].

– The <apiName> shall be "nnssaaf-nssaa".

– The <apiVersion> shall be "v1".

– The <apiSpecificResourceUriPart> shall be set as described in clause 6.1.3.

6.1.2 Usage of HTTP

6.1.2.1 General

HTTP/2, IETF RFC 7540 [11], shall be used as specified in clause 5 of 3GPP TS 29.500 [4].

HTTP/2 shall be transported as specified in clause 5.3 of 3GPP TS 29.500 [4].

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

6.1.2.2 HTTP standard headers

6.1.2.2.1 General

See clause 5.2.2 of 3GPP TS 29.500 [4] for the usage of HTTP standard headers.

6.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 clause 5.4 of 3GPP TS 29.500 [4]. 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].

6.1.2.3 HTTP custom headers

The mandatory HTTP custom header fields specified in clause 5.2.3.2 of 3GPP TS 29.500 [4] shall be applicable.

6.1.3 Resources

6.1.3.1 Overview

The structure of the Resource URIs of the Nnssaaf_NSSAA service is shown in Figure 6.1.3.1-1

Figure 6.1.3.1-1: Resource URI structure of the NSSAA API

Table 6.1.3.1-1 provides an overview of the resources and applicable HTTP methods.

Table 6.1.3.1-1: Resources and methods overview

Resource name

Resource URI

HTTP method or custom operation

Description

slice-authentications

(Collection)

/v1/slice-authentications

POST

Initiate the slice-specific authentication and authorization process by providing inputs related to the UE and a specific slice.

slice-authentication

(Document)

/v1/slice-authentications/{authCtxId}

PUT

Put the UE response from the EAP process.

6.1.3.2 Resource: slice-authentications (Collection)

6.1.3.2.1 Description

This resource represents a collection of the slice-authentication resources generated by the NSSAAF.

6.1.3.2.2 Resource Definition

Resource URI: {apiRoot}/nnssaaf-nssaa /<apiVersion>/slice-authentications

This resource shall support the resource URI variables defined in table 6.1.3.2.2-1.

Table 6.1.3.2.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	See clause 6.1.1
apiVersion	string	See clause 6.1.1

6.1.3.2.3 Resource Standard Methods

6.1.3.2.3.1 POST

This method shall support the URI query parameters specified in table 6.1.3.2.3.1-1.

Table 6.1.3.2.3.1-1: URI query parameters supported by the POST method on this resource

Name	Data type	P	Cardinality	Description	Applicability
n/a

This method shall support the request data structures specified in table 6.1.3.2.3.1-2 and the response data structures and response codes specified in table 6.1.3.2.3.1-3.

Table 6.1.3.2.3.1-2: Data structures supported by the POST Request Body on this resource

Data type	P	Cardinality	Description
SliceAuthInfo	M	1	Contains the GPSI, S-NSSAI, and EAP ID Response from the UE, etc.

Table 6.1.3.2.3.1-3: Data structures supported by the POST Response Body on this resource

Data type	P	Cardinality	Response codes	Description
SliceAuthContext	M	1	201 Created	This case indicates the corresponding resource has been created by the NSSAAF for the requested slice-specific authentication and authorization, and further EAP process is required. The HTTP response shall include a "Location" header that contains the resource URI of the created resource.
RedirectResponse	O	0..1	307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing a different URI, or the same URI if this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same NSSAAF or NSSAAF (service) set. (NOTE 2)
RedirectResponse	O	0..1	308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing a different URI, or the same URI if this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same NSSAAF or NSSAAF (service) set. (NOTE 2)
ProblemDetails	O	0..1	400 Bad Request	This case represents the failure to start slice-specific authentication and authorization because of input parameter error.
ProblemDetails	O	0..1	403 Forbidden	This case represents when the UE or the slice is not allowed to be authenticated. The "cause" attribute may be used to indicate one of the following application errors: – SLICE_AUTH_REJECTED
ProblemDetails	O	0..1	404 Not Found	This case represents the user or user context is not found. The "cause" attribute may be used to indicate one of the following application errors: – CONTEXT_NOT_FOUND – USER_NOT_FOUND
ProblemDetails	O	0..1	504 Gateway Time out	This case represents network error or remote peer (i.e. AAA-S) error, e.g. not reachable, no response and time out. The "cause" attribute may be used to indicate one of the following application errors: – NETWORK_FAILURE – UPSTREAM_SERVER_ERROR – TIME_OUT_REQUEST
NOTE 1: The mandatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. NOTE 2: RedirectResponse may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

Table 6.1.3.2.3.1-4: Headers supported by the POST method on this resource

Name	Data type	P	Cardinality	Description
n/a

Table 6.1.3.2.3.1-5: Headers supported by the 201 response code on this resource

Name

Data type

Cardinality

Description

Location

URI

URI of created resource for the slice authentication context.

The URI structure is defined in clause 6.1.3.3.1.

Table 6.1.3.2.3.1-6: Headers supported by the 307 Response Code on this endpoint

Name

Data type

Cardinality

Description

Location

string

URI pointing to the resource of another NF service producer to which the request should be sent.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

Table 6.1.3.2.3.1-7: Headers supported by the 308 Response Code on this endpoint

Name

Data type

Cardinality

Description

Location

string

URI pointing to the resource of another NF service producer to which the request should be sent.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

6.1.3.2.4 Resource Custom Operations

There is no Resource Custom Operations in the current version of this API.

6.1.3.3 Resource: slice-authentication (Document)

6.1.3.3.1 Description

The sub-resource "slice-authentication" is generated by the NSSAAF. This subresource should not persist after the slice-specific authentication and authorization process finishes.

6.1.3.3.2 Resource Definition

Resource URI: {apiRoot}/nnssaaf-nssaa/<apiVersion>/slice-authentications/{authCtxId}

This resource shall support the resource URI variables defined in table 6.1.3.3.2-1.

Table 6.1.3.3.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	See clause 6.1.1
apiVersion	string	See clause 6.1.1
authCtxId	string	The slice authentication context ID, which is of data type SliceAuthCtxId defined in clause 6.1.6.3.2.

6.1.3.3.3 Resource Standard Methods

6.1.3.3.3.1 PUT

This method shall support the URI query parameters specified in table 6.1.3.3.3.1-1.

Table 6.1.3.3.3.1-1: URI query parameters supported by the PUT method on this resource

Name	Data type	P	Cardinality	Description	Applicability
n/a

This method shall support the request data structures specified in table 6.1.3.3.3.1-2 and the response data structures and response codes specified in table 6.1.3.3.3.1-3.

Table 6.1.3.3.3.1-2: Data structures supported by the PUT Request Body on this resource

Data type	P	Cardinality	Description
SliceAuthConfirmationData	M	1	Contains the EAP message generated by the UE and provided to the AMF.

Table 6.1.3.3.3.1-3: Data structures supported by the PUT Response Body on this resource

Data type	P	Cardinality	Response codes	Description
SliceAuthConfirmationResponse	M	1	200 OK	This case indicates that the NSSAAF has performed the slice-specific authentication. The response body shall contain the result of the slice-specific authentication and authorization.
RedirectResponse	O	0..1	307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing a different URI, or the same URI if this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same NSSAAF or NSSAAF (service) set. (NOTE 2)
RedirectResponse	O	0..1	308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing a different URI, or the same URI if this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same NSSAAF or NSSAAF (service) set. (NOTE 2)
ProblemDetails	O	0..1	400 Bad Request	This case represents a slice-specific authentication failure because of input parameter error. This indicates that the NSSAAF was not able to process the slice-specific authentication.
ProblemDetails	O	0..1	403 Forbidden	This case represents when the UE or the slice is not allowed to be authenticated. The "cause" attribute may be used to indicate one of the following application errors: – SLICE_AUTH_REJECTED
ProblemDetails	O	0..1	404 Not Found	This case represents the UE or UE related context is not found. The "cause" attribute may be used to indicate one of the following application errors: – CONTEXT_NOT_FOUND – USER_NOT_FOUND
ProblemDetails	O	0..1	504 Gateway Time out	This case represents network error or remote peer (i.e. AAA-S) error, e.g. not reachable, no response when time out. The "cause" attribute may be used to indicate one of the following application errors: – NETWORK_FAILURE – UPSTREAM_SERVER_ERROR – TIMED_OUT_REQUEST
NOTE 1: The mandatory HTTP error status code for the PUT method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. NOTE 2: RedirectResponse may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

Table 6.1.3.3.3.1-4: Headers supported by the PUT method on this resource

Name	Data type	P	Cardinality	Description
n/a

Table 6.1.3.3.3.1-5: Headers supported by the 200 response code on this resource

Name	Data type	P	Cardinality	Description
n/a

Table 6.1.3.3.3.1-6: Headers supported by the 307 Response Code on this endpoint

Name

Data type

Cardinality

Description

Location

string

URI pointing to the resource of another NF service producer to which the request should be sent.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

Table 6.1.3.3.3.1-7: Headers supported by the 308 Response Code on this endpoint

Name

Data type

Cardinality

Description

Location

string

URI pointing to the resource of another NF service producer to which the request should be sent.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

6.1.3.3.4 Resource Custom Operations

There is no Resource Custom Operations in the current version of this API.

6.1.4 Custom Operations without associated resources

6.1.4.1 Overview

There is no Custom Operation in the current version of this API.

6.1.5 Notifications

6.1.5.1 General

Notifications shall comply to clause 6.2 of 3GPP TS 29.500 [4] and clause 4.6.2.3 of 3GPP TS 29.501 [5].

Table 6.1.5.1-1: Notifications overview

Notification

Resource URI

HTTP method or custom operation

Description

(service operation)

Re-authentication Notification

{reauthNotifUri}

(NF Service Consumer provided callback reference)

POST

Re-authentication Notification

Revocation Notification

{revocNotifUri}

(NF Service Consumer provided callback reference)

POST

Revocation Notification

6.1.5.2 Re-authentication Notification

6.1.5.2.1 Description

The Re-authentication Notification is used by the NSSAAF to trigger the NF Service Consumer (i.e. the AMF) to re-initiate slice-specific authentication and authorization for a given UE.

6.1.5.2.2 Target URI

The Notification URI "{reauthNotifUri}" shall be used with the resource URI variables defined in table 6.1.5.2.2-1.

Table 6.1.5.2.2-1: Resource URI variables for this resource

Name	Definition
reauthNotifUri	String formatted as URI which carries the re-authentication notification URI.

6.1.5.2.3 Standard Methods

6.1.5.2.3.1 POST

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

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

Data type	P	Cardinality	Description
SliceAuthReauthNotification	M	1	SliceAuthReauthNotification which carries the re-authentication notification for a given UE.

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

Data type	P	Cardinality	Response codes	Description
n/a			204 No Content	Successful notification of the re-authentication.
RedirectResponse	O	0..1	307 Temporary Redirect	Temporary redirection. The NF service consumer shall generate a Location header field containing a URI pointing to the endpoint of another NF service consumer to which the notification should be sent. If an SCP redirects the message to another SCP then the location header field shall contain the same URI or a different URI pointing to the endpoint of the NF service consumer to which the notification should be sent. (NOTE 2)
RedirectResponse	O	0..1	308 Permanent Redirect	Permanent redirection. The NF service consumer shall generate a Location header field containing a URI pointing to the endpoint of another NF service consumer to which the notification should be sent. If an SCP redirects the message to another SCP then the location header field shall contain the same URI or a different URI pointing to the endpoint of the NF service consumer to which the notification should be sent. (NOTE 2)
NOTE 1: The mandatory HTTP error status codes for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. NOTE 2: RedirectResponse may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

Table 6.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	A URI pointing to the endpoint of NF service consumer to which the notification should be sent.

Table 6.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	A URI pointing to the endpoint of NF service consumer to which the notification should be sent.

6.1.5.3 Revocation Notification

6.1.5.3.1 Description

The Revocation Notification is used by the NSSAAF to trigger the NF Service Consumer (i.e. the AMF) to revoke the slice-specific authentication and authorization result for a given UE.

6.1.5.3.2 Target URI

The Notification URI "{revocNotifUri}" shall be used with the resource URI variables defined in table 6.1.5.3.2-1.

Table 6.1.5.3.2-1: Resource URI variables for this resource

Name	Definition
revocNotifUri	String formatted as URI which carries the revocation notification URI.

6.1.5.3.3 Standard Methods

6.1.5.3.3.1 POST

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

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

Data type	P	Cardinality	Description
SliceAuthRevocNotification	M	1	SliceAuthRevocNotification which carries the revocation notification for a given UE.

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

Data type	P	Cardinality	Response codes	Description
n/a			204 No Content	Successful notification of the revocation.
RedirectResponse	O	0..1	307 Temporary Redirect	Temporary redirection. The NF service consumer shall generate a Location header field containing a URI pointing to the endpoint of another NF service consumer to which the notification should be sent. If an SCP redirects the message to another SCP then the location header field shall contain the same URI or a different URI pointing to the endpoint of the NF service consumer to which the notification should be sent. (NOTE 2)
RedirectResponse	O	0..1	308 Permanent Redirect	Permanent redirection. The NF service consumer shall generate a Location header field containing a URI pointing to the endpoint of another NF service consumer to which the notification should be sent. If an SCP redirects the message to another SCP then the location header field shall contain the same URI or a different URI pointing to the endpoint of the NF service consumer to which the notification should be sent. (NOTE 2)
NOTE 1: The mandatory HTTP error status codes for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. NOTE 2: RedirectResponse may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

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

Name	Data type	P	Cardinality	Description
Location	string	M	1	A URI pointing to the endpoint of NF service consumer to which the notification should be sent.

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

Name	Data type	P	Cardinality	Description
Location	string	M	1	A URI pointing to the endpoint of NF service consumer to which the notification should be sent.

6.1.6 Data Model

6.1.6.1 General

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

Table 6.1.6.1-1 specifies the data types defined for the Nnssaaf service based interface protocol.

Table 6.1.6.1-1: Nnssaaf specific Data Types

Data type	Clause defined	Description	Applicability
SliceAuthInfo	6.1.6.2.2	Contains the GPSI, S-NSSAI, EAP ID Response, etc.
SliceAuthContext	6.1.6.2.3	Contains the information of the resource created for slice-specific authentication and authorization.
SliceAuthConfirmationData	6.1.6.2.4	Contains the EAP message from the UE for EAP process.
SliceAuthConfirmationResponse	6.1.6.2.5	Contains the slice-specific authentication and authorization result from the NSSAAF to the UE.
SliceAuthReauthNotification	6.1.6.2.6	Contains the re-authentication notification for slice-specific authentication and authorization.
SliceAuthRevocNotification	6.1.6.2.7	Contains the revocation notification for slice-specific authentication and authorization.
SliceAuthCxtId	6.1.6.3.2	Contains the resource ID of slice authentication context.
EapMessage	6.1.6.3.2	Contains the string formatted EAP message.
SliceNotificationType	6.1.6.3.3	Notification type of slice-specification authentication and authorization.

Table 6.1.6.1-2 specifies data types re-used by the Nnssaaf 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 Nnssaaf service based interface.

Table 6.1.6.1-2: Nnssaaf re-used Data Types

Data type	Reference	Comments	Applicability
ProblemDetails	3GPP TS 29.571 [10]	Common Data Type used in response bodies
RedirectResponse	3GPP TS 29.571 [10]	Redirect Response
Gpsi	3GPP TS 29.571 [10]	GPSI
Snssai	3GPP TS 29.571 [10]	S-NSSAI
AuthStatus	3GPP TS 29.571 [10]	Slice Authentication Status
Supi	3GPP TS 29.571 [10]	SUPI of the UE

6.1.6.2 Structured data types

The following clause defines the structures to be used in resource representations.

6.1.6.2.1 Introduction

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

6.1.6.2.2 Type: SliceAuthInfo

Table 6.1.6.2.2-1: Definition of type SliceAuthInfo

Attribute name	Data type	P	Cardinality	Description	Applicability
gpsi	Gpsi	M	1	Contains the GPSI of the UE.
snssai	Snssai	M	1	Contains the S-NSSAI for authentication.
eapIdRsp	EapMessage	M	1	Contains the EAP ID Responses message from the UE. If no EAP ID Responses message is received or requested, it shall contain the Null value.
amfInstanceId	NfInstanceId	O	0..1	This IE may be present, if the AMF determines to provide the re-authentication/revocation notification URI to the NSSAAF. When present, it shall contain the NF Instance Id of the AMF.
reauthNotifUri	Uri	O	0..1	This IE may be present, e.g. if the AMF determines the UE with low mobility characteristic. When present, it shall contain the re-authentication notification URI.
revocNotifUri	Uri	O	0..1	This IE may be present, e.g. if the AMF determines the UE with low mobility characteristic. When present, it shall contain the revocation notification URI.

6.1.6.2.3 Type: SliceAuthContext

Table 6.1.6.2.3-1: Definition of type SliceAuthContext

Attribute name	Data type	P	Cardinality	Description	Applicability
gpsi	Gpsi	M	1	Contains the GPSI of the UE.
snssai	Snssai	M	1	Contains the S-NSSAI for authentication.
authCtxId	SliceAuthCtxId	M	1	Indicates the resource ID uniquely identifying the slice authentication context, generated by the NSSAAF.
eapMessage	EapMessage	M	1	Contains the EAP message to be sent to the UE.

6.1.6.2.4 Type: SliceAuthConfirmationData

Table 6.1.6.2.4-1: Definition of type SliceAuthConfirmationData

Attribute name	Data type	P	Cardinality	Description	Applicability
gpsi	Gpsi	M	1	Contains the GPSI of the UE.
snssai	Snssai	M	1	Contains the S-NSSAI for authentication.
eapMessage	EapMessage	M	1	Contains the EAP message received from the UE.

6.1.6.2.5 Type: SliceAuthConfirmationResponse

Table 6.1.6.2.5-1: Definition of type SliceAuthConfirmationResponse

Attribute name	Data type	P	Cardinality	Description	Applicability
gpsi	Gpsi	M	1	Contains the GPSI of the UE.
snssai	Snssai	M	1	Contains the S-NSSAI for authentication.
eapMessage	EapMessage	M	1	Contains the EAP success/failure message needs to be sent to the UE.
authResult	AuthStatus	O	0..1	When present, it shall indicate the result of slice-specific authentication and authorization.

6.1.6.2.6 Type: SliceAuthReauthNotification

Table 6.1.6.2.6-1: Definition of type SliceAuthReauthNotification

Attribute name	Data type	P	Cardinality	Description	Applicability
notificationType	SliceAuthNotificationType	M	1	Indicate the type of slice authentication notification.
gpsi	Gpsi	M	1	Contains the GPSI of the UE.
snssai	Snssai	M	1	Contains the S-NSSAI for authentication.
supi	Supi	C	0..1	This IE should be sent by the NSSAAF to the AMF, if available.

6.1.6.2.7 Type: SliceAuthRevocNotification

Table 6.1.6.2.7-1: Definition of type SliceAuthRevocNotification

Attribute name	Data type	P	Cardinality	Description	Applicability
notificationType	SliceAuthNotificationType	M	1	Indicate the type of slice authentication notification.
gpsi	Gpsi	M	1	Contains the GPSI of the UE.
snssai	Snssai	M	1	Contains the S-NSSAI for authentication.
supi	Supi	C	0..1	This IE should be sent by the NSSAAF to the AMF, if available.

6.1.6.3 Simple data types and enumerations

6.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.

6.1.6.3.2 Simple data types

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

Table 6.1.6.3.2-1: Simple data types

Type Name

Type Definition

Description

Applicability

SliceAuthCtxId

string

The resource ID uniquely identifying the slice authentication context, generated by the NSSAAF.

EapMessage

string

The EAP packet is encoded using base64 (see IETF RFC 4648 [14]) and represented as a String.

Format: byte

6.1.6.3.3 Enumeration: SliceAuthNotificationType

The enumeration SliceAuthNotificationType represents the notification type of slice-specific authentication and authorization. It shall comply with the provisions defined in table 6.1.6.3.3-1.

Table 6.1.6.3.3-1: Enumeration SliceAuthNotificationType

Enumeration value	Description	Applicability
SLICE_RE_AUTH	This value is used to indicate the re-authentication is needed
SLICE_REVOCATION	This value is used to indicate the previous slice-specific authentication and authorization shall be revoked.

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

There is no alternative data types defined in this specification.

6.1.6.5 Binary data

There is no binary data type defined in this specification.

6.1.7 Error Handling

6.1.7.1 General

For the Nnssaaf_NSSAA API, HTTP error responses shall be supported as specified in clause 4.8 of 3GPP TS 29.501 [5]. Protocol errors and application errors specified in table 5.2.7.2-1 of 3GPP TS 29.500 [4] shall be supported for an HTTP method if the corresponding HTTP status codes are specified as mandatory for that HTTP method in table 5.2.7.1-1 of 3GPP TS 29.500 [4].

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

6.1.7.2 Protocol Errors

No specific procedures for the Nnssaaf_NSSAA service are specified.

6.1.7.3 Application Errors

The application errors defined for the Nnssaaf_NSSAA service are listed in Table 6.1.7.3-1.

Table 6.1.7.3-1: Application errors

Application Error	HTTP status code	Description
RESOURCE_TEMP_MOVED	307 Temporary Redirect	Indicates that the NSSAAF is not able to handle the request, but points to the URI of another NSSAAF.
RESOURCE_MOVED	308 Permanent Redirect	Indicates that the NSSAAF is not able to handle the request, but points to the URI of another NSSAAF.
SLICE_AUTH_REJECTED	403 Forbidden	The user cannot be authenticated, e.g. authentication request rejected by the AAA-S.
CONTEXT_NOT_FOUND	404 Not Found	The NSSAAF cannot find the resource corresponding to the URI provided by the NF Service Consumer, i.e. the resource identified by the authCtxId does not exist in the NSSAAF.
USER_NOT_FOUND	404 Not Found	The user does not exist in the HPLMN.
UPSTREAM_SERVER_ERROR	504 Gateway Timeout	Error happens in reaching the remote peer (i.e. the AAA-S).
NETWORK_FAILURE	504 Gateway Timeout	The request is rejected due to a network problem.
TIMED_OUT_REQUEST	504 Gateway Timeout	No response is received from the remote peer (i.e. the AAA-S) when time out.

6.1.8 Feature negotiation

The optional features in table 6.1.8-1 are defined for the Nnssaaf_NSSAA API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].

Table 6.1.8-1: Supported Features

Feature number	Feature Name	Description

6.1.9 Security

As indicated in 3GPP TS 33.501 [8] and 3GPP TS 29.500 [4], the access to the Nnssaaf_NSSAA API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [9]), based on local configuration, using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [10]) plays the role of the authorization server.

If OAuth2 is used, an NF Service Consumer, prior to consuming services offered by the Nnssaaf_NSSAA API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [10], clause 5.4.2.2.

NOTE: When multiple NRFs are deployed in a network, the NRF used as authorization server is the same NRF that the NF Service Consumer used for discovering the Nnssaaf_NSSAA service.

The Nnssaaf_NSSAA API defines a single scope "nnssaaf-nssaa" for the entire service, and it does not define any additional scopes at resource or operation level.

6.2 Nnssaaf_AIW Service API

6.2.1 Introduction

The Nnssaaf_AIW service shall use the Nnssaaf_AIW API.

The API URI of the Nnssaaf_AIW API shall be:

{apiRoot}/<apiName>/<apiVersion>

The request URIs used in HTTP request from the NF service consumer towards the NF service producer shall have the Resource URI structure defined in clause 4.4.1 of 3GPP TS 29.501 [5], i.e.:

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

with the following components:

– The {apiRoot} shall be set as described in 3GPP TS 29.501 [5].

– The <apiName> shall be "nnssaaf-aiw".

– The <apiVersion> shall be "v1".

– The <apiSpecificResourceUriPart> shall be set as described in clause 6.2.3.

6.2.2 Usage of HTTP

6.2.2.1 General

HTTP/2, IETF RFC 7540 [11], shall be used as specified in clause 5 of 3GPP TS 29.500 [4].

HTTP/2 shall be transported as specified in clause 5.3 of 3GPP TS 29.500 [4].

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

6.2.2.2 HTTP standard headers

6.2.2.2.1 General

See clause 5.2.2 of 3GPP TS 29.500 [4] for the usage of HTTP standard headers.

6.2.2.2.2 Content type

6.2.2.3 HTTP custom headers

The mandatory HTTP custom header fields specified in clause 5.2.3.2 of 3GPP TS 29.500 [4] shall be applicable.

6.2.3 Resources

6.2.3.1 Overview

The structure of the Resource URIs of the Nnssaaf_AIW service is shown in Figure 6.2.3.1-1

Figure 6.2.3.1-1: Resource URI structure of the AIW API

Table 6.2.3.1-1 provides an overview of the resources and applicable HTTP methods.

Table 6.2.3.1-1: Resources and methods overview

Resource name

Resource URI

HTTP method or custom operation

Description

authentications

(Collection)

/authentications

POST

Initiate the authentication and authorization process by providing inputs related to the UE.

authentication

(Document)

/authentications/{authCtxId}

PUT

Put the UE response from the EAP process.

6.2.3.2 Resource: authentications (Collection)

6.2.3.2.1 Description

This resource represents a collection of the authentication resources generated by the NSSAAF.

6.2.3.2.2 Resource Definition

Resource URI: {apiRoot}/nnssaaf-aiw/<apiVersion>/authentications

This resource shall support the resource URI variables defined in table 6.2.3.2.2-1.

Table 6.2.3.2.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	See clause 6.2.1
apiVersion	string	See clause 6.2.1

6.2.3.2.3 Resource Standard Methods

6.2.3.2.3.1 POST

This method shall support the URI query parameters specified in table 6.2.3.2.3.1-1.

Table 6.2.3.2.3.1-1: URI query parameters supported by the POST method on this resource

Name	Data type	P	Cardinality	Description	Applicability
n/a

This method shall support the request data structures specified in table 6.2.3.2.3.1-2 and the response data structures and response codes specified in table 6.2.3.2.3.1-3.

Table 6.2.3.2.3.1-2: Data structures supported by the POST Request Body on this resource

Data type	P	Cardinality	Description
AuthInfo	M	1	Contains the SUPI, EAP ID Response from the UE, etc.

Table 6.2.3.2.3.1-3: Data structures supported by the POST Response Body on this resource

Data type	P	Cardinality	Response codes	Description
AuthContext	M	1	201 Created	This case indicates the corresponding resource has been created by the NSSAAF for the requested authentication and authorization, and further EAP process is required. The HTTP response shall include a "Location" header that contains the resource URI of the created resource.
RedirectResponse	O	0..1	307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing a different URI, or the same URI if this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same NSSAAF or NSSAAF (service) set. (NOTE 2)
RedirectResponse	O	0..1	308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing a different URI, or the same URI if this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same NSSAAF or NSSAAF (service) set. (NOTE 2)
ProblemDetails	O	0..1	400 Bad Request	This case represents the failure to start authentication and authorization because of input parameter error.
ProblemDetails	O	0..1	403 Forbidden	This case represents when the UE is not allowed to be authenticated.
ProblemDetails	O	0..1	404 Not Found	This case represents the user or user context is not found. The "cause" attribute may be used to indicate one of the following application errors: – CONTEXT_NOT_FOUND – USER_NOT_FOUND
ProblemDetails	O	0..1	504 Gateway Time out	This case represents network error or remote peer (i.e. AAA-S) error, e.g. not reachable, no response and time out. The "cause" attribute may be used to indicate one of the following application errors: – NETWORK_FAILURE – UPSTREAM_SERVER_ERROR – TIME_OUT_REQUEST
NOTE 1: The mandatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. NOTE 2: RedirectResponse may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

Table 6.2.3.2.3.1-4: Headers supported by the POST method on this resource

Name	Data type	P	Cardinality	Description
n/a

Table 6.2.3.2.3.1-5: Headers supported by the 201 response code on this resource

Name

Data type

Cardinality

Description

Location

URI

URI of created resource for the authentication context.

The URI structure is defined in clause 6.2.3.3.1.

Table 6.2.3.2.3.1-6: Headers supported by the 307 Response Code on this endpoint

Name

Data type

Cardinality

Description

Location

string

URI pointing to the resource of another NF service producer to which the request should be sent.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

Table 6.2.3.2.3.1-7: Headers supported by the 308 Response Code on this endpoint

Name

Data type

Cardinality

Description

Location

string

URI pointing to the resource of another NF service producer to which the request should be sent.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

6.2.3.3 Resource: authentication (Document)

6.2.3.3.1 Description

The sub-resource "authentication" is generated by the NSSAAF. This subresource should not persist after the authentication and authorization process finishes.

6.2.3.3.2 Resource Definition

Resource URI: {apiRoot}/nnssaaf-aiw/<apiVersion>/authentications/{authCtxId}

This resource shall support the resource URI variables defined in table 6.2.3.3.2-1.

Table 6.2.3.3.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	See clause 6.2.1
apiVersion	string	See clause 6.2.1
authCtxId	string	The authentication context ID, which is of data type AuthCtxId defined in clause 6.2.6.3.2.

6.2.3.3.3 Resource Standard Methods

6.2.3.3.3.1 PUT

This method shall support the URI query parameters specified in table 6.2.3.3.3.1-1.

Table 6.2.3.3.3.1-1: URI query parameters supported by the PUT method on this resource

Name	Data type	P	Cardinality	Description	Applicability
n/a

This method shall support the request data structures specified in table 6.2.3.3.3.1-2 and the response data structures and response codes specified in table 6.2.3.3.3.1-3.

Table 6.2.3.3.3.1-2: Data structures supported by the PUT Request Body on this resource

Data type	P	Cardinality	Description
AuthConfirmationData	M	1	Contains the EAP message generated by the UE and provided to the AUSF.

Table 6.2.3.3.3.1-3: Data structures supported by the PUT Response Body on this resource

Data type	P	Cardinality	Response codes	Description
AuthConfirmationResponse	M	1	200 OK	This case indicates that the NSSAAF has performed the authentication. The response body shall contain the result of the authentication and authorization.
RedirectResponse	O	0..1	307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing a different URI, or the same URI if this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same NSSAAF or NSSAAF (service) set. (NOTE 2)
RedirectResponse	O	0..1	308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing a different URI, or the same URI if this is a redirection triggered by an SCP to the same target resource via another SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same NSSAAF or NSSAAF (service) set. (NOTE 2)
ProblemDetails	O	0..1	400 Bad Request	This case represents an authentication failure because of input parameter error. This indicates that the NSSAAF was not able to process the authentication.
ProblemDetails	O	0..1	403 Forbidden	This case represents when the UE is not allowed to be authenticated.
ProblemDetails	O	0..1	404 Not Found	This case represents the UE or UE related context is not found. The "cause" attribute may be used to indicate one of the following application errors: – CONTEXT_NOT_FOUND – USER_NOT_FOUND
ProblemDetails	O	0..1	504 Gateway Time out	This case represents network error or remote peer (i.e. AAA-S) error, e.g. not reachable, no response when time out. The "cause" attribute may be used to indicate one of the following application errors: – NETWORK_FAILURE – UPSTREAM_SERVER_ERROR – TIMED_OUT_REQUEST
NOTE 1: The mandatory HTTP error status code for the PUT method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. NOTE 2: RedirectResponse may be inserted by an SCP, see clause 6.10.9.1 of 3GPP TS 29.500 [4].

Table 6.2.3.3.3.1-4: Headers supported by the PUT method on this resource

Name	Data type	P	Cardinality	Description
n/a

Table 6.2.3.3.3.1-5: Headers supported by the 200 response code on this resource

Name	Data type	P	Cardinality	Description
n/a

Table 6.2.3.3.3.1-6: Headers supported by the 307 Response Code on this endpoint

Name

Data type

Cardinality

Description

Location

string

URI pointing to the resource of another NF service producer to which the request should be sent.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

Table 6.2.3.3.3.1-7: Headers supported by the 308 Response Code on this endpoint

Name

Data type

Cardinality

Description

Location

string

URI pointing to the resource of another NF service producer to which the request should be sent.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

6.2.4 Custom Operations without associated resources

There are no Custom Operation in the current version of this API.

6.2.5 Notifications

There are no Notifications in the current version of this API.

6.2.6 Data Model

6.2.6.1 General

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

Table 6.2.6.1-1 specifies the data types defined for the Nnssaaf service based interface protocol.

Table 6.2.6.1-1: Nnssaaf_AIW specific Data Types

Data type	Clause defined	Description	Applicability
AuthInfo	6.2.6.2.2	Contains the SUPI, EAP ID Response, etc.
AuthContext	6.2.6.2.3	Contains the information of the resource created for authentication and authorization.
AuthConfirmationData	6.2.6.2.4	Contains the EAP message from the UE for EAP process.
AuthConfirmationResponse	6.2.6.2.5	Contains the authentication and authorization result from the NSSAAF to the UE.
AuthCxtId	6.2.6.3.2	Contains the resource ID of authentication context.

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

Table 6.2.6.1-2: Nnssaaf re-used Data Types

Data type	Reference	Comments	Applicability
ProblemDetails	3GPP TS 29.571 [10]	Common Data Type used in response bodies
RedirectResponse	3GPP TS 29.571 [10]	Redirect Response
AuthStatus	3GPP TS 29.571 [10]	Authentication Status
Supi	3GPP TS 29.571 [10]	SUPI of the UE
SupportedFeatures	3GPP TS 29.571 [10]	Supported Features
ServerAddressingInfo	3GPP TS 29.571 [10]	Addressing information (FQNDs and/or IP addresses) of a server.
EapMessage	3GPP TS 29.526	See clause 6.1.6.3.2
Msk	3GPP TS 29.509 [18]	See clause 6.1.6.3.2

6.2.6.2 Structured data types

6.2.6.2.1 Introduction

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

6.2.6.2.2 Type: AuthInfo

Table 6.2.6.2.2-1: Definition of type AuthInfo

Attribute name	Data type	P	Cardinality	Description	Applicability
supi	Supi	M	1	Contains the SUPI of the UE.
eapIdRsp	EapMessage	C	0..1	Contains the EAP Identity Response message. (NOTE)
ttlsInnerMethodContainer	EapMessage	C	0..1	Contains the EAP-TTLS inner method messages. It is included when EAP-TTLS is used, after the initial EAP-TLS exchange. (NOTE)
supportedFeatures	SupportedFeatures	C	0..1	This IE shall be present if at least one optional feature defined in clause 6.2.9 is supported.
NOTE: Either eapIdRsp or ttlsInnerMethodContainer shall be present, but not both.

6.2.6.2.3 Type: AuthContext

Table 6.2.6.2.3-1: Definition of type AuthContext

Attribute name	Data type	P	Cardinality	Description	Applicability
supi	Supi	M	1	Contains the SUPI of the UE.
authCtxId	AuthCtxId	M	1	Indicates the resource ID uniquely identifying the authentication context, generated by the NSSAAF.
eapMessage	EapMessage	C	0..1	Contains the EAP message to be sent to the UE. (NOTE)
ttlsInnerMethodContainer	EapMessage	C	0..1	Contains the EAP-TTLS inner method messages. It is included when EAP-TTLS is used, after the initial EAP exchange. (NOTE)
supportedFeatures	SupportedFeatures	C	0..1	This IE shall be present if at least one optional feature defined in clause 6.2.9 is supported.
NOTE: Either eapIdRsp or ttlsInnerMethodContainer shall be present, but not both.

6.2.6.2.4 Type: AuthConfirmationData

Table 6.2.6.2.4-1: Definition of type AuthConfirmationData

Attribute name	Data type	P	Cardinality	Description	Applicability
supi	Supi	M	1	Contains the SUPI of the UE.
eapMessage	EapMessage	M	1	Contains the EAP message received from the UE.
supportedFeatures	SupportedFeatures	C	0..1	This IE shall be present if at least one optional feature defined in clause 6.2.9 is supported.

6.2.6.2.5 Type: AuthConfirmationResponse

Table 6.2.6.2.5-1: Definition of type AuthConfirmationResponse

Attribute name	Data type	P	Cardinality	Description	Applicability
supi	Supi	M	1	Contains the SUPI of the UE.
eapMessage	EapMessage	M	1	Contains the EAP success/failure message needs to be sent to the UE.
authResult	AuthStatus	O	0..1	When present, it shall indicate the result of authentication and authorization.
pvsInfo	array(ServerAddressingInfo)	O	1..N	When present, it shall contain the FQDN(s) and/or IP address(es) of the SNPN UE onboarding Provisioning Servers.
msk	Msk	C	0..1	This IE shall be present if MSK is received from AAA-S after successful authentication, as specified in clause I.2.2.2 of 3GPP TS 33.501 [8].
supportedFeatures	SupportedFeatures	C	0..1	This IE shall be present if at least one optional feature defined in clause 6.2.9 is supported.

6.2.6.3 Simple data types and enumerations

6.2.6.3.1 Introduction

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

6.2.6.3.2 Simple data types

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

Table 6.2.6.3.2-1: Simple data types

Type Name	Type Definition	Description	Applicability
AuthCtxId	string	The resource ID uniquely identifying the authentication context, generated by the NSSAAF.

6.2.7 Error Handling

6.2.7.1 General

For the Nnssaaf_AIW API, HTTP error responses shall be supported as specified in clause 4.8 of 3GPP TS 29.501 [5]. Protocol errors and application errors specified in table 5.2.7.2-1 of 3GPP TS 29.500 [4] shall be supported for an HTTP method if the corresponding HTTP status codes are specified as mandatory for that HTTP method in table 5.2.7.1-1 of 3GPP TS 29.500 [4].

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

6.2.7.2 Protocol Errors

No specific procedures for the Nnssaaf_AIW service are specified.

6.2.7.3 Application Errors

The application errors defined for the Nnssaaf_AIW service are listed in Table 6.2.7.3-1.

Table 6.2.7.3-1: Application errors

Application Error	HTTP status code	Description
RESOURCE_TEMP_MOVED	307 Temporary Redirect	Indicates that the NSSAAF is not able to handle the request, but points to the URI of another NSSAAF.
RESOURCE_MOVED	308 Permanent Redirect	Indicates that the NSSAAF is not able to handle the request, but points to the URI of another NSSAAF.
CONTEXT_NOT_FOUND	404 Not Found	The NSSAAF cannot find the resource corresponding to the URI provided by the NF Service Consumer, i.e. the resource identified by the authCtxId does not exist in the NSSAAF.
USER_NOT_FOUND	404 Not Found	The user does not exist.
UPSTREAM_SERVER_ERROR	504 Gateway Timeout	Error happens in reaching the remote peer (i.e., the AAA-S).
NETWORK_FAILURE	504 Gateway Timeout	The request is rejected due to a network problem.
TIMED_OUT_REQUEST	504 Gateway Timeout	No response is received from the remote peer (i.e., the AAA-S) when time out.

6.2.8 Feature negotiation

The optional features in table 6.2.8-1 are defined for the Nnssaaf_AIW API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].

Table 6.2.8-1: Supported Features

Feature number	Feature Name	Description

6.2.9 Security

As indicated in 3GPP TS 33.501 [8] and 3GPP TS 29.500 [4], the access to the Nnssaaf_AIW API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [9]), based on local configuration, using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [10]) plays the role of the authorization server.

If OAuth2 is used, an NF Service Consumer, prior to consuming services offered by the Nnssaaf_AIW API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [10], clause 5.4.2.2.

NOTE: When multiple NRFs are deployed in a network, the NRF used as authorization server is the same NRF that the NF Service Consumer used for discovering the Nnssaaf_AIW service.

The Nnssaaf_AIW API defines a single scope "nnssaaf-aiw" for the entire service, and it does not define any additional scopes at resource or operation level.

Annex A (normative):
OpenAPI specification