B.3 Obtaining tokens
33.1793GPPRelease 13Security of Mission Critical Push To Talk (MCPTT) over LTETS
B.3.0 General
Once an MCPTT client has been successfully registered with the IdM server of the MCPTT service provider, the MCPTT client may request ID tokens and access tokens (as required to access MCPTT resource servers such as PTT and KMS). MCPTT Connect will support a number of different MCPTT client types, including: native, web-based, and browser-based. Only native MCPTT clients are defined in this first version of the MCPTT Connect profile. The exact method in which an MCPTT client requests the access token depends upon the client profile. The MCPTT client profiles, along with steps required from them to obtain OAuth access tokens, are explained in technical detail below.
B.3.1 Native MCPTT client
B.3.1.0 General
This conforms to the Native Application profile of OAuth 2.0 as per IETF RFC 6749 [19].
MCPTT clients fitting the Native application profile utilize the authorization code grant type with the PKCE extension for enhanced security as shown in figure B.3.1.0-1.
Figure B.3.1.0-1: Authorization Code flow
B.3.1.1 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.3.1.1-1 are required by the MCPTT Connect profile. Other parameters defined by the OpenID Connect specification are optional.
Table B.3.1.1-1: Authentication Request standard required parameters
|
Parameter |
Values |
|
response_type |
REQUIRED. For native IdM clients the value shall be set to "code". |
|
client_id |
REQUIRED. The identifier of the IdM client making the API request. It shall match the value that was previously registered with the IdM server of the MCPTT service provider. |
|
scope |
REQUIRED. Scope values are expressed as a list of space-delimited, case-sensitive strings which indicate which MCPTT resource servers the client is requesting access to (e.g. MCPTT, 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 MCPTT client. This profile further defines the following additional authorization scopes: – "3gpp:mc:ptt_service" (service authorization) – "3gpp:mc:ptt_key_management_service" (key management authorization) – "3gpp:mc:ptt_config_management_service" (config mgmt authorization) – "3gpp:mc:ptt_group_management_service" (group mgmt authorization) Others may be added in the future as new MCPTT resource servers are introduced by 3GPP (see note). |
|
redirect_uri |
REQUIRED. The URI of the MCPTT client to which the IdM server will redirect the MCPTT client’s IdM Client in order to return the authorization code to the IdM client. 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 MCPTT client to maintain state between the authorization request and authorization response. The IdM server includes this value in its authorization response. |
|
acr_values |
REQUIRED. Space-separated string that specifies the acr values that the IdM server is being requested to use for processing this authorization 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 that is sent in the authorization request, 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 MCPTT Connect might look like:
EXAMPLE:
GET/as/authorization.oauth2?response_type=code&client_id=idm_client&scope=openid 3gpp:mcptt:ptt_server&redirect_uri=e 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 IdM client, the IdM server performs user authentication. Note that user authentication is completely opaque to the IdM client (which never sees any of it, as it is run directly between the IdM server and the IdM client on the UE).
B.3.1.2 Authentication response
The authorization endpoint running on the IdM server issues an authorization code and delivers it to the MCPTT client. The authorization code is used by the MCPTT 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.3.1.2-1.
Table B.3.1.2-1: Authentication Response standard required parameters
|
Parameter |
Values |
|
code |
REQUIRED. The authorization code generated by the authorization endpoint and returned to the MCPTT client via the authorization response. |
|
state |
REQUIRED. The value shall match the exact value used in the authorization request. If the state does not match exactly, then the NGMI API 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 MCPTT Connect might look like.
EXAMPLE:
HTTP/1.1 302 Found
Location: http://mcptt_client/cb?
code=SplxlOBeZQQYbYS6WxSbIA
&state=abc123
B.3.1.3 Token request
In order to exchange the authorization code for an ID token, access token and refresh token, the MCPTT 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) in order to exchange the authorization code for an access token. Assuming that client secrets are used, the client secret is sent in the HTTP Authorization Header. The token request standard parameters are shown in table B.3.1.3-1.
Table B.3.1.3-1: 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 authorization request and subsequent successful authentication of the MCPTT 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 authorization request. |
|
code_verifier |
REQUIRED. A cryptographically random string that is used to correlate the authorization request to the token request. |
An example of a token request for MCPTT Connect might look like.
EXAMPLE:
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=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&client_id=myNativeApp&code_verifier=0x123456789abcdef&redirect_uri=http://3gpp.mcptt/cb
B.3.1.4 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 MCPTT client; otherwise it will return an error.
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 MCPTT client may now validate the user with the ID token and configure itself for the user (e.g. by extracting the MCPTT ID from the ID Token). The MCPTT client then uses the access token to make authorized requests to the MCPTT resource servers (MCPTT server, KMS, etc.) on behalf of the end user.