6.3 Nhss_imsUEAuthentication Service API
29.5623GPP5G SystemHome Subscriber Server (HSS) servicesRelease 18Stage 3TS
6.3.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-ims-ueau" and the "apiVersion" shall be set to "v1" for the current version of this specification.
6.3.2 Usage of HTTP
6.3.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_imsUEAU service shall comply with the OpenAPI [9] specification contained in Annex A.3.
6.3.2.2 HTTP standard headers
6.3.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.3.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.3.2.3 HTTP custom headers
6.3.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.3.3 Resources
6.3.3.1 Overview
Figure 6.3.3.1-1: Resource URI structure of the Nhss_imsUEAU API
Table 6.3.3.1-1 provides an overview of the resources and applicable HTTP methods.
Table 6.3.3.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
SecurityInformation |
/{impi}/security-information/generate-sip-auth-data |
generate-sip-auth-data (POST) |
The HSS takes the variable {impi} and, if applicable, fetches the corresponding SUPI. The HSS calculates a fresh authentication vector based on the received information and the stored security information, if IMS-AKA is selected. Otherwise, the HSS provides the corresponding authentication information. |
6.3.3.2 Resource: SecurityInformation
6.3.3.2.1 Description
This resource represents the information that is needed together with the SIP authenticacion scheme to calculate a fresh authentication vector.
6.3.3.2.2 Resource Definition
Resource URI: {apiRoot}/nhss-ims-ueau/v1/{impi}/security-information
This resource shall support the resource URI variables defined in table 6.3.3.2.2-1.
Table 6.3.3.2.2-1: Resource URI variables for this resource
|
Name |
Definition |
|
apiRoot |
See clause 6.3.1 |
|
impi |
Represents the IMS Private Identity (see 3GPP TS 23.003 [13] clause 13.3. Pattern: "^(impi-.+|.+)$" |
6.3.3.2.3 Resource Standard Methods
No Standard Methods are supported for this resource.
6.3.3.2.4 Resource Custom Operations
6.3.3.2.4.1 Overview
Table 6.3.3.2.4.1-1: Custom operations
|
Custom operaration URI |
Mapped HTTP method |
Description |
|
/generate-sip-auth-data |
POST |
Select the authentication method and calculate a fresh AV if IMS-AKA is selected or provides corresponding authentication information. |
6.3.3.2.4.2 Operation: generate-sip-auth-data
6.3.3.2.4.2.1 Description
This custom operation is used by the NF service consumer (S-CSCF) to request authentication information data for the IMPI from the HSS. The HSS calculates an authentication vector taking into account the information received from the NF service consumer (S-CSCF) and the current representation of this resource if IMS AKA is selected. For details see 3GPP TS 33.203 [14].
6.3.3.2.4.2.2 Operation Definition
This operation shall support the request data structures specified in table 6.3.3.2.4.2.2-1 and the response data structure and response codes specified in table 6.3.3.2.4.2.2-2.
Table 6.3.3.2.4.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
SipAuthenticationInfoRequest |
M |
1 |
Contains the SIP Authentication Scheme, the number of authentication items and Resynchronization Information |
Table 6.3.3.2.4.2.2-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
SipAuthenticationInfoResult |
M |
1 |
200 OK |
Upon success, a response body containing the selected authentication method and an authentication vector if IMS AKA has been selected 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 the following application error: – USER_NOT_FOUND |
|
ProblemDetails |
O |
0..1 |
403 Forbidden |
The "cause" attribute may be used to indicate one of the following application errors: – AUTHENTICATION_REJECTED – UNSUPPORTED_SIP_AUTH_SCHEME |
Table 6.3.3.2.4.2.2-3: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI 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.3.3.2.4.2.2-4: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI 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.3.4 Custom Operations without associated resources
In this release of this specification, no custom operations without associated resources are defined for the Nhss_imsUEAuthentication Service.
6.3.5 Notifications
In this release of this specification, no notifications are defined for the Nhss_imsUEAuthentication Service.
6.3.6 Data Model
6.3.6.1 General
This clause specifies the application data model supported by the API.
Table 6.3.6.1-1 specifies the structured data types defined for the Nhss_imsUEAU service API.
Table 6.3.6.1-1: Nhss_imsUEAU specific Data Types
|
Data type |
Clause defined |
Description |
|
SipAuthenticationInfoRequest |
6.3.6.2.2 |
Contains SIP Authentication Schema, Authentication Items and Resynchronization Information |
|
SipAuthenticationInfoResult |
6.3.6.2.3 |
Contains authentication information (e.g. authentication vectors, line id) |
|
ResynchronizationInfo |
6.3.6.2.4 |
Contains RAND and AUTS |
|
3GAkaAv |
6.3.6.2.5 |
Contains RAND, XRES, AUTN, CK, and IK |
Table 6.3.6.1-2 specifies data types re-used by the Nhss_imsUEAU service API from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Nhss_imsUEAU.
Table 6.3.6.1-2: Nhss_imsUEAU re-used Data Types
|
Data type |
Reference |
Comments |
|
ProblemDetails |
3GPP TS 29.571 [16] |
Response body of error response messages. |
|
RedirectResponse |
3GPP TS 29.571 [16] |
Response body of redirect response messages. |
|
IpAddr |
3GPP TS 29.571 [16] |
IP Address (either IPv4 address, IPv6 address or IPv6 prefix) |
|
Autn |
3GPP TS 29.503 [15] |
AUTN component of the Authentication Vector |
|
Auts |
3GPP TS 29.503 [15] |
AUTS component of the Resynchronization Info |
|
Rand |
3GPP TS 29.503 [15] |
RAND component of the Authentication Vector or the Resynchronization Info |
|
Xres |
3GPP TS 29.503 [15] |
XRES component of the Authentication Vector |
|
ConfidentialityKey |
3GPP TS 29.503 [15] |
CK component of the Authentication Vector |
|
IntegrityKey |
3GPP TS 29.503 [15] |
IK component of the Authentication Vector |
6.3.6.2 Structured data types
6.3.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
6.3.6.2.2 Type: SipAuthenticationInfoRequest
Table 6.3.6.2.3-1: Definition of type AuthenticationInfoRequest
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
cscfServerName |
string |
M |
1 |
S-CSCF name in SIP URI format |
|
sipAuthenticationScheme |
SipAuthenticationScheme |
M |
1 |
SIP Authentication Scheme requested by service consumer (S-CSCF) |
|
sipNumberAuthItems |
SipNumberAuthItems |
O |
0..1 |
Number of authentication items (AVs). Absence indicates that only one AV is requested. This attribute shall be absent for authentication schemes other than IMS AKA. |
|
resynchronizationInfo |
ResynchronizationInfo |
O |
0..1 |
Contains RAND and AUTS; see 3GPP TS 33.203 [14]. This attribute shall be included only if a resynchronization procedure needs to be triggered. This attribute shall be absent for authentication schemes other than IMS AKA. |
6.3.6.2.3 Type: SipAuthenticationInfoResult
Table 6.3.6.2.3-1: Definition of type AuthenticationInfoResult
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
sipAuthenticationScheme |
SipAuthenticationScheme |
M |
1 |
SIP Authentication Scheme used by service producer (HSS) |
|
3gAkaAvs |
array(3GAkaAv) |
O |
1..N |
If IMS AKA is requested, it shall be present and will contains Authentication Vectors. |
|
digestAuth |
DigestAuthentication |
O |
0..1 |
If SIP Digest is used, it shall be present and shall contain the digest realm, algorithm, QoP and HA1. |
|
lineIdentifierList |
array(LineIdentifier) |
O |
0..N |
If NBA is used, it shall be present and shall contain a list of fixed broadband access line identifiers associated to the user. |
|
ipAddress |
IpAddr |
O |
0..1 |
If GIBA is used, it shall be present and shall contain an IP address (IPv4, or IPv6, or IPv6 prefix) |
6.3.6.2.4 Type: ResynchronizationInfo
Table 6.3.6.2.4-1: Definition of type ResynchronizationInfo
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
rand |
Rand |
M |
1 |
|
|
auts |
Auts |
M |
1 |
6.3.6.2.5 Type: 3GAkaAv
Table 6.3.6.2.5-1: Definition of type 3gAkaAv
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
rand |
Rand |
M |
1 |
RAND component of the Authentication Vector |
|
xres |
Xres |
M |
1 |
XRES component of the Authentication Vector |
|
autn |
Autn |
M |
1 |
AUTN component of the Authentication Vector |
|
ck |
ConfidentialityKey |
M |
1 |
CK component of the Authentication Vector |
|
ik |
IntegrityKey |
M |
1 |
IK component of the Authentication Vector |
6.3.6.2.6 Type: DigestAuthentication
Table 6.3.6.2.6-1: Definition of type DigestAuthentication
|
Attribute name |
Data type |
P |
Cardinality |
Description |
|
digestRealm |
string |
M |
1 |
Digest realm. See IETF RFC 4740 [17]. |
|
digestAlgorithm |
SipDigestAlgorithm |
M |
1 |
Digest Algorithm. See IETF RFC 4740 [17]. |
|
digestQop |
SipDigestQop |
M |
1 |
Quality of Protection. See IETF RFC 4740 [17]. |
|
ha1 |
string |
M |
1 |
Hash H(A1). See IETF RFC 4740 [17]. |
6.3.6.2.7 Void
6.3.6.3 Simple data types and enumerations
6.3.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.3.6.3.2 Simple data types
The simple data types defined in table 6.3.6.3.2-1 shall be supported.
Table 6.3.6.3.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
|
SipNumberAuthItems |
integer |
Number of authentication items Minimum: 1 |
|
Impi |
string |
IMS Private User Identity |
|
LineIdentifier |
string |
Line Identifier for the wireline access |
6.3.6.3.3 Enumeration: SipAuthenticationScheme
The enumeration SipAuthenticationScheme represents an IMS authentication scheme. It shall comply with the provisions defined in table 6.3.6.3.3-1.
Table 6.3.6.3.3-1: Enumeration SipAuthenticationScheme
|
Enumeration value |
Description |
|
"DIGEST-AKAV1-MD5" |
IMS-AKA authentication scheme |
|
"DIGEST-HTTP" |
SIP Digest authentication scheme |
|
"NBA" |
NASS Bundled authentication scheme |
|
"GIBA" |
GPRS-IMS-Bundled authentication scheme |
|
"UNKNOWN" |
Authentication scheme to be used is unknown by the service consumer |
6.3.6.3.4 Enumeration: SipDigestAlgorithm
The enumeration SipDigestAlgorithm represents the algorithm for SIP Digest scheme. It shall comply with the provisions defined in table 6.3.6.3.4-1.
Table 6.3.6.3.4-1: Enumeration SipDigestAlgorithm
|
Enumeration value |
Description |
|
"MD5" |
|
|
"MD5_SESS" |
6.3.6.3.5 Enumeration: SipDigestQop
The enumeration SipDigestQop represents the quality of protection for SIP Digest scheme. It shall comply with the provisions defined in table 6.3.6.3.5-1.
Table 6.3.6.3.5-1: Enumeration SipDigestQop
|
Enumeration value |
Description |
|
"AUTH" |
Indicates authentication |
|
"AUTH_INT" |
Indicates authentication with integrity protection |
6.3.7 Error Handling
6.3.7.1 General
HTTP error handling shall be supported as specified in clause 5.2.4 of 3GPP TS 29.500 [4].
6.3.7.2 Protocol Errors
Protocol errors handling shall be supported as specified in clause 5.2.7 of 3GPP TS 29.500 [4].
6.3.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_imsUEAuthentication service. The following application errors listed in Table 6.3.7.3-1 are specific for the Nhss_imsUEAuthentication service.
Table 6.3.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
|
AUTHENTICATION_REJECTED |
403 Forbidden |
The user cannot be authenticated with this authentication method |
|
USER_NOT_FOUND |
404 Not Found |
The user does not exist in the HPLMN |
|
UNSUPPORTED_SIP_AUTHENTICATION_SCHEME |
501 Not implemented |
The received SIP authentication scheme is not supported by HPLMN |
6.3.8 Feature Negotiation
6.3.9 Security
As indicated in 3GPP TS 33.501 [5], the access to the Nhss_imsUEAU 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_imsUEAU 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_imsUEAU service.
The Nhss_imsUEAU API defines the following scopes for OAuth2 authorization:
Table 6.3.9-1: Oauth2 scopes defined in Nhss_imsUEAU API
|
Scope |
Description |
|
"nhss-ims-ueau" |
Access to the Nhss IMS UE Context Management API |
|
"nhss-ims-ueau:generate-sip-auth-data:invoke" |
Access to invoke the Generate SIP Auth Data custom method |