B.7 Obtaining an access token from a partner domain

33.1803GPPRelease 17Security of the Mission Critical (MC) serviceTS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

B.7.1 Overview

When an MCX user requires user service authorisation for services owned and managed within a partner domain, the MCX client shall use the OAuth 2.0 token exchange extension grant type mechanism to obtain a security token for authentication with the partner IdM service. The OAuth 2.0 token exchange procedure defines a method for obtaining the security token from the primary IdMS which contains information about the user that is verifiable by the partner IdMS.

The MCX client then provides this security token to the partner IdM service in exchange for an access token that is specific to the services in the partner domain. The MCX UE then uses the access token for user service authorisation to those services within the partner domain.

The security token and acess token(s) are specific to a IdMS and partner domain and therefore the OAuth 2.0 token exchange procedure shall be repeated with each additional domain to obtain user service authorisation to partner services within those domains.

Figure B.7.1-1 shows the OAuth 2.0 token exchange procedure used to obtain a security token and acess token(s). The messages are described in the following sub-clauses.

Figure B.7.1-1: Token exchange flow

B.7.2 Token Exchange Request

In order to obtain a security token, the MCX client makes a request to the primary authorization server’s token endpoint by sending the following parameters using the "application/x-www-form-urlencoded" content-type and a character encoding of UTF-8 in the HTTP request entity-body. The standard parameters shown in table B.7.2-1 are required by the MCX Connect profile.

Table B.7.2-1: Token Exchange Request standard required parameters

Parameter	Values
grant_type	REQUIRED. The value shall be set to “urn:ietf:params:oauth:grant-type:token-exchange” indicating that a token exchange is being performed.
resource	REQUIRED. Indicates the physical location of the target service or resource where the client intends to use the requested security token (i.e. the address of the partner authorization server’s token endpoint where the security token will be applied).
subject_token	REQUIRED. A token that represents the identity of the party on behalf of whom the request is being made. This shall be the access token previously obtained in the token response message (clause B.4.2.5) during authorisation (clause B.4).
subject_token_type	REQUIRED. An identifier that indicates the type of the security token in the subject_token parameter. The value shall be set to “urn:ietf:params:oauth:token-type:jwt” indicating the access token is a JSON Web Token.

An example of a successful token exchange request might look like:

EXAMPLE:

POST /as/token.oauth2 HTTP/1.1

Host: IdM.server.com:9031

Authorization: Basic cnA33hpsb25nABClY3VyZS1yYW5kb20tc2VjdnV0

Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange

&resource= IdM.partner_server.com

&subject_token=baaR3jcJyb4BWCxGsndq23ScbdFMogUC5Pb233jKLTC

&subject_token_type= urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt

B.7.3 Token Exchange Response

Upon successfully receiving and validating the token exchange request message from the MCX client, the IdM server shall return a token exchange response containing a security token specific to the partner IdMS.

The token exchange response standard parameters are shown in table B.7.3-1.

Table B.7.3-1: Token exchange response standard required parameters

Parameter	Values
access_token	REQUIRED. This is the security token specific to the partner IdMS.
issued_token_type	REQUIRED. This field shall be “urn:ietf:params:oauth:token-type:jwt”
token_type	REQUIRED. This field shall be “bearer”
expires_in	RECOMMENDED. The lifetime in seconds of the security token.

An example of a successful token exchange response might look like:

EXAMPLE:

HTTP/1.1 200 OK

Content-Type: application/json

Cache-Control: no-cache, no-store

{

"access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJo

dHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV

4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsIn

N1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo0nhce

PwnQbunD2gw_pDyCFA-Saobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmXklSTp

z0yC7hlSQ",

"issued_token_type":"urn:ietf:params:oauth:token-type:jwt",

"token_type":"Bearer",

"expires_in":600

}

B.7.4 Token Request

In order to exchange the security token for an access token and (optional) refresh token, the MCX client makes a request to the partner authorization server’s token endpoint by sending a token request message with the following parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body. Note that authentication of the security token by the partner IdMS is REQUIRED in order to exchange the security token for an access token. The security token shall be transported in the body of the token request message. The token request standard parameters are shown in table B.7.4-1.

Table B.7.4-1: Token Request standard required parameters

Parameter	Values
grant_type	REQUIRED. This value shall be set to "urn:ietf:params:oauth:grant-type:jwt-bearer" as per rfc 7523 [46].
assertion	REQUIRED. This field shall contain the security token received in annex B.7.3.
client_id	REQUIRED. The identifier of the client making the API request. It shall match the value that was previously registered with the OAuth Provider during the client registration phase of deployment, or as provisioned via a development portal.
scope	REQUIRED. Scope values are expressed as a list of space-delimited, case-sensitive strings which indicate which MCX resource servers the client is requesting access to at the partner system (e.g. MCPTT group services, MCVideo group services, MCData group services, etc.). If authorized, the requested scope values will be bound to the access token returned to the client in the token exchange response message. The scope shall include one or more of the following: – "3gpp:mc:ptt_service" – "3gpp:mc:video_service" – "3gpp:mc:data_service" – "3gpp:mc:ptt_key_management_service" – "3gpp:mc:video_key_management_service" – "3gpp:mc:data_key_management_service" – "3gpp:mc:ptt_config_management_service" – "3gpp:mc:video_config_management_service" – "3gpp:mc:data_config_management_service" – "3gpp:mc:ptt_group_management_service" – "3gpp:mc:video_group_management_service" – "3gpp:mc:data_group_management_service" Others may be added in the future as new MCX resource servers are introduced by 3GPP.

Examples of a successful token request might look like:

EXAMPLE 1:

POST /as/token.oauth2 HTTP/1.1
Host: IdM.server.com:9031
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer& assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsInN1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo0nhcePwnQbunD2gw_pDyCFASaobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmXklSTpz0yC7hlSQ&

client_id=myNativeApp&

scope=openid 3gpp:mc:ptt_group_management_service&

EXAMPLE 2:

POST /as/token.oauth2 HTTP/1.1
Host: IdM.server.com:9031
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer& assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsInN1YiI6ImJjQGV4YW1wbGUuY29tIiwic2NwIjpbImFwaSJdfQ.MXgnpvPMo0nhcePwnQbunD2gwpDyCFASaobl6gyLAdyPbaALFuAOyFc4XTWaPEnHV_LGmXklSTpz0yC7hlSQ&

client_id=myNativeApp&scope=openid 3gpp:mc:ptt_service,3gpp:mc:ptt_key_management_service,3gpp:mc:ptt_config_management_service,3gpp:mc:ptt_group_management_service&

B.7.5 Token Response

If the token request is valid and authorized, the partner IdM server returns an access token to the MCX client specific to the user for the partner services and optionally a refresh token in a token response message; otherwise, it will return an error.

The token response standard parameters are shown in table B.7.5-1.

Table B.7.5-1: Token response standard parameters

Parameter	Values
access_token	REQUIRED. This is the issued access token.
token_type	REQUIRED. This field shall be “bearer”
expires_in	REQUIRED. The lifetime in seconds of the access token.
Id_token	OPTIONAL. This is the issued id token.
Refresh_token	OPTIONAL. This is the issued refresh token.

An example of a successful response might look like:

EXAMPLE:

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache

{

"access_token":"eyJhbGciOiJSUzI1NiJ9.eyJtY3B0dF9pZCI6ImFsaWNlQG9yZy5jb20iLCJleHAiOjE0NTM1MDYxMjEsInNjb3BlIjoib3BlbmlkIDNncHA6bWNwdHQ6cHR0X3NlcnZlciIsImNsaWVudF9pZCI6Im1jcHR0X2NsaWVudCJ9.yXGl0gu3SsRQ_VUrDTWuEp-X8wrj-xUzXzWhTnqntXn0fI6xLR0i6VHtY3L25w81u260bsOFUMiYLLBC0LOKi-SOcwMqrzH6_BZwjkRhExiAciHZNtwgIlHWYwpCuxQII0dcg7_bw_YAFEQQC9IDzsifPXl9JmazI8YMtGcAWohoiSi0KY1pnbORUDBSPLLFlekQH5aOWbe_6EF4pDbm5pH8GXLd_ZtxS7jC6tAAMsCvsRy7Pb_GeDr_jT8-IevGKWO82of7gaUQkF8qnKVagr4-qc2FJeSDuhj4ZvfL510cgcRGy4NJ_7xxS10bzFNLavfqOlgOelJv0KA9IAd-1Q",
"refresh_token": "iTxQYALqlc7uLyFGpnl8tR8Y9gkw91mFy2qC9Yywkz",
"token_type": "Bearer",
"expires_in": 7199
}

The MCX client then uses the access token to make authorized requests to the partner MCX resource servers (MCPTT group management service, MCVideo group management service, MCData group management service, etc) on behalf of the end user.