B.4 Obtaining tokens

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

B.4.1 General

Once a client has been successfully registered with the IdM server of the MCX service provider, the client may request ID tokens and access tokens (as required to access MCX resource servers such as PTT, Video, Data and KMS). MCX Connect will support a number of different MCX client types, including: native, web-based, and browser-based. Only native clients are defined in this version of the MCX Connect profile. The exact method in which a client requests the access token depends upon the client profile. The client profiles, along with steps required from them to obtain OAuth access tokens, are explained in technical detail below.

B.4.2 Native MCX client

B.4.2.1 General

This conforms to the Native Application profile of OAuth 2.0 as per IETF RFC 6749 [19].

MCX clients fitting the Native application profile utilize the authorization code grant type with the IETF RFC 7636 [53] PKCE extension for enhanced security as shown in figure B.4.2.1-1.

Unless indicated otherwise in this document, the use of HTTP Basic authentication shall be as specified in IETF RFC 6749 [19] and IETF RFC 6750 [20].

Figure B.4.2.1-1: Authorization Code flow

B.4.2.2 Authentication request

As described in OpenID Connect 1.0, the IdM client constructs a request URI by adding the following parameters to the query component of the authorization endpoint’s URI using the "application/x-www-form-urlencoded" format, redirecting the user’s web browser to the authorization endpoint of the IdM server. The standard parameters shown in table B.4.2.2-1 are required by the MCX Connect profile. Other parameters defined by the OpenID Connect specification are optional.

Table B.4.2.2-1: Authentication Request standard required parameters

Parameter	Values
response_type	REQUIRED. For native clients the value shall be set to "code".
client_id	REQUIRED. The identifier of the client making the API request. It shall match the value that was previously registered with the IdM server of the MCX service provider.
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 (e.g. MCPTT, MCVideo, MCData, KMS, etc.). If authorized, the requested scope values will be bound to the access token returned to the client. The scope value "openid" is defined by the OpenID Connect standard and is mandatory, to indicate that the request is an OpenID Connect request, and that an ID token should be returned to the client. This profile further defines the following additional authorization scopes: – "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" – "3gpp:mc:location_management_service" Others may be added in the future as new MCX resource servers are introduced by 3GPP (see note).
redirect_uri	REQUIRED. The URI of the client to which the IdM server will redirect the authentication response in order to return the authorization code. The URI shall match the redirect URI registered with the IdM server during the client registration phase.
state	REQUIRED. An opaque value used by the client to maintain state between the authentication request and authentication response. The IdM server includes this value in its authentication response .
acr_values	REQUIRED. Space-separated string that specifies the acr values that the IdM server is being requested to use for processing this authentication request, with the values appearing in order of preference. For minimum interoperability requirements, a password-based ACR value is mandatory to support. "3gpp:acr:password" as per the OpenID Connect 1.0 specification [21].
code_challenge	REQUIRED. The base64url-encoded SHA-256 challenge derived from the code verifier , to be verified against later.
code_challenge_method	REQUIRED. The hash method used to transform the code verifier to produce the code challenge. This profile current requires the usage of "S256"
NOTE: The order in which they are expressed does not matter.

An example of an authentication request for MCX Connect might look like:

EXAMPLE:

GET/as/authorization.oauth2?response_type=code&client_id=idm_client&scope=openid 

3gpp:mc:ptt_service&redirect_uri=http://3gpp.mcptt/cb&state=abc123&acr_values=3gpp:acr:password&code_challenge=0x123456789abcdef&code_challenge_method=S256 

HTTP/1.1
Host: IdMS.server.com:9031
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

Upon receiving the authentication request from the client, the IdM server performs user authentication. Note that user authentication should be completely opaque to the MC services on the client.

B.4.2.3 Authentication response

The authorization endpoint running on the IdM server issues an authorization code and delivers it to the MCX client. The authorization code is used by the MCX client to obtain an ID token, access token and refresh token from the IdM server. The authorization code is added to the query component of the redirection URI using the "application/x-www-form-urlencoded" format. The authorization code standard parameters are shown in table B.4.2.3-1.

Table B.4.2.3-1: Authentication Response standard required parameters

Parameter	Values
code	REQUIRED. The authorization code generated by the authorization endpoint and returned to the client via the authentication response.
state	REQUIRED. The value shall match the exact value used in the authentication request. If the state does not match exactly, then the client is under a Cross-site request forgery attack and shallreject the authorization code by ignoring it and shall not attempt to exchange it for an access token. No error is returned.

An example of an authentication response for MCX Connect might look like.

EXAMPLE:

HTTP/1.1 302 Found

Location:http://mcptt_client/cb?

code=SplxlOBeZQQYbYS6WxSbIA

&state=abc123

B.4.2.4 Access token request

In order to exchange the authorization code for an ID token, access token and refresh token, the MCX client makes a request to the authorization server’s token endpoint by sending 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 client authentication is REQUIRED for native applications (using PKCE IETF RFC 7636 [53]) in order to exchange the authorization code for an access token. If client secrets are used, the client secret is sent in the HTTP Authorization Header as defined in IETF RFC 6749 [19]. The access token request standard parameters are shown in table B.4.2.4-1.

Table B.4.2.4-1: Access token request standard required parameters

Parameter	Values
grant_type	REQUIRED. The value shall be set to "authorization_code".
code	REQUIRED. The authorization code previously received from the IdM server as a result of the authentication request and subsequent successful authentication of the MCX user.
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.
redirect_uri	REQUIRED. The value shall be identical to the "redirect_uri" parameter included in the authentication request.
code_verifier	REQUIRED. A cryptographically random string that is used to correlate the authentication request to the token request.

An example of an access token request for MCX Connect might look like this.

EXAMPLE:

POST /as/token.oauth2 HTTP/1.1
Host: IdM.server.com:9031
Cache-Control: no-cache
Authorization: Basic cnA33hpsb25nABClY3VyZS1yYW5kb20tc2VjdnV0

Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code

&code=SplxlOBeZQQYbYS6WxSbIA

&client_id=myNativeApp

&code_verifier=0x123456789abcdef

&redirect_uri=http://3gpp.mcptt/cb

B.4.2.5 Access token response

If the access token request is valid and authorized, the IdM server returns an ID token, access token and refresh token to the MCX client in an access token response message; otherwise it will return an error.

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

Table B.4.2.5-1: Access 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":"Y7NSzUJuS0Jp7G4SKpBKSOJVHIZxFbxqsqCIZhOEk9",

"id_token":"eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiYXVkIjoibWNwdHRfY2xpZW50IiwiaXNzIjoiSWRNUy5zZXJ2ZXIuY29tOjkwMzEiLCJpYXQiOjE0NTM0OTgxNTgsImV4cCI6MTQ1MzQ5ODQ1OCwibWNwdHRfaWQiOiJhbGljZUBvcmcuY29tIn0.Dpn7AhIMaqMEgg12NYUUfJGSFJMPG8M2li9FLtPotDlHvwU2emBws8z5JLw81SXQnoLqZ8ZF8tIhZ1W7uuMbufF4Wsr7PAadZixz3CnV2wxFV9qR_VA1-0ccDTPukUsRHsic0SgZ3aIbcYKd6VsehFe_GDwfqysYzD7yPwCfPZo",
"token_type": "Bearer",
"expires_in": 7199
}

The MCX client may now validate the user with the ID token and configure itself for the user (e.g. by extracting the MC service ID from the ID Token). The MCX client then uses the access token to make authorized requests to the MCX resource servers (MCPTT server, MCVideo server, MCData server, KMS, etc.) on behalf of the end user.