6.4 Nhss_gbaSubscriberDataManagement Service API

29.5623GPP5G SystemHome Subscriber Server (HSS) servicesRelease 18Stage 3TS

6.4.1 API URI

URIs of this API shall have the following root:

{apiRoot}/{apiName}/{apiVersion}

where "apiRoot" is defined in clause 4.4.1 of 3GPP TS 29.501 [5], the "apiName" shall be set to "nhss-gba-sdm" and the "apiVersion" shall be set to "v1" for the current version of this specification.

6.4.2 Usage of HTTP

6.4.2.1 General

HTTP/2, as defined in IETF RFC 7540 [8], 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 Nhss_gbaSubscriberDataManagement service shall comply with the OpenAPI [9] specification contained in Annex A.5.

6.4.2.2 HTTP standard headers

6.4.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.4.2.2.2 Content type

The following content types shall be supported:

– JSON, as defined in IETF RFC 8259 [10], signalled by the content type "application/json".

– The Problem Details JSON Object (IETF RFC 7807 [11] signalled by the content type "application/problem+json"

– JSON Patch, as defined in IETF RFC 6902 [12], signalled by the content type "application/json-patch+json"

6.4.2.3 HTTP custom headers

6.4.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.4.3 Resources

6.4.3.1 Overview

Figure 6.4.3.1-1: Resource URI structure of the Nhss_gbaSDM API

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

Table 6.4.3.1-1: Resources and methods overview

Resource name
(Archetype)

Resource URI

HTTP method or custom operation

Description

GBA Subscriber Data (Document)

/{ueId}/gba-subscriber-data

GET

GBA SDM Subscriptions (Collection)

/{ueId}/subscriptions

POST

GBA SDM Individual

/{ueId}/subscriptions/{subscriptionId}

PATCH

Subscription (Document)

DELETE

6.4.3.2 Resource: GBA Subscriber Data

6.4.3.2.1 Description

This resource represents the subscriber data of the UE for GBA, including the GBA User Security Settings (GUSS).

6.4.3.2.2 Resource Definition

Resource URI: {apiRoot}/nhss-gba-sdm/v1/{ueId}/gba-subscriber-data

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

Table 6.4.3.2.2-1: Resource URI variables for this resource

Name

Definition

apiRoot

See clause 6.4.1

ueId

Represents the UE Identity. See clause 6.4.6.3.2.

6.4.3.2.3 Resource Standard Methods

6.4.3.2.3.1 GET

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

Table 6.4.3.2.3.1-1: URI query parameters supported by the GET 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.4.3.2.3.1-2 and the response data structures and response codes specified in table 6.4.3.2.3.1-3.

Table 6.4.3.2.3.1-2: Data structures supported by the GET Request Body on this resource

Data type

P

Cardinality

Description

n/a

Table 6.4.3.2.3.1-3: Data structures supported by the GET Response Body on this resource

Data type

P

Cardinality

Response

codes

Description

GbaSubscriberData

M

1

200 OK

A response body containing the GBA subscriber data of the UE; it includes the GBA User Security Settings (GUSS) data.

RedirectResponse

O

0..1

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 service instance within the same HSS (service) set.

RedirectResponse

O

0..1

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 service instance within the same HSS (service) set.

ProblemDetails

O

0..1

403 Forbidden

The "cause" attribute may be used to indicate one of the following application errors:

– OPERATION_NOT_ALLOWED

ProblemDetails

O

0..1

404 Not Found

The "cause" attribute may be used to indicate the following application error:

– USER_NOT_FOUND

Table 6.4.3.2.3.1-4: Headers supported by the 307 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located on an alternative service instance within the same HSS (service) set.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected.

Table 6.4.3.2.3.1-5: Headers supported by the 308 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located on an alternative service instance within the same HSS (service) set.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected.

6.4.3.3 Resource: Subscriptions

6.4.3.3.1 Description

This resource is used to represent subscriptions to notifications of data change.

6.4.3.3.2 Resource Definition

Resource URI: {apiRoot}/nhss-gba-sdm/{apiVersion}/{ueId}/subscriptions

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

Table 6.4.3.3.2-1: Resource URI variables for this resource

Name

Definition

apiRoot

See clause 6.4.1

apiVersion

See clause 6.4.1

ueId

Represents the UE Identity. See clause 6.4.6.3.2.

6.4.3.3.3 Resource Standard Methods

6.4.3.3.3.1 POST

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

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

Name

Data type

P

Cardinality

Description

n/a

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

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

Data type

P

Cardinality

Description

GbaSdmSubscription

M

1

The subscription that is to be created.

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

Data type

P

Cardinality

Response

codes

Description

GbaSdmSubscription

M

1

201 Created

Upon success, a response body containing a representation of the created Individual subscription resource shall be returned.

The HTTP response shall include a "Location" HTTP 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. The URI shall be an alternative URI of the resource located on an alternative service instance within the same HSS (service) set.

RedirectResponse

O

0..1

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 service instance within the same HSS (service) set.

ProblemDetails

O

0..1

404 Not Found

The "cause" attribute may be used to indicate the following application error:

– USER_NOT_FOUND

ProblemDetails

O

0..1

501 Not Implemented

The "cause" attribute may be used to indicate the following application error:

– UNSUPPORTED_RESOURCE_URI

This response shall not be cached.

Table 6.4.3.3.3.1-4: Headers supported by the 307 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located on an alternative service instance within the same HSS (service) set.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected.

Table 6.4.3.3.3.1-5: Headers supported by the 308 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located on an alternative service instance within the same HSS (service) set.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected.

6.4.3.4 Resource: Individual subscription

6.4.3.4.1 Description

This resource is used to represent an individual subscription to notifications of data change.

6.4.3.4.2 Resource Definition

Resource URI: {apiRoot}/nhss-gba-sdm/{apiVersion}/{ueId}/subscriptions/{subscriptionId}

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

Table 6.4.3.4.2-1: Resource URI variables for this resource

Name

Definition

apiRoot

See clause 6.4.1

apiVersion

See clause 6.4.1

ueId

Represents the UE Identity. See clause 6.4.6.3.2.

subscriptionId

The subscriptionId identifies an individual subscription to notifications.

6.4.3.4.3 Resource Standard Methods

6.4.3.4.3.1 DELETE

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

Table 6.4.3.4.3.1-1: URI query parameters supported by the DELETE method on this resource

Name

Data type

P

Cardinality

Description

n/a

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

Table 6.4.3.4.3.1-2: Data structures supported by the Delete Request Body on this resource

Data type

P

Cardinality

Description

n/a

The request body shall be empty.

Table 6.4.3.4.3.1-3: Data structures supported by the DELETE Response Body on this resource

Data type

P

Cardinality

Response

codes

Description

n/a

204 No Content

Upon success, an empty response body shall be returned.

RedirectResponse

O

0..1

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 service instance within the same HSS (service) set.

RedirectResponse

O

0..1

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 service instance within the same HSS (service) set.

ProblemDetails

O

0..1

404 Not Found

The "cause" attribute may be used to indicate one of the following application errors:

– USER_NOT_FOUND

– SUBSCRIPTION_NOT_FOUND, see 3GPP TS 29.500 [4] table 5.2.7.2-1.

Table 6.4.3.4.3.1-4: Headers supported by the 307 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located on an alternative service instance within the same HSS (service) set.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected.

Table 6.4.3.4.3.1-5: Headers supported by the 308 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located on an alternative service instance within the same HSS (service) set.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected.

6.4.3.4.3.2 PATCH

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

Table 6.4.3.4.3.2-1: URI query parameters supported by the PATCH method on this resource

Name

Data type

P

Cardinality

Description

supported-features

SupportedFeatures

O

0..1

see 3GPP TS 29.500 [4] clause 6.6

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

Table 6.4.3.4.3.2-2: Data structures supported by the PATCH Request Body on this resource

Data type

P

Cardinality

Description

array(PatchItem)

M

1

It contains the list of changes to be made to the resource representing the individual subscription, according to the JSON PATCH format specified in IETF RFC 6902 [12].

Table 6.4.3.4.3.2-3: Data structures supported by the PATCH Response Body on this resource

Data type

P

Cardinality

Response

codes

Description

n/a

204 No Content

Upon success, a response with no content is returned.

(NOTE 1)

PatchResult

M

1

200 OK

Upon success, the execution report is returned. (NOTE 1)

RedirectResponse

O

0..1

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 service instance within the same HSS (service) set.

RedirectResponse

O

0..1

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 service instance within the same HSS (service) set.

ProblemDetails

O

0..1

404 Not Found

The "cause" attribute may be used to indicate one of the following application errors:

– USER_NOT_FOUND

– SUBSCRIPTION_NOT_FOUND, see 3GPP TS 29.500 [4] table 5.2.7.2-1.

ProblemDetails

O

0..1

403 Forbidden

One or more attributes are not allowed to be modified.

The "cause" attribute may be used to indicate the following application error:

– MODIFICATION_NOT_ALLOWED, see 3GPP TS 29.500 [4] table 5.2.7.2-1.

NOTE 1: If all the modification instructions in the PATCH request have been implemented, the HSS shall respond with 204 No Content response; if some of the modification instructions in the PATCH request have been discarded, and the NF service consumer has included in the supported-feature query parameter the "PatchReport" feature number, the HSS shall respond with PatchResult.

Table 6.4.3.4.3.2-4: Headers supported by the 307 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located on an alternative service instance within the same HSS (service) set.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected.

Table 6.4.3.4.3.2-5: Headers supported by the 308 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located on an alternative service instance within the same HSS (service) set.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected.

6.4.4 Custom Operations without associated resources

In this release of this specification, no custom operations without associated resources are defined for the Nhss_gbaSDM Service.

6.4.5 Notifications

6.4.5.1 General

This clause specifies the use of notifications and corresponding protocol details.

6.4.5.2 Data Change Notification

The POST method shall be used for Data Change Notifications and the URI shall be as provided during the subscription procedure.

Resource URI: {callbackReference}

Support of URI query parameters is specified in table 6.4.5.2-1.

Table 6.4.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.4.5.2-2 and of response data structures and response codes is specified in table 6.4.5.2-3.

Table 6.4.5.2-2: Data structures supported by the POST Request Body

Data type

P

Cardinality

Description

ModificationNotification

M

1

Table 6.4.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.

RedirectResponse

O

0..1

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 notification endpoint of the subscribing NF Service Consumer.

RedirectResponse

O

0..1

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 notification endpoint of the subscribing NF Service Consumer.

ProblemDetails

O

0..1

404 Not Found

The "cause" attribute may be used to indicate the following application error:

– CONTEXT_NOT_FOUND

See table 6.4.7.3-1 for the description of this error.

Table 6.4.5.2-4: Headers supported by the 307 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the notification endpoint of the subscribing NF.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected.

Table 6.4.5.2-5: Headers supported by the 308 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the notification endpoint of the subscribing NF.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected.

6.4.6 Data Model

6.4.6.1 General

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

Table 6.4.6.1-1 specifies the structured data types defined for the Nhss_gbaSDM service API.

Table 6.4.6.1-1: Nhss_gbaSDM specific Data Types

Data type

Clause defined

Description

GbaSubscriberData

6.4.6.2.2

Guss

6.4.6.2.3

BsfInfo

6.4.6.2.4

GbaSdmSubscription

6.4.6.2.5

UeId

6.4.6.3.2

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

Table 6.4.6.1-2: Nhss_gbaSDM re-used Data Types

Data type

Reference

Comments

UssListItem

3GPP TS 29.309 [42]

SecFeature

3GPP TS 29.309 [42]

ModificationNotification

3GPP TS 29.503 [15]

NfInstanceId

3GPP TS 29.571 [16]

Uri

3GPP TS 29.571 [16]

DateTime

3GPP TS 29.571 [16]

DurationSec

3GPP TS 29.571 [16]

ProblemDetails

3GPP TS 29.571 [16]

Response body of error response messages.

RedirectResponse

3GPP TS 29.571 [16]

Response body of redirect response messages.

ImsUeId

3GPP TS 29.562

IMS UE ID (IMPU or IMPI)

6.4.6.2 Structured data types

6.4.6.2.1 Introduction

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

6.4.6.2.2 Type: GbaSubscriberData

Table 6.4.6.2.2-1: Definition of type GbaSubscriberData

Attribute name

Data type

P

Cardinality

Description

guss

Guss

M

1

6.4.6.2.3 Type: Guss

Table 6.4.6.2.3-1: Definition of type Guss

Attribute name

Data type

P

Cardinality

Description

bsfInfo

BsfInfo

O

0..1

BSF-specific information.

ussList

array(UssListItem)

O

1..N

6.4.6.2.4 Type: BsfInfo

Table 6.4.6.2.4-1: Definition of type BsfInfo

Attribute name

Data type

P

Cardinality

Description

uiccType

UiccType

O

0..1

It indicates whether GBA or GBA_U is to be used; default value is GBA.

lifeTime

DurationSec

O

0..1

It indicates a user-specific key lifetime (duration in seconds). If the lifeTime element is missing the default value in the BSF is used.

securityFeatures

array(SecFeature)

O

1..N

It indicates a user-specific security feature list that the UE supports. If the securityFeature element is missing, then the security features are not defined.

Standard security features are defined in 3GPP TS 29.309 [42], clause 6.1.6.3.5.

6.4.6.2.5 Type: GbaSdmSubscription

Table 6.4.6.2.5-1: Definition of type GbaSdmSubscription

Attribute name

Data type

P

Cardinality

Description

nfInstanceId

NfInstanceId

M

1

callbackReference

Uri

M

1

monitoredResourceUris

array(Uri)

M

1..N

expires

DateTime

O

0..1

6.4.6.3 Simple data types and enumerations

6.4.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.4.6.3.2 Simple data types

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

Table 6.4.6.3.2-1: Simple data types

Type Name

Type Definition

Description

UeId

string

Identity of the UE. It can be an MSISDN, an IMSI an IMPI or an IMPU.

Msisdn

string

MS-ISDN of the UE.

pattern: ‘^msisdn-[0-9]{5,15}$’

Imsi

string

IMSI of the UE.

pattern: ‘^imsi-[0-9]{5,15}$’

6.4.6.3.3 Enumeration: UiccType

The enumeration UiccType represents whether GBA or GBA_U is to be used. It shall comply with the provisions defined in table 6.4.6.3.3-1.

Table 6.4.6.3.4-1: Enumeration UiccType

Enumeration value

Description

"GBA"

GBA: Basic GBA case (no generation of Ks_int_NAF at the BSF).

"GBA_U"

GBA_U: Generation of Ks_int_NAF is required at the BSF.

6.4.7 Error Handling

6.4.7.1 General

HTTP error handling shall be supported as specified in clause 5.2.4 of 3GPP TS 29.500 [4].

6.4.7.2 Protocol Errors

Protocol errors handling shall be supported as specified in clause 5.2.7 of 3GPP TS 29.500 [4].

6.4.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 Nhss_gbaSDM service. The following application errors listed in Table 6.4.7.3-1 are specific for the Nhss_gbaSDM service.

Table 6.4.7.3-1: Application errors

Application Error

HTTP status code

Description

USER_NOT_FOUND

404 Not Found

The user does not exist in the HPLMN

CONTEXT_NOT_FOUND

404 Not Found

The service consumer has received a notification from a service producer for a subscription that is unknown to the service consumer.

6.4.8 Feature Negotiation

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

Table 6.4.8-1: Supported Features

Feature number

Feature Name

Description

6.4.9 Security

As indicated in 3GPP TS 33.501 [5], the access to the Nhss_gbaSDM API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [35]), using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [36]) plays the role of the authorization server.

If Oauth2 authorization is used, an NF Service Consumer, prior to consuming services offered by the Nhss_gbaSDM API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [36], 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 Nhss_gbaSDM service.

The Nhss_gbaSDM API defines the following scopes for OAuth2 authorization:

Table 6.4.9-1: Oauth2 scopes defined in Nhss_gbaSDM API

Scope

Description

"nhss-gba-sdm"

Access to the Nhss_gbaSDM API

"nhss-gba-sdm:gba-subscriber-data:read"

Access to read the GBA Subscriber Data resource