Authorization (OAuth 2.0)

OAuth 2.0 is an authorization framework that uses authorization tokens to obtain access to HTTP resources. OAuth 2.0 can be used to check if a consumer is allowed to access a particular URI on the producer.

OAuth 2.0 provides a mechanism to achieve these access permissions in a distributed system by passing signed tokens with every request. Figure 1 shows OAuth 2.0 passing signed tokens with each request, among the NRF, SMF, and CHF.

Figure 1. Token Exchange Among NRF, SMF, and CHF
OAuth 2.0 passes signed tokens among the NRF, SMF, and CHF.
  1. The NF Consumer requests an OAuth Token from the NRF, using TLS mAuth to authenticate itself.
  2. The NRF returns a token, signed with its private key, which includes a list NF services (scopes) that the NF consumer is allowed to access.
  3. The NF consumer sends the token in the authorization header of an HTTP request to the NF producer.
  4. The NF producer verifies the token using the pre-installed NRF certificate to ensure it was created by the NRF and has not been modified. It matches a scope in the token to the service being accessed to authorize the request.

HMAC versus RSA

The token can be signed using a shared secret (HMAC) or a public/private key pair (RSA). The token must be signed so that the NF producer can verify that it was produced by the NRF and has not been modified. If HMAC is used, the shared secret must be configured on the NRF and on every NF producer and consumer. Note the following requirements when generating keys:

  • The key must be at least 32 bytes long.
  • The key must be configured using a secure mechanism, such as Kubernetes Secrets.
  • SBA Gateway supports plain-text keys or Base64-encoded keys.

If RSA is used, the NF producer (for example, SBA Gateway) must be configured with a keystore containing a certificate that is used to verify the received token. Normally, this is the certificate of the NRF. For details, see the discussion about OAuth Certificate Management in MATRIXX 5G Integration.

JWT Overview

SBA Gateway validates signed tokens received in JSON Web Token (JWT) format. The standard JWT consists of a header, payload, and payload definitions. An encoded JSON Web Token is passed to an NF producer in the authorization header: 

Authorization: Bearer <token>

SBA OAuth Error Responses

If OAuth fails for any reason, SBA Gateway returns the error response defined in RFC 6749 5.2. SBA returns a 400 Bad Request HTTP status code with a JSON body containing an error and error_description, for example: 

HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request",
       "error_description":"Authorization header with a single Bearer token required"
     }

SBA Authorization Logic

The Figure 2 shows that a Network Function consumer (such as the SMF) must request an access token from the NRF (as per 3GPP TS 33.501). The SMF needs this access token from the NRF before it can send requests to other Network Functions.

Figure 2. NF Service Consumer (SMF) Obtains Access Token
The SMF gets the access token from the NRF, which it then uses when sending requests to the CHF

The Figure 3 shows that if a token is granted, it is passed in a request to an NF Service.

Note: Figure 3 is one of many possible scenarios; it could show the SMF as the consumer and the CHF as the producer. The key point to remember is that any time a request is received from another Network Function, it has an access token.
Figure 3. NF Service Consumer (SMF) Requests Service Access with Access Token
SBA Gateway verifies integrity and claims in access token.

An NF producer (SBA-GW) authorizes a request against a JSON Web Token using the rules defined in 3GPP TS 33.501 13.4.1. If the request succeeds, it executes the requested service. The following actions occur to the fields in the access token. Note that a JWT payload has a set of claims.

  • If the authorization header is missing or does not contain a bearer entry, then an invalid_request error is returned.
  • If the authorization header does not contain the expected Bearer <token> format, then an invalid_request error is returned.
  • If the token has expired, is malformed, or otherwise invalid, then an invalid_grant error is returned.
  • If RSA is used, check that the identity of the issuer of the access token (NRF) in the issuer claim in the access token matches the subject in the NRF certificate from the keystore. Return an invalid_grant error on failure.
  • If mTLS is enabled, check that the subject claim within the access token matches the subject in the NF consumer certificate. Return an invalid_grant error on failure.
  • Check that the audience claim in the access token matches our own identity (nfInstanceId from the configuration file) or the type of NF service producer (nfType from the configuration file).
  • If scope is present, it checks that the scope matches the requested service operation.

SBA Gateway expects the claims as defined in the 3GPP Technical Specification 29.510. For more information, see Definition of type AccessTokenClaims in 3GPP TS 29.510.

When the SMF is invoking CHF services, SBA Gateway might receive the following claim: 
{
  "iss": "964d462e-bf1b-4a1d-b6d0-f66633aead06",
  "sub": "a2953918-0881-4071-a48c-aa774b230d29",
  "aud": "CHF",
  "scope": "nchf-convergedcharging nchf-spendinglimitcontrol",
  "exp": 1565274257
}
The fields hold the following information:
  • iss — Issuer is the NF instance ID of the NRF.
  • sub — Subject is the NF instance ID of the SMF.
  • aud — The NF type of the producer (CHF). NF types are defined in 3GGP TS 29.510 6.1.6.3.3.
  • scope — The name of the NF services the access token is authorized to use. This is space delimited, and service names are defined in 3GPP TS 29.510 6.1.3.11.
  • exp — NumericDate is the value of when the token expires.