6.6 Nudm_NIDDAuthorization Service API
29.5033GPP5G SystemRelease 18Stage 3TSUnified Data Management Services
6.6.1 API URI
The Nudm_NIDDAuthorization service shall use the Nudm_NIDDAU API.
The API URI of the Nudm_NIDDAU API shall be:
{apiRoot}/<apiName>/<apiVersion>
The request URI used in HTTP request from the NF service consumer towards the NF service producer shall have the 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 "nudm-niddau".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in clause 6.6.3.
6.6.2 Usage of HTTP
6.6.2.1 General
HTTP/2, as defined in IETF RFC 7540 [13], 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].
HTTP messages and bodies for the Nudm_NIDDAuthorization service shall comply with the OpenAPI [14] specification contained in Annex A.7.
6.6.2.2 HTTP standard headers
6.6.2.2.1 General
The usage of HTTP standard headers shall be supported as specified in clause 5.2.2 of 3GPP TS 29.500 [4].
6.6.2.2.2 Content type
The following content types shall be supported:
JSON, as defined in IETF RFC 8259 [15], signalled by the content type "application/json".
The Problem Details JSON Object (IETF RFC 7807 [16] signalled by the content type "application/problem+json"
6.6.2.3 HTTP custom headers
6.6.2.3.1 General
The usage of HTTP custom headers shall be supported as specified in clause 5.2.3 of 3GPP TS 29.500 [4].
6.6.3 Resources
6.6.3.1 Overview
This clause describes the structure for the Resource URIs and the resources and methods used for the service.
Figure 6.6.3.1-1 depicts the resource URIs structure for the Nudm_NIDDAU API.
Figure 6.6.3.1-1: Resource URI structure of the Nudm-NIDDAU API
Table 6.6.3.1-1 provides an overview of the resources and applicable HTTP methods.
Table 6.6.3.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
ueIdentity |
/{ueIdentity}/authorize |
authorize (POST) |
Authorize the NIDD configuration request. |
6.6.3.2 Resource: ueIdentity (Document)
6.6.3.2.1 Description
This resource represents the UE’s subscribed NIDD authorization information for a GPSI or External Group Identifier.
6.6.3.2.2 Resource Definition
Resource URI: {apiRoot}/nudm-niddau/<apiVersion>/{ueIdentity}
This resource shall support the resource URI variables defined in table 6.6.3.2.2-1.
Table 6.6.3.2.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 6.6.1 |
|
ueIdentity |
string |
Represents the GPSI or External Group Identifier (see 3GPP TS 23.501 [2] clause 7.2.5) |
6.6.3.2.3 Resource Standard Methods
No Standard Methods are supported for this resource.
6.6.3.2.4 Resource Custom Operations
6.6.3.2.4.1 Overview
Table 6.6.3.2.4.1-1: Custom operations
|
Operation Name |
Custom operation URI |
Mapped HTTP method |
Description |
|
authorize |
/authorize |
POST |
Authorize the NIDD configuration request. |
6.6.3.2.4.2 Operation: authorize
6.6.3.2.4.2.1 Description
This custom operation is used by the NF service consumer (NEF) to request UDM to authorize the NIDD configuration request for the GPSI/External Group Identifier.
6.6.3.2.4.2.2 Operation Definition
This operation shall support the request data structures specified in table 6.6.3.2.4.2.2-1 and the response data structure and response codes specified in table 6.6.3.2.4.2.2-2.
Table 6.6.3.2.4.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
AuthorizationInfo |
M |
1 |
Contains S-NSSAI, DNN, MTC Provider Information, callback URI. |
Table 6.6.3.2.4.2.2-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
AuthorizationData |
M |
1 |
200 OK |
Upon success, a response body containing the SUPI(s) and GPSI shall be returned. |
|
ProblemDetails |
O |
1 |
404 Not Found |
The "cause" attribute may be used to indicate one of the following application errors: – USER_NOT_FOUND |
|
ProblemDetails |
O |
0..1 |
403 Forbidden |
The "cause" attribute may be used to indicate one of the following application errors: – DNN_NOT_ALLOWED – MTC_PROVIDER_NOT_ALLOWED – AF_INSTANCE_NOT_ALLOWED – SNSSAI_NOT_ALLOWED |
|
NOTE: In addition common data structures as listed in table 5.2.7.1-1 of 3GPP TS 29.500 [4] are supported. |
||||
6.6.4 Custom Operations without associated resources
In this release of this specification, no custom operations without associated resources are defined for the Nudm_SubscriberDataManagement Service.
6.6.5 Notifications
6.6.5.1 General
This clause will specify the use of notifications and corresponding protocol details if required for the specific service. When notifications are supported by the API, it will include a reference to the general description of notifications support over the 5G SBIs specified in 3GPP TS 29.500 [4] / 3GPP TS 29.501 [5].
Table 6.6.5.1-1: Notifications overview
|
Notification |
Resource URI |
HTTP method or custom operation |
Description (service operation) |
|
Authorization Data Update Notification |
{authUpdateCallbackUri} |
POST |
6.6.5.2 Nidd Authorization Data Update Notification
The POST method shall be used for Nidd Authorization Data Update Notifications and the Call-back URI shall be provided during the NIDD Authorization Data Retrieval procedure. UDM should continuously generate NIDD authorization Data Update Notifications to service consumer (NEF) for UE for the event until validity time related to the UE expires, and if validity time expires, it indicates unsubscription to notification for the UE.
Resource URI: {authUpdateCallbackUri}
Support of URI query parameters is specified in table 6.6.5.2-1.
Table 6.6.5.2-1: URI query parameters supported by the POST method
|
Name |
Data type |
P |
Cardinality |
Description |
|
n/a |
Support of request data structures is specified in table 6.6.5.2-2 and of response data structures and response codes is specified in table 6.6.5.2-3.
Table 6.1.5.2-2: Data structures supported by the POST Request Body
|
Data type |
P |
Cardinality |
Description |
|
NiddAuthUpdateNotification |
M |
1 |
Table 6.6.5.2-3: Data structures supported by the POST Response Body
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
204 No Content |
Upon success, an empty response body shall be returned. |
||
|
NOTE: In addition common data structures as listed in table 6.6.7-1 are supported. |
||||
6.6.6 Data Model
6.6.6.1 General
This clause specifies the application data model supported by the API.
Table 6.6.6.1-1 specifies the structured data types defined for the Nudm_NIDDAU service API. For simple data types defined for the Nudm_NIDDAU service API see table 6.6.6.3.2-1.
Table 6.6.6.1-1: Nudm_NIDDAU specific Data Types
|
Data type |
Clause defined |
Description |
|
AuthorizationData |
6.6.6.2.2 |
|
|
UserIdentifier |
6.6.6.2.3 |
|
|
NiddAuthUpdateInfo |
6.6.6.2.4 |
|
|
NiddAuthUpdateNotification |
6.6.6.2.5 |
|
|
AuthorizationInfo |
6.6.6.2.6 |
|
|
NiddCause |
6.6.6.3.3 |
Table 6.6.6.1-2 specifies data types re-used by the Nudm_NIDDAU service API from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Nudm_NIDDAU service API.
Table 6.6.6.1-2: Nudm_NIDDAU re-used Data Types
|
Data type |
Reference |
Comments |
|
Nssai |
6.1.6.2.2 |
Network Slice Selection Assistance Information |
|
Gpsi |
3GPP TS 29.571 [7] |
Generic Public Subscription Identifier |
|
Supi |
3GPP TS 29.571 [7] |
|
|
Dnn |
3GPP TS 29.571 [7] |
Data Network Name with Network Identifier only. |
|
MtcProviderInformation |
3GPP TS 29.571 [7] |
|
|
DateTime |
3GPP TS 29.571 [7] |
|
|
Snssai |
3GPP TS 29.571 [7] |
|
|
Uri |
3GPP TS 29.571 [7] |
|
|
NefId |
3GPP TS 29.510 [19] |
NEF ID |
6.6.6.2 Structured data types
6.6.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
6.6.6.2.2 Type: AuthorizationData
Table 6.6.6.2.2-1: Definition of type AuthorizationData
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
authorizationData |
array(UserIdentifier) |
M |
1..N |
May contain a single value or list of (SUPI and GPSI). Contains unique items. |
|
validityTime |
DateTime |
O |
0..1 |
Indicates the granted validity time of the authorisation result. If absent, it indicates the authorisation result is valid permanently |
6.6.6.2.3 Type: UserIdentifier
Table 6.6.6.2.3-1: Definition of type UserIdentifier
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
supi |
Supi |
M |
1 |
|
|
gpsi |
Gpsi |
O |
0..1 |
|
|
validityTime |
DateTime |
O |
0..1 |
Indicates the granted validity time of the authorisation result for this user. If absent, the value of the validity time in the AuthorizationData is used for this user if it is present in AuthorizationData. If present, this value has higher priority than the value in the AuthorizationData. |
6.6.6.2.4 Type: NiddAuthUpdateInfo
Table 6.6.6.2.4-1: Definition of type NiddAuthUpdateInfo
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
authorizationData |
AuthorizationData |
M |
1 |
This IE shall include the Authorization data. |
|
invalidityInd |
boolean |
O |
0..1 |
Indicates whether the authorized NIDD authoration data is still valid or not. true: the authorized NIDD authoration data is not valid. false or absent: the authorized NIDD authoration data is valid. |
|
snssai |
Snssai |
O |
0..1 |
Indicates Single Network Slice Selection Assistance Information for NIDD authorization. When absent it indicates authorization for all subscribed S-NSSAIs. |
|
dnn |
Dnn |
O |
0..1 |
Indicates DNN for NIDD authorization, shall contain the Network Identifier only. When absent it indicates authorization for all subscribed DNNs. |
|
niddCause |
NiddCause |
O |
0..1 |
NIDD Cause |
6.6.6.2.5 Type: NiddAuthUpdateNotification
Table 6.6.6.2.5-1: Definition of type NiddAuthUpdateNotification
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
niddAuthUpdateInfoList |
array(NiddAuthUpdateInfo) |
M |
1..N |
List of NiddAuthUpdateInfo. |
6.6.6.2.6 Type: AuthorizationInfo
Table 6.6.6.2.6-1: Definition of type AuthorizationInfo
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
snssai |
Snssai |
M |
1 |
Indicates Single Network Slice Selection Assistance Information for NIDD authorization. |
|
dnn |
Dnn |
M |
1 |
Indicates DNN for NIDD authorization, shall contain the Network Identifier only. |
|
mtcProviderInformation |
MtcProviderInformation |
M |
1 |
Indicates MTC provider information for NIDD authorization. (NOTE) |
|
authUpdateCallbackUri |
Uri |
M |
1 |
A URI provided by NEF to receive (implicitly subscribed) notifications on authorization data update. The authUpdateCallbackUri URI shall have unique information within NEF to identify the authorized result. |
|
afId |
string |
O |
0..1 |
When present, indicates the string identifying the originating AF, which is carried in {scsAsId} URI variable in resource URIs on T8/N33 interface (see clause 5 of 3GPP TS 29.122 [45]) or in {afId} URI variable in resource URIs on N33 interface (see clause 5 of 3GPP TS 29.522 [54]). |
|
nefId |
NefId |
O |
0..1 |
When present, this IE shall contain the ID of the requesting NEF. The UDM shall update the NIDD NEF ID for the DNN and Slice in corresponding subscription data after successful NIDD authorization, as specified in clause 4.25.3 of 3GPP TS 23.502 [3]. |
|
validityTime |
DateTime |
O |
0..1 |
Indicates the granted validity time of the authorisation result. If absent, it indicates the authorisation result is valid permanently |
|
contextInfo |
ContextInfo |
O |
0..1 |
This IE if present may contain e.g. the headers received by the UDM along with the Authorization Data Retrieval request. Shall be absent on Nudm and may be present on Nudr. |
|
NOTE: When the service operation is originated by external AF via T8/N33 interface, information carried in mtcProviderId attribute in NiddConfiguration structured data type (see clause 5.6.2.1.2 of 3GPP TS 29.122 [45]) can be used as the value for this IE. If the value is not received via T8/N33, the value for the mtcProviderInformation attribute shall be the empty string. |
||||
6.6.6.3 Simple data types and enumerations
6.6.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.6.6.3.2 Simple data types
The simple data types defined in table 6.6.6.3.2-1 shall be supported.
Table 6.6.6.3.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
6.6.6.3.3 Enumeration: NiddCause
Table 6.6.6.3.3-1: Enumeration NiddCause
|
Enumeration value |
Description |
|
"SUBSCRIPTION_WITHDRAWAL" |
Subscription Withdrawal |
|
"DNN_REMOVED" |
DNN used for NIDD service is removed from the UE subscription |
6.6.7 Error Handling
6.6.7.1 General
HTTP error handling shall be supported as specified in clause 5.2.4 of 3GPP TS 29.500 [4].
6.6.7.2 Protocol Errors
Protocol errors handling shall be supported as specified in clause 5.2.7 of 3GPP TS 29.500 [4].
6.6.7.3 Application Errors
The common application errors defined in the Table 5.2.7.2-1 in 3GPP TS 29.500 [4] may also be used for the Nudm_NIDD Authorization service. The following application errors listed in Table 6.6.7.3-1 are specific for the Nudm_NIDD Authorization service.
Table 6.6.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
|
UNKNOWN_5GS_SUBSCRIPTION |
403 Forbidden |
No 5GS subscription is associated with the user. |
|
USER_NOT_FOUND |
404 Not Found |
The user does not exist in the HPLMN |
|
DNN_NOT_ALLOWED |
403 Forbidden |
DNN not authorized for the user |
|
MTC_PROVIDER_NOT_ALLOWED |
403 Forbidden |
MTC Provider not authorized |
|
AF_INSTANCE_NOT_ALLOWED |
403 Forbidden |
This AF instance is not authorized |
|
SNSSAI_NOT_ALLOWED |
403 Forbidden |
This SNSSAI is not authorized to this user |
|
DATA_NOT_FOUND |
404 Not Found |
There is no valid authorization data for the UE |
6.6.8 Feature Negotiation
The optional features in table 6.6.8-1 are defined for the Nudm_NIDDAU API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].
Table 6.6.8-1: Supported Features
|
Feature number |
Feature Name |
Description |
6.6.9 Security
As indicated in 3GPP TS 33.501 [6] and 3GPP TS 29.500 [4], the access to the Nudm_NIDDAU API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [18]), based on local configuration, using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [19]) plays the role of the authorization server.
If OAuth2 is used, an NF Service Consumer, prior to consuming services offered by the Nudm_NIDDAU API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [19], 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 Nudm_NIDDAU service.
The Nudm_NIDDAU API defines a single scope "nudm-niddau" for OAuth2 authorization (as specified in 3GPP TS 33.501 [6]) for the entire API, and it does not define any additional scopes at resource or operation level.