6.5 Nhss_gbaUEAuthentication Service API
29.5623GPP5G SystemHome Subscriber Server (HSS) servicesRelease 18Stage 3TS
6.5.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-ueau" and the "apiVersion" shall be set to "v1" for the current version of this specification.
6.5.2 Usage of HTTP
6.5.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_gbaUEAuthentication service shall comply with the OpenAPI [9] specification contained in Annex A.6.
6.5.2.2 HTTP standard headers
6.5.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.5.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"
6.5.2.3 HTTP custom headers
6.5.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.5.3 Resources
6.5.3.1 Overview
Figure 6.5.3.1-1: Resource URI structure of the Nhss_gbaUEAU API
Table 6.5.3.1-1 provides an overview of the resources and applicable HTTP methods.
Table 6.5.3.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
SecurityInformation |
/{ueId}/security-information/generate-auth-data |
generate-auth-data (POST) |
6.5.3.2 Resource: SecurityInformation (Custom Operation)
6.5.3.2.1 Description
This resource represents the information that is needed to calculate a fresh authentication vector for GBA.
6.5.3.2.2 Resource Definition
Resource URI: {apiRoot}/nhss-gba-ueau/v1/{ueId}/security-information
This resource shall support the resource URI variables defined in table 6.5.3.2.2-1.
Table 6.5.3.2.2-1: Resource URI variables for this resource
|
Name |
Definition |
|
apiRoot |
See clause 6.5.1 |
|
ueId |
Represents the UE Identity. It can be an MSISDN, an IMSI an IMPI or an IMPU. |
6.5.3.2.3 Resource Standard Methods
No Standard Methods are supported for this resource.
6.5.3.2.3 Resource Custom Operations
6.5.3.2.4.1 Overview
Table 6.5.3.2.4.1-1: Custom operations
|
Operation Name |
Custom operation URI |
Mapped HTTP method |
Description |
|
generate-auth-data |
/generate-auth-data |
POST |
6.5.3.2.4.2 Operation: generate-auth-data
6.5.3.2.4.2.1 Description
This custom operation is used by the NF service consumer (BSF) to request authentication information data for the UE from the HSS.
6.5.3.2.4.2.2 Operation Definition
This operation shall support the request data structures specified in table 6.5.3.2.4.2.2-1 and the response data structure and response codes specified in table 6.5.3.2.4.2.2-2.
Table 6.5.3.2.4.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
AuthenticationInfoRequest |
M |
1 |
Table 6.5.3.2.3.1-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
AuthenticationInfoResult |
M |
1 |
200 OK |
|
|
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.5.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.5.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.5.5 Notifications
In this release of this specification, no notifications are defined for the Nhss_gbaUEAuthentication Service.
6.5.6 Data Model
6.5.6.1 General
This clause specifies the application data model supported by the API.
Table 6.5.6.1-1 specifies the structured data types defined for the Nhss_gbaUEAU service API.
Table 6.5.6.1-1: Nhss_gbaUEAU specific Data Types
|
Data type |
Clause defined |
Description |
|
AuthenticationInfoRequest |
6.5.6.2.2 |
|
|
AuthenticationInfoResult |
6.5.6.2.3 |
|
|
DigestAuthentication |
6.5.6.2.6 |
|
|
Impi |
6.5.6.3.2 |
|
|
AuthenticationScheme |
6.5.6.3.3 |
|
|
DigestAlgorithm |
6.5.6.3.4 |
|
|
DigestQop |
6.5.6.3.5 |
Table 6.5.6.1-2 specifies data types re-used by the Nhss_gbaUEAU service API from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Nhss_gbaUEAU.
Table 6.5.6.1-2: Nhss_gbaUEAU re-used Data Types
|
Data type |
Reference |
Comments |
|
Autn |
3GPP TS 29.503 [15] |
|
|
Auts |
3GPP TS 29.503 [15] |
|
|
Rand |
3GPP TS 29.503 [15] |
|
|
Xres |
3GPP TS 29.503 [15] |
|
|
ProblemDetails |
3GPP TS 29.571 [16] |
Response body of error response messages. |
|
RedirectResponse |
3GPP TS 29.571 [16] |
Response body of redirect response messages. |
|
SupportedFeatures |
3GPP TS 29.571 [16] |
|
|
ResynchronizationInfo |
3GPP TS 29.562 |
Clause 6.3.6.2.4 |
|
3GAkaAv |
3GPP TS 29.562 |
Clause 6.3.6.2.5 |
|
UeId |
3GPP TS 29.562 |
Clause 6.4.6.3.2 |
6.5.6.2 Structured data types
6.5.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
6.5.6.2.2 Type: AuthenticationInfoRequest
Table 6.5.6.2.2-1: Definition of type AuthenticationInfoRequest
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
authenticationScheme |
AuthenticationScheme |
M |
1 |
|
|
resynchronizationInfo |
ResynchronizationInfo |
O |
0..1 |
|
|
supportedFeatures |
SupportedFeatures |
O |
0..1 |
6.5.6.2.3 Type: AuthenticationInfoResult
Table 6.5.6.2.3-1: Definition of type AuthenticationInfoResult
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
impi |
Impi |
O |
0..1 |
|
|
3gAkaAv |
3gAkaAv |
O |
0..1 |
|
|
digestAuth |
DigestAuthentication |
O |
0..1 |
|
|
supportedFeatures |
SupportedFeatures |
O |
0..1 |
6.5.6.2.4 Void
6.5.6.2.5 Void
6.5.6.2.6 Type: DigestAuthentication
Table 6.5.6.2.6-1: Definition of type DigestAuthentication
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
digestRealm |
string |
M |
1 |
|
|
digestAlgorithm |
DigestAlgorithm |
M |
1 |
|
|
digestQop |
DigestQop |
M |
1 |
|
|
ha1 |
string |
M |
1 |
6.5.6.3 Simple data types and enumerations
6.5.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.5.6.3.2 Simple data types
The simple data types defined in table 6.5.6.3.2-1 shall be supported.
Table 6.5.6.3.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
|
Impi |
string |
IMS Private User Identity |
|
Ck |
string |
pattern: "^[A-Fa-f0-9]{32}$" |
|
Ik |
string |
pattern: "^[A-Fa-f0-9]{32}$" |
6.5.6.3.3 Enumeration: AuthenticationScheme
The enumeration AuthenticationScheme represents the authentication scheme used in GBA. It shall comply with the provisions defined in table 6.5.6.3.3-1.
Table 6.5.6.3.3-1: Enumeration AuthenticationScheme
|
Enumeration value |
Description |
|
"DIGEST_AKAV1_MD5" |
IMS-AKA authentication scheme |
|
"DIGEST_HTTP" |
Digest authentication scheme |
6.5.6.3.4 Enumeration: DigestAlgorithm
The enumeration DigestAlgorithm represents the algorithm for the Digest scheme. It shall comply with the provisions defined in table 6.5.6.3.4-1.
Table 6.5.6.3.4-1: Enumeration DigestAlgorithm
|
Enumeration value |
Description |
|
"MD5" |
MD5 digest algorithm |
|
"MD5_SESS" |
Session variant of the MD5 digest algorithm |
6.5.6.3.5 Enumeration: DigestQop
The enumeration DigestQop represents the quality of protection for the Digest scheme. It shall comply with the provisions defined in table 6.5.6.3.5-1.
Table 6.5.6.3.5-1: Enumeration DigestQop
|
Enumeration value |
Description |
|
"AUTH" |
Indicates authentication |
|
"AUTH_INT" |
Indicates authentication with integrity protection |
6.5.7 Error Handling
6.5.7.1 General
HTTP error handling shall be supported as specified in clause 5.2.4 of 3GPP TS 29.500 [4].
6.5.7.2 Protocol Errors
Protocol errors handling shall be supported as specified in clause 5.2.7 of 3GPP TS 29.500 [4].
6.5.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_gbaUEAU service. The following application errors listed in Table 6.5.7.3-1 are specific for the Nhss_gbaUEAU service.
Table 6.5.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
|
OPERATION_NOT_ALLOWED |
403 Forbidden |
The NF Service Consumer is not authorized to invoke the requested service operation. |
|
USER_NOT_FOUND |
404 Not Found |
The user does not exist in the HPLMN. |
6.5.8 Feature Negotiation
The optional features in table 6.5.8-1 are defined for the Nhss_gbaUEAU API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [4].
Table 6.5.8-1: Supported Features
|
Feature number |
Feature Name |
Description |
6.5.9 Security
As indicated in 3GPP TS 33.501 [5], the access to the Nhss_gbaUEAU 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_gbaUEAU 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_gbaUEAU service.
The Nhss_gbaUEAU API defines the following scopes for OAuth2 authorization:
Table 6.5.9-1: Oauth2 scopes defined in Nhss_gbaUEAU API
|
Scope |
Description |
|
"nhss-gba-ueau" |
Access to the Nhss_gbaUEAU API |
|
"nhss-gba-ueau:generate-auth-data:invoke" |
Access to invoke the Generate Auth Data operation |
Annex A (normative):
OpenAPI specification