customer verification (and number share ... share) technical implementation guide version 1.0 table...

Copyright © 2018 GSM Association. The GSM Association (“Association”) makes no representation, warranty or undertaking (express or implied)

with respect to and does not accept any responsibility for, and hereby disclaims liability for the accuracy or completeness or timeliness of the

information contained in this document. The information contained in this document may be subject to change without prior notice.

The Mobile Connect Logo is a trade mark registered and owned by the GSMA.

The information contain herein is in full compliance with the GSM Association’s antitrust compliance policy.

CUSTOMER VERIFICATION (AND NUMBER SHARE) TECHNICAL IMPLEMENTATION GUIDE Version 1.0

Table of Contents Terminology .............................................................................................................................. 1

1. About this Document .......................................................................................................... 2

1.1. Audience ..................................................................................................................... 2

1.2. Assumption ................................................................................................................. 2

1.3. On-net vs Off-net......................................................................................................... 2

1.4. References.................................................................................................................. 3

2. Verified Mobile Number Share ........................................................................................... 4

2.1. Call Flow ..................................................................................................................... 4

3. Discovery Flow ................................................................................................................... 6

3.1. Discovery API Use Case ............................................................................................. 6

3.2. Discovery API Endpoint............................................................................................... 6

3.3. Discovery API Request Parameters ............................................................................ 6

3.3.1. Discovery API Header Request Parameters......................................................... 6

3.3.2. Discovery API Request Parameters ..................................................................... 7

3.3.3. Sample discovery request (IP based) ................................................................... 7

3.4. Discovery Response ................................................................................................... 7

3.4.1. Discovery Response Example ............................................................................. 8

3.4.2. Discovery Error Response ................................................................................... 9

4. Authorisation Code Flow .................................................................................................. 10

4.1. Authorisation Code Parameters and Examples ......................................................... 11

4.1.1. Authorisation Endpoint ....................................................................................... 11

4.1.2. Authorisation Request Parameters ..................................................................... 12

4.1.3. Sample Authorisation Requests ......................................................................... 13

4.1.4. Authorisation Response ..................................................................................... 14

4.2. Access Token Request ............................................................................................. 16

4.2.1. Token Endpoint .................................................................................................. 16

4.2.2. Token Request Parameters ............................................................................... 17

4.2.3. Sample Token Request ...................................................................................... 17

4.2.4. Token Response ................................................................................................ 17

4.2.5. Token Response Example ................................................................................. 18

4.2.6. Token Response – ID Token .............................................................................. 19

4.2.7. Token Error Response ....................................................................................... 22

5. User Info API .................................................................................................................... 24

5.1. User Info API Endpoint .............................................................................................. 24

5.2. User Info API Request Parameters ........................................................................... 24

5.2.1. Sample User Info API Request........................................................................... 24

5.2.2. User Info API Response ..................................................................................... 24

5.2.3. User Info API Response Example ...................................................................... 25

5.2.4. User Info API Response – sub ........................................................................... 26

6. Best Practices .................................................................................................................. 27

6.1. Optimisation .............................................................................................................. 27

6.2. Security ..................................................................................................................... 27

6.2.1. Request Parameters .......................................................................................... 27

6.2.2. Tokens ............................................................................................................... 27

6.2.3. TLS .................................................................................................................... 29

6.2.4. Generic .............................................................................................................. 29

6.2.5. Pop-Up Blocker .................................................................................................. 30

6.2.6. Webview for native apps .................................................................................... 30

6.2.7. Allow vertical scrolling for webview .................................................................... 30

Terminology

Term Description or Terms in an acronym/abbreviation

OP OpenID Connect Provider

RP Relying Party

ID GW Identity Gateway

OIDC OpenID Connect

OTP One Time Password

REST Representational state transfer (REST or RESTful) is a style of software architecture for distributed systems such as the World Wide Web.

SMSC Short Message Service Centre

URI Uniform resource identifier is a string of characters used to identify a name of a web resource.

URL Uniform Resource Locator

MNO Mobile Number Operator

PCR Pseudonymous Customer Reference

LoA Level of Assurance

Identity Programme – Mobile Connect Page 2 of 34

1. About this Document

This document is a guide to building applications which access services protected by OIDC 2.0

authentication and authorisation framework as provided by the OAuth Authorisation Server on

the mobile connect platform.

1.1. Audience

The intended audience for this document are programmers who are developing or modifying

the applications designed to access mobile connect services protected by OAuth 2.0.

Credentials for applications can be had from the GSMA Integration Manager.

1.2. Assumption

This document is designed to provide sufficient information to implement a working solution for

using OAuth protected services. As such, it does not contain a description of the OAuth

protocols. The concepts and requirements of OAuth 2.0 framework are defined in IETF RFC

specifications referenced below.

1.3. On-net vs Off-net The user experience for authorisation and the message exchange between the application and user, and between application and the ID GW, is influenced by the type of network connection being used by the user device to access mobile connect services. At high level, there are two possibilities for mobile device connection:

1. On-net over the MNO’s (Mobile Network Operator) radio access network (RAN) to the

secure MNO network, i.e. on-net means connected on the MNO’s mobile network.

2. Off-net via the Internet, e.g. over Wi-Fi.

The on-net case allows an MNO network gateway to inject the mobile subscriber integrated

services digital network (MSISDN) number for the user into the authorisation request, and by

virtue that it is a trusted gateway on a secure network the authorisation service can trust the

authenticity of the MSISDN. Thus, when using the mobile network data connection, the user is

automatically authenticated, and this gives the best possible user experience by minimizing the

amount of data the user must enter to provide authorisation for an application. In this flow the

user will only be presented with a Terms & Conditions page (for users unregistered with Mobile

Connect [first time users]) and requested to accept or cancel the Ts & Cs. For the MSISDN

injection to occur, the authorisation request must be sent over HTTP, rather than to the secure

endpoint for the authorisation service.

By contrast, the off-net case is over the Internet. Therefore, it does not transit an MNO gateway

and the messages are over an insecure network. The MSISDN number is not available in the


authorisation request, and even if the application is able to insert the MSISDN it cannot be

trusted. For the off-net case secure messaging is required over HTTPS to a secure

authorisation endpoint exposed by the ID GW. The user will be asked to enter their MSISDN,

they will receive a USSD prompt to that MSISDN and they will be asked to allow on USSD

prompt to authenticate that a valid MSISDN has been provided and to authorize login into a

Service provider’s (SP) application.

In order to simplify application development, the authorisation server can accept the initial

authorisation request on the insecure endpoint even for the off-net case. It can detect that the

session is off-net and will redirect the user agent to a secure session. For efficiency and best

possible user experience it will be preferable for an application to use the mobile network data

connection and on-net authorisation where possible. In the case that off-net data connection is

the only choice, the application should, if possible, go directly to the secure end-point, avoiding

redirection from the insecure end-point.

1.4. References

The following guides and specifications must be available for reference. Relevant sections are

noted in the text, as applicable.

Ref#1: Openid-connect Specification at http://openid.net/specs/openid-connect-

core-1_0.html

Ref#2:OAuth 2.0 Authorisation Framework RFC 6749 Specification at

http://tools.ietf.org/html/rfc6749, and Bearer Token Usage Specification RFC 6750

at https://tools.ietf.org/html/rfc6750

Ref#3: https://www.ietf.org/rfc/rfc4122.txt

http://openid.net/specs/openid-connect-core-1_0.html

http://openid.net/specs/openid-connect-core-1_0.html

https://tools.ietf.org/html/rfc6750

https://www.ietf.org/rfc/rfc4122.txt


2. Verified Mobile Number Share

Mobile connect can provide a validated mobile number with the SP from the device used by

the end-user when accessing the service. Mobile Connect can provide either plain text phone

number or in hashed format; the latter has benefit of verification without disclosing phone

number of the user (which helps SP avoid liabilities associated with personal data retention).

Mobile number (plain) is shared with SP after taking end-user’s consent. Consent mechanism

is dependent and decided based on operator’s policy for all SPs or a particular SP.

2.1. Call Flow

Fig. 1 – Call Flow – Verified Mobile Number Share

1. End user browses an SP Portal or App

2. End user makes a service request


3. Service provider makes https POST call to API eXchange to discovery operator on the

basis of device (client) source IP address

4. If source IP of device belongs to mobile connect supported operator, SP will receive json

response with operator details like operator name, credentials and operator endpoints.

Otherwise, SP will receive MSISDN entry page which signifies that user is either on Wi-Fi

or belongs to an unsupported operator and hence user/device identification via mobile

connect is not possible for current transaction

5. SP then creates an ‘authorisation’ URL with necessary parameters and send http 302

response (with authorisation URL set in ‘location’ header) back to end-user’s device

browser

6. Device browser then invokes authorisation API hosted on IDentity GateWay. ID GW

performs necessary validation on request

7. If user is on mobile data of supported operator, ID GW extracts mobile number from

request header. Optionally, as per operator’s policy, user may be asked to give the consent

8.1. User may not allow sharing of mobile number with service provider

9.1. ID GW will send an error response back to service provider

8.2. User may give consent on sharing mobile number with service provider

9.2. ID GW will generate an authorisation code and send it to service provider on the

redirect uri of the service provider

9. In case, user’s consent is not required and ID GW is able to extract mobile number from

request header, an authorisation code will be generated and sent to service provider by ID

GW

10. In case, ID GW cannot extract mobile number of the header, ID GW generates an error

response and sends it to service provider

11. Service provider invokes token API with authorisation code as request parameter

12. ID GW validates the token request and issues an access token and id token

13. Service provider validates id token and invokes user info API using access token

14. ID GW validates access token and service provider credentials and sends back mobile

number in response

15. Service provider may optionally send a success message to consumption device or

continue silently


3. Discovery Flow

The Discovery Service provides the developer with details of the mobile operator that serves

the end user. Once you obtain the details for a specific user you can perform the Mobile

Connect API calls to authorise that user.

3.1. Discovery API Use Case

A user accessing your service from a mobile device on mobile data network

Implicit: Invoke Discovery API from the device with the mobile data network to

obtain the details required to perform the Mobile Connect authorisation process.

Explicit: Device with mobile data hits SP’s application server. SP’s application

server retrieves device source IP and use it in header to invoke discovery API.

3.2. Discovery API Endpoint

Endpoint for invoking discovery API:

https://india.discover.mobileconnect.io/gsma/v2/discovery

Communication with the discovery End-Point MUST use TLS. The request could either be

HTTP GET or HTTP POST.

3.3. Discovery API Request Parameters

3.3.1. Discovery API Header Request Parameters

Following header parameter should be sent while calling discovery API:

Header Description Mandatory

Authorisation The value MUST be set to "Basic <base-

64(clientid:clientsecret)>"

Yes

X-Source-ip Device source IP No

Table 1: Discovery Request Header Parameters

https://india.discover.mobileconnect.io/gsma/v2/discovery


3.3.2. Discovery API Request Parameters Following request parameters need to be used for invoking discovery API:

Parameter Description Method Mandatory

Redirect_URL The Redirect URL that you set when you

create your Application that determines where

Discovery Service sends responses to your

OperatorSelection request.

POST/GET Yes

correlation_id correlation_id can be used to uniquely identify

and trace the call.

POST/GET No

Table 2: Discovery API Request Parameters

3.3.3. Sample discovery request (IP based)

POST https://discover.mobileconnect.io/gsma/v2/discovery HTTP/1.1

Authorisation: Basic ODhhZTNiNWQtMThmMS00ZmM1LWE5ODFhLTFhY2IxMmJhMzM0ZA==

X-source-ip: 10.20.30.40

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

Cache-Control: no-cache

Redirect_URL=http%3A%2F%2Flocalhost%3A8080%2FMCIndiaDummy%2Fcal

3.4. Discovery Response

Discovery response is constructed by adding the following parameters to the entity-body of the

HTTP response with a 200 (OK) status code. There are multiple types of response depending

on the request.

Parameter Data Type Description

ttl timestamp "time to live", the expiry timestamp when this discovery details are

no longer valid.

response object Details of the serving mobile operator that you will require to

perform API requests to.

client_id string client_id part of your credential to be used by OIDC requests.

client_secret string client_secret part of your credential to be used by OIDC requests.

serving_operat

or

string Name of the serving mobile operator.

country string Country name of the serving mobile operator.

currency string Currency of the serving mobile operator.

apis object Available APIs from the serving mobile operator.

operatorid object Operator Identity API.

link[] list collection of available links.

link[].href string The relationship of the links object.

https://discover.mobileconnect.io/gsma/v2/discovery


Parameter Data Type Description

link[].rel string The full url to the links object.

correlation_id string correlation_id value if passed in request.

Table 3: Discovery Response Parameters

The parameters are included in the entity-body of the HTTP response using the

"application/json" media type.

The parameters are serialised into a JavaScript Object Notation (JSON) structure by adding

each parameter at the highest structure level. Parameter names and string values are included

as JSON strings. Numerical values are included as JSON numbers. The order of parameters

does not matter and can vary.

The application MUST ignore unrecognised value names in the response. The application

should avoid making assumptions about value sizes.

3.4.1. Discovery Response Example

{

"ttl": 1483574961,

"response": {

"client_id": "x-88ae3b5d-18f1-abcd-a97e-a6c5eae9cd5a",

"client_secret": "x-5d6c7979-axyz-4b45-a81a-1acb12ba334d",

"serving_operator": "vodafone_india",

"country": "India",

"currency": "Rupee",

"apis": {

"operatorid": {

"link": [

{

"href": "http://india.gateway.wso2telco.com/authorize/v1/vodafone/oauth2/authorize",

"rel": "authorisation"

},

{

"href": "https://india.gateway.wso2telco.com/token/v1/vodafone/oauth2/token",

"rel": "token"

},

{

"href": "https://india.mconnect.wso2telco.com/oauth2/userinfo?schema=openid",

"rel": "userinfo"

}

]

}

}

}

}


3.4.2. Discovery Error Response

In case of any error because of invalid or missing parameters or any other such cause, the

discovery url server informs the application by responding with a json response.

Parameter Description Present

error Invalid_Request

Redirect_URL not provided.

Unauthorised_Access

Invalid session or authorisation credentials.

Invalid_Session

Using an invalid session or the session expired.

Backend_Call_Failed

Backend Service Down.

Always

description Human-readable ASCII [USASCII] text providing additional

information, used to assist the client developer in

understanding the error that occurred. Values for the

"description" parameter will not include characters outside the

set %x20-21 / %x23-5B / %x5D-7E.

Always

Table 4: Discovery Error Response

Response-Error Scenario: Missing Redirect URL

Http Response Code: 400 Bad Request

{

"error": "Invalid_Request",

"description": "Redirect_URL missing"

}

Response-Error Scenario: No Authorisation

Http Response Code: 401 Unauthorised

{

"error": "Unauthorised_Access",

"description": "Your request needs a valid session or valid credentials"

}

Response-Error Scenario: Bad Session

Http Response Code: 401 Unauthorised

{

"error": "Invalid_Session",

"description": "Your request needs a valid session"

}


4. Authorisation Code Flow

The Authorisation Code Flow returns an Authorisation Code to the Client, which can then

exchange it for an ID Token and an Access Token directly. This provides the benefit of not

exposing any tokens to the User Agent and possibly other malicious applications with access

to the User Agent. The Authorisation Server can also authenticate the Client before

exchanging the Authorisation Code for an Access Token. The Authorisation Code flow is

suitable for Clients that can securely maintain a Client Secret between themselves and the

Authorisation Server.

Authorisation Code Flow Features:

Feature Authorisation Code Flow

Tokens returned from Token Endpoint Yes

Tokens not revealed to User Agent Yes

Client can be Authenticated Yes

Refresh Token Possible Yes

Communication in one round-trip No

Server-to-server communication Yes

Table 5: Authorisation Code Flow Features

The Code Flow consists of the following steps:


0. The user is using the service from the SP, and the use case needs to authenticate the

Service User

1. The SP prepares the OIDC Authorisation request and sends that to the Authorisation

endpoint at the ID GW, passing the LoA needed in the Request Object

2. The ID GW selects the appropriate authenticator for the LoA and authenticates the user

3. The ID GW returns the Authorisation Code to the SP

4. The SP sends the token request to the token endpoint at the ID GW, passing the

Authorisation code

5. The ID GW validates the Authorisation code and returns the access token along with

the ID Token JWT – containing the authentication context, and optionally a refresh

token

a. The SP gets the PCR and the authentication context [i.e. when and how the

authentication processed]

6. If needed, the SP can call the UserInfo/ PremiumInfo endpoints at the ID GW to get the

essential attributes, passing the access token

4.1. Authorisation Code Parameters and Examples

This section lists the parameters required in each of the OIDC request operations in the

sequence described above, those returned in successful responses and in error responses,

together with selected message examples. Notes are supplied for the operations where

applicable.

The application (client) issues a redirect to the subscriber device browser in a GET operation

as follows: the application constructs the request URI by adding the following parameters to

the query component of the authorisation endpoint URI using the "application/x-www-form-

urlencoded" format.

4.1.1. Authorisation Endpoint

Authorisation endpoint is different for each operator. Endpoint is received in discovery API

response:

http://india.gateway.wso2telco.com/authorize/v1/{operator}/oauth2/authorize

e.g.,

http://india.gateway.wso2telco.com/authorize/v1/airtel/oauth2/authorize

http://india.gateway.wso2telco.com/authorize/v1/%7boperator%7d/oauth2/authorize

http://india.gateway.wso2telco.com/authorize/v1/airtel/oauth2/authorize


4.1.2. Authorisation Request Parameters

Parameter Description Mandatory

response_type Value MUST be set to "code".

OAuth 2.0 Response Type value that determines the

authorisation processing flow to be used, including what

parameters are returned from the endpoints used. When using

the Authorisation Code Flow, this value is code.

Yes

client_id OAuth 2.0 Client Identifier valid at the Authorisation Server.

client_id is received in the discovery response.

Yes

redirect_uri URL of a callback on the application.

After completing its interaction with the resource owner, the

authorisation server directs the resource owner's user-agent

back to the client. The authorisation server redirects the user-

agent to the client's redirection endpoint previously established

with the authorisation server during the client registration

process or when making the authorisation request.

The endpoint URI MAY include an "application/x-www-form-

urlencoded" formatted query component, which MUST be

retained when adding additional query parameters. The

endpoint URI MUST NOT include a fragment component.

Both HTTP and HTTPS schemes are allowed; The

recommended scheme is HTTPS.

Yes

scope The scope of the resource access to be authorised, as defined

on the authorisation service for the service (resource) being

requested. The value of the scope parameter is expressed as a

list of space-delimited, case-sensitive strings.

OIDC Authorisation request MUST contain the scope value

“openid”. If no openid scope value is present, the request may

still be a valid OAuth 2.0 request, but is not an OpenID Connect

request.

Scope to be used for this use case is:

openid+mc_attr_vm_share for plain mobile number sharing or,

openid+mc_attr_vm_share_hash for hashed mobile number

sharing.

Yes

state Opaque value used to maintain state between the request and

the callback. Typically, Cross-Site Request Forgery (CSRF,

XSRF) mitigation is done by cryptographically binding the value

of this parameter with a browser cookie.

Yes

acr_values The acr_values are indication of what authentication methods to

used by the IDP. The authentication methods to be used are

Yes



linked to the LOA value passed in the acr_values. The IDP

configures the authentication method selection logic based on

the acr_values.

nonce String value used to associate a Client session with an ID

Token, and to mitigate replay attacks. The value is passed

through unmodified from the Authentication Request to the ID

Token. Sufficient entropy MUST be present in the nonce values

used to prevent attackers from guessing values.

Although, there is no length specified as per OIDC specs,

however, because of implementation constraints, max length for

nonce is defined as 100.

No

Table 6: Authorisation Request Parameters

Refer to OpenID Connect Specifications [Ref#1] for more optional parameters.

Authorisation Request Parameters – scope

Scopes for sharing mobile number (plain/hashed) with SP after user consent:

openid+mc_attr_vm_share – this is an onnet (works only on mobile data) only scope which

can be used for getting plain text user mobile number of the verified user after taking explicit

user consent.

openid+mc_attr_vm_share_hash – this is an onnet (works only on mobile data) only scope

which can be used for getting hashed user mobile number of the verified user.

4.1.3. Sample Authorisation Requests

mc_attr_vm_share

http://india.gateway.wso2telco.com/authorize/v1/airtel/oauth2/authorize?client_id=x-883b5d-18f1-

4fc5-a97e-

a6c5eae9cd5a&scope=openid+mc_attr_vm_share&response_type=code&redirect_uri=http://localhost

:8080/MCIndiaDummy/callback&acr_values=2&nonce=12345&state=12345

mc_attr_vm_share_hash

http://india.gateway.wso2telco.com/authorize/v1/airtel/oauth2/authorize?client_id=x-883b5d-18f1-

4fc5-a97e-

a6c5eae9cd5a&scope=openid+mc_attr_vm_share_hash&response_type=code&redirect_uri=http://loc

alhost:8080/MCIndiaDummy/callback&acr_values=2&nonce=12345&state=12345


4.1.4. Authorisation Response

If the mobile number in request matches mobile number received from header, the

authorisation server issues an authorisation code and delivers it to the application by adding

the following parameters to the query component of the redirection URI using the

"application/x-www-form-urlencoded" format.

The client MUST ignore unrecognised response parameters.

There are no service specific parameters in authorisation responses.


code The authorisation code generated by the authorisation server.

The authorisation code will normally be in form of a UUID and

may include other identifiers. A length of up to 72 characters

should be considered. However, the application should not

make assumptions about the code value size.

The authorisation code will expire shortly after it is issued to

mitigate the risk of leaks. A maximum authorisation code

lifetime of 10 minutes should be expected and the code should

be used as soon as possible. The client MUST NOT use the

authorisation code more than once. If an authorisation code is

used more than once, the authorisation server will deny the

request.

Always

state PRESENT IF the "state" parameter was present in the client

authorisation request. The exact value received from the client.

If in the

request

Table 7: Authorisation Response Parameters

Authorisation Response Example

An example of a successful authorisation response to the application, including the authorisation code. Browser interaction traces have been omitted from the initial request to this response.

HTTP/1.1 302 Found

Location: https://client.example.org?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

Authorisation Error Response

If the authentication fails, the authorisation server informs the application by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format. There are no service specific parameters in authorisation error responses.



error A single ASCII error code from the following:

unsupported_response_type

The authorisation server does not support obtaining an

authorisation code using this method.

server_error

The authorisation server encountered an unexpected

condition that prevented it from fulfilling the request.

(This error code is needed because a 500 Internal

Server Error HTTP status code cannot be returned to

the client via an HTTP redirect.)

Eg.

https://client.example.org/cb?error=server_error&state=

xyz

temporarily_unavailable

The authorisation server is currently unable to handle

the request due to a temporary overloading or

maintenance of the server. (This error code is needed

because a 503 Service Unavailable HTTP status code

cannot be returned to the client via an HTTP redirect.)

Eg.

https://client.example.org/cb?error=temporarily_unavaila

ble&state=xyz

access_denied

The resource owner or authorisation server denied the

request.

Eg. error=access_denied& state=12345

invalid_request

The request is missing a required parameter, includes

an invalid parameter value, includes a parameter more

than once, or is otherwise malformed.

• Invalid request error can occur when the state

parameter is missing or invalid

Eg.

https://client.example.org/cb?error=invalid_request&erro

r_description=state_Required

• Invalid request error can occur when the response

type parameter is missing or invalid

Eg.

https://india.mconnect.wso2telco.com/authenticationend

point/oauth2_error.do?oauthErrorCode=invalid_request

&oauthErrorMsg=invalid_request%2C+Missing+respons

e_type+parameter+value

invalid_client

The client is not authorised to request an authorisation

code using this method.

• Client id is invalid or unavailable

Eg. 401 unauthorised

<ams:fault>

Always

https://client.example.org/cb?error=server_error&state=xyz

https://client.example.org/cb?error=server_error&state=xyz

https://client.example.org/cb?error=temporarily_unavailable&state=xyz

https://client.example.org/cb?error=temporarily_unavailable&state=xyz

https://client.example.org/cb?error=invalid_request&error_description=state_Required

https://client.example.org/cb?error=invalid_request&error_description=state_Required

https://india.mconnect.wso2telco.com/authenticationendpoint/oauth2_error.do?oauthErrorCode=invalid_request&oauthErrorMsg=invalid_request%2C+Missing+response_type+parameter+value






<ams:code>900902</ams:code>

<ams:message>Missing Credentials</ams:message>

<ams:description>Required OAuth credentials not

provided</ams:description>

</ams:fault>

invalid_callback

The Registered callback does not match with the

provided url.

Eg.

https://india.mconnect.wso2telco.com/authenticationend

point/oauth2_error.do?oauthErrorCode=invalid_callback

&oauthErrorMsg=Registered+callback+does+not+match

+with+the+provided+url

error_descripti

on

Human-readable ASCII [USASCII] text providing additional



"error_description" parameter will not include characters

outside the set %x20-21 / %x23-5B / %x5D-7E.

Always

state PRESENT If a "state" parameter was present in the

application authorisation request. The exact value received

from the application.

If in the

request

Table 8: Authorisation Error Response Parameters

4.2. Access Token Request

The Client makes an Access Token Request using the Authorisation Code to obtain tokens

from the Token Endpoint. Communication with the Token End-Point MUST use TLS. The

request encoding used is application/x-www-form-urlencoded using the HTTP POST method.

4.2.1. Token Endpoint

Token endpoint is different for each operator. Endpoint is received in discovery API response:

https://india.gateway.wso2telco.com/token/v1/{operator}/oauth2/token

e.g.,

https://india.gateway.wso2telco.com/token/v1/airtel/oauth2/token

https://india.mconnect.wso2telco.com/authenticationendpoint/oauth2_error.do?oauthErrorCode=invalid_callback&oauthErrorMsg=Registered+callback+does+not+match+with+the+provided+url




https://india.gateway.wso2telco.com/token/v1/%7boperator%7d/oauth2/token



4.2.2. Token Request Parameters

On receiving a successful authorisation response, the following parameters are required in all

access token requests, regardless of the applicable service.


grant_type The value MUST be set to "authorisation_code". Yes

code The authorisation code received from the authorisation server. Yes

redirect_uri The value of this parameter MUST be identical to the

"redirect_uri" included in the authorisation request.

Yes

Table 9: Access Token Request Parameters

Following header parameter should be sent while calling token API:


Authorisatio

n

The value MUST be set to "Basic <base-64(clientid:clientsecret)>" Yes

Table 10: Access Token Request Header Parameters

4.2.3. Sample Token Request

POST https://india.gateway.wso2telco.com/token/v1/airtel/oauth2/token HTTP/1.1

Connection: close

Authorisation: Basic ZDYzNDBjYWM0OGY3NjRhZTI3MzVhYTNiMDIyMGM3NjI6e0dFV1c+M20=

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

grant_type=authorisation_code&client_id=d6340cac48f764ae2735aa3b0220c762&redirect_uri=http://

merchant.site.com/webservice/callback&code=550e8400-e29b-41d4-a716-446655440000

4.2.4. Token Response

The token response is in accordance with OAuth 2.0 and encoded in UTF-8. If the access token request is valid and authorised, the authorisation server issues an access

token and optional refresh token. It constructs the response by adding the following

parameters to the entity-body of the HTTP response with a 200 (OK) status code.

There are no service specific parameters in access token responses.


access_token Access Token for the UserInfo Endpoint. Always

token_type OAuth 2.0 Token Type value. The value MUST be Bearer,

as specified in OAuth 2.0 Bearer Token Usage [RFC6750],

for Clients using this subset.

Always

expires_in Expiration time of the Access Token in seconds since the

response was generated.

Optional

scope A copy of the scope from the client request. Always

refresh_token Refresh Token. Optional




id_token The ID Token is a security token that contains Claims about

the authentication of an End-User by an Authorisation

Server when using a Client, and potentially other requested

Claims. The ID Token is represented as a JSON Web

Token (JWT) [JWT].

Always

Table 11: Access Token Response Parameters




each parameter at the highest structure level. Parameter names and string values are included

as JSON strings. Numerical values are included as JSON numbers. The order of parameters

does not matter and can vary.

The authorisation server includes the HTTP "Cache-Control" response header field with a

value of "no-store", as well as the "Pragma" response header field with a value of "no-cache".



4.2.5. Token Response Example

An example of a successful access token response to the application, with the access token: Response Header: Content-Type: application/json

{

"scope": "openid",

"token_type": "bearer",

"expires_in": 157640000,

"refresh_token": "2111b43bb6f9ba91d07bee335eba1ac",

"id_token":

"eyJhbGciOiJSUzI1NiJ9.eyJhdXRoX3RpbWUiOjE0ODA0ODQ1ODMsImV4cCI6MTYzODEyNDU4My

wic3ViIjoibjJyQmN0Z1F3U25RV1dGOTZsZCUyRlFVWlYwWG1QSFJSbnRFR0IxNzFGZkVkZnAxZ2k

lMkZwdUt3Vld3OVNSYmhYazYlMEQlMEEiLCJhenAiOiJ4LTg4YWUzYjVkLTE4ZjEtNGZjNS1hOTdlL

WE2YzVlYWU5Y2Q1YSIsImF0X2hhc2giOiJNbVkzTkRWak5EZzRZelV6WTJNNU1tTTJNV1U1TTJJ

ME4yRTJNMkZrIiwibm9uY2UiOiIxMjM0NTY3OCIsImF1ZCI6WyJ4LTg4YWUzYjVkLTE4ZjEtNGZjNS1

hOTdlLWE2YzVlYWU5Y2Q1YSJdLCJpc3MiOiJodHRwczpcL1wvbG9jYWxob3N0Ojk0NDNcL29hdXR

oMmVuZHBvaW50c1wvdG9rZW4iLCJpYXQiOjE0ODA0ODQ1ODMsImFjciI6IjIiLCJhbXIiOiJNU0lTRE

5BdXRoZW50aWNhdG9yLFVTU0RBdXRoZW50aWNhdG9yIn0.WqWfa-Cw-

VxYHCoIupjTXdbsrDqRXNcjLZlE-

D4RgZAuQzF66ajk9pF3YGFT9AZcpCEQkBMC0LOuE8GsQFDHDiU3o5iAnvwma22w8BeAHBYED

WbDpOTf0rb2rPWwVU1vqt7t26vZjGPTnaMrfP_VMAh_vx8RfCI-rNDiCmVfzRo",

"access_token": "2f745c488c53cc92c61e93b47a63ad"

}


4.2.6. Token Response – ID Token

The ID Token is a security token that contains Claims about the authentication of an End-User

by an Authorisation Server when using a Client, and potentially other requested Claims. The ID

Token is represented as a JSON Web Token (JWT).

JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be

transferred between two parties.

The JWT comes in 3 parts separated by "."

e.g.,

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJub25jZSI6Im5vbmNlXzAucHBzdHR1aGFwNWV

6aDBrOSIsInN1YiI6IjMyMzljNmQxNmYzYjAxM2FmYTZkMTFkZjc1OTIyYWY0IiwiYW1yIjoiU01

TX1VSTCIsImF1dGhfdGltZSI6MTQ0NjY0MDgyOSwiYWNyIjoiMiIsImF6cCI6IjBjOWRmMjE5Iiw

iaWF0IjoxNDQ2NjQwODI5LCJleHAiOjE0NDY2NDQ0MjksImF1ZCI6WyIwYzlkZjIxOSJdLCJpc

3MiOiJodHRwOi8vb3BlcmF0b3JfYS5zYW5kYm94Lm1vYmlsZWNvbm5lY3QuaW8vb2lkYy9hY

2Nlc3N0b2tlbiJ9.VuJFR71XqEGZmC1bnrn9iWUReYm0iJAji1oWailXqjk

The first part (highlighted in yellow) is the header. It usually contains information on how the

id_token is signed.

The second part (highlighted in blue), is the token payload. This contains all the claims that are

being passed over by the operator.

The third part (highlighted in green) is the signature hash. Using information obtained from the

header, you will know which hashing algorithm to use. If the hash result of the first and the

second parts matches the third part, you will know that this id_token has not been tampered

with and can be trusted. If they don´t match, there is a chance that the id_token is corrupted or

has been tampered at some point and should not be trusted.

Decoding

The JSON Web Token is encoded using Base64URL format. This is not the same as Base64.

Base64 has some characters which are not URL safe such as "+", "/" and "=".

To make it URL safe, the "=" which is the padding is removed. The "+" sign is replaced with "-"

and the "/" sign is replaced with "_". So, to revert the process, the id_token part needs to:

1. 1. Replace any "-" sign to "+"

2. 2. Replace any "_" sign to "/"

3. 3. Add extra "=" padding to the string based on modulo 4

Example, "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9" (since there isn't any "-" or "_" sign,

there is nothing to replace). The length of this header value is 36. "36 % 4" modulo 4 = 0, so

this means that there is no extra padding to be added. This string can now be passed into a

base64decoder to be decoded.


Note: most of the base64 decoding will auto pad this, but for some cases such as VB.net, you

will have to manually insert the padding to work.

Validating

There are multiple hash algorithm used to validate the id_token, such as HS256, HS512,

RS256, RS512. They are specified in the "header" part of the id_token.

example.

{

"typ": "JWT",

"alg": "HS256"

}

With that in mind, you will hash the value of

"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJub25jZSI6Im5vbmNlXzAucHBzdHR1aGFwNW

V6aDBrOSIsInN1YiI6IjMyMzljNmQxNmYzYjAxM2FmYTZkMTFkZjc1OTIyYWY0IiwiYW1yIjoiU

01TX1VSTCIsImF1dGhfdGltZSI6MTQ0NjY0MDgyOSwiYWNyIjoiMiIsImF6cCI6IjBjOWRmMjE5

IiwiaWF0IjoxNDQ2NjQwODI5LCJleHAiOjE0NDY2NDQ0MjksImF1ZCI6WyIwYzlkZjIxOSJdLCJ

pc3MiOiJodHRwOi8vb3BlcmF0b3JfYS5zYW5kYm94Lm1vYmlsZWNvbm5lY3QuaW8vb2lkYy9

hY2Nlc3N0b2tlbiJ9"

with the secret or public key to get a hash (in the above case, using a secret with HS256

algorithm). Compare the result with the passed signature

"VuJFR71XqEGZmC1bnrn9iWUReYm0iJAji1oWailXqjk". If they match, the id_token is

validated.

References

There are many open source libraries publicly available that provides the capability to decode

and verify the id_token. http://jwt.io provides a basic functionality to decode id_token as well as

links to different library for different programming languages that you can download and use.

Sample decrypted id_token (2nd part):

{

"auth_time":1480484583,

"exp":1638124583,

"sub":"n2rBctgQwSnQWWF96ld%2FQUZV0XmPHRRntEGB171FfEdfp1gi%2FpuKwVWw9SRbhXk6

%0D%0A",

"azp":"x-88ae3b5d-18f1-4fc5-a97e-a6c5eae9cd5a",

"at_hash":"MmY3NDVjNDg4YzUzY2M5MmM2MWU5M2I0N2E2M2Fk",

"nonce":"12345678",

"aud":[

"x-88ae3b5d-18f1-4fc5-a97e-a6c5eae9cd5a"

],

"iss":"https:\/\/localhost:9443\/oauth2endpoints\/token",

"iat":1480484583,

"acr":"2",

"amr":"MSISDNAuthenticator,USSDAuthenticator"

}

http://jwt.io/


The following Claims are used within the ID Token:


iss Issuer Identifier for the Issuer of the response. The iss

value is a case-sensitive URL using the https scheme that

contains scheme, host, and optionally, port number and

path components and no query or fragment components.

Always

sub Subject identifier. A globally unique identifier (PCR) of the

end -user to work in a federated environment. It is a case-

sensitive ASCII string with a maximum length of 255. The

sub value does not contain the MSISDN.

Always

aud Audience(s) that this ID Token is intended for. It MUST

contain the OAuth 2.0 client_id of the Relying Party as an

audience value. It MAY also contain identifiers for other

audiences. In the general case, the aud value is an array of

case-sensitive strings. In the common special case when

there is one audience, the aud value MAY be a single case-

sensitive string.

Always

exp Expiration time on or after which the ID Token MUST NOT

be accepted for processing. The processing of this

parameter requires that the current date/time MUST be

before the expiration date/time listed in the value.

Its value is a JSON [RFC7159] number representing the

number of seconds from 1970-01-01T00:00:00Z as

measured in UTC until the date/time.

Always

iat The time of issue of the ID Token. The format is the number

of seconds from 1970-01-01T0:0:0Z as measured in UTC

until the date/time specified.

Always

auth_time Time of end-user authentication or authorisation. The

format is the number of seconds from 1970-01-01T0:0:0Z

as measured in UTC until the date/time specified.

Always

nonce String value used to associate a client session with the ID

Token. It is passed unmodified from Authorisation Request

to ID Token. The value SHOULD be unique per session to

mitigate replay attacks. For the Mobile Connect Profile, it is

a recommended parameter.

Always

acr Authentication Context Class Reference. It’s a case

sensitive string, representing the fact that the authentication

process followed the acr [e.g. LOA] requested or not.

Always

amr Authentication Methods References. An array of case-

sensitive strings to indicate the authentication method used.

The values need to be negotiated offline (e.g.,

MSISDNAuthenticator,USSDAuthenticator)

Always

azp Authorised Party – the party to which the ID Token is

issued. Represented as the client_id of the party.

Always

at_hash A base64url encoded value of the hash of the access_token

[the hash algorithm is negotiated during registration].

Optional

Table 12: ID Token Claims


4.2.7. Token Error Response

In case of any error because of invalid or missing parameters or any other such cause, the authorisation server informs the application by responding with a json response.


error invalid_request

The request is missing a required parameter, includes

an invalid parameter value, includes a parameter more

than once, or is otherwise malformed.

• Invalid request error can occur when the grant type

parameter is invalid

Eg. 400 Bad Request

{"error":"invalid_request","error_description":"Invalid

grant_type parameter value"}

• Invalid request error can occur when the grant type

parameter is missing

Eg. 400 Bad Request

{"error":"invalid_request","error_description":"Missing

grant_type parameter value"}

• Invalid request error can occur when the code


Eg. 400 Bad Request


parameters: code"}

• Invalid request error can occur when the redirect uri


Eg. 400 Bad Request


parameters: redirect_uri"}

invalid_grant

The request is missing a valid authorisation code.

• Invalid grant error can occur when the code parameter

is invalid

Eg. 400 Bad Request

{"error":"invalid_grant","error_description":"Provided

Authorisation Grant is invalid."}

invalid_client

The client is not authorised to request an token using

this method.

• Client id is invalid or unavailable

Eg. 401 unauthorised

<ams:fault>

<ams:code>900902</ams:code>

<ams:message>Missing Credentials</ams:message>

<ams:description>Required OAuth credentials not

provided</ams:description>

</ams:fault>

server_error

Always



The authorisation server encountered an unexpected

condition that prevented it from fulfilling the request.

(This error code is needed because a 500 Internal

Server Error HTTP status code cannot be returned to

the client via an HTTP redirect.)

error_descripti

on

Human-readable ASCII [USASCII] text providing additional



"error_description" parameter will not include characters

outside the set %x20-21 / %x23-5B / %x5D-7E.

Always

Table 13: Access Token Error Response


5. User Info API User Info API returns user info according to the claim(s) specified during authorisation.

5.1. User Info API Endpoint

https://india.mconnect.wso2telco.com/oauth2/userinfo?schema=openid

5.2. User Info API Request Parameters

Following header parameter should be sent while calling user info API:


Authorisation The value MUST be set to "Bearer <access token>" Yes

Table 14: User Info API Request Header Parameters

5.2.1. Sample User Info API Request

GET https://india.mconnect.wso2telco.com/oauth2/userinfo?schema=openid HTTP/1.1

Connection: close

Authorisation: Bearer d55dc0b1b0818d5815caac2295058a2

5.2.2. User Info API Response

If the user info API request is valid and authorised, the ID GW constructs the response by

adding the following parameters to the entity-body of the HTTP response with a 200 (OK)

status code.


sub Subject identifier. A globally unique

identifier (PCR) of the end -user to

work in a federated environment. It is

a case-sensitive ASCII string with a

maximum length of 255. The sub value

does not contain the MSISDN.

This value should match with the sub

value received in id_token from token

response.

Always

device_msisdn Plain text msisdn returned to SP in

E.164 format e.g., 919958123456

Optional. Present when

scope=openid+mc_attr_vm_shar

e

https://india.mconnect.wso2telco.com/oauth2/userinfo?schema=openid



device_msisdn_h

ash

SHA-256 hashed value of

device_msisdn. E.g.,

fd05057195c3b8345714de5d3039ce1

7b157b3d4f13760a422a4915e746ae8

e2

Optional. Present when

scope=openid+mc_attr_vm_shar

e_hash

Table 15: User Info API Response Parameters




each parameter at the highest structure level. Parameter names and values are included as

JSON strings. The order of parameters does not matter and can vary.



5.2.3. User Info API Response Example

An example of a successful user info API response:

Response Header: Content-Type: application/json Plaint text mobile number (scope=mc_attr_vm_share)

{

"sub":

"n2rBctgQwSnQWWF96ld%2FQUZV0XmPHRRntEGB171FfEdfp1gi%2FpuKwVWw9SRbhXk6%0D%

0A",

"device_msisdn": "919958123456"

}

Plain text mobile number (scope=mc_attr_vm_share_hash)

{

"sub":

"n2rBctgQwSnQWWF96ld%2FQUZV0XmPHRRntEGB171FfEdfp1gi%2FpuKwVWw9SRbhXk6%0D%

0A",

"device_msisdn_hash":

"fd05057195c3b8345714de5d3039ce17b157b3d4f13760a422a4915e746ae8e2"

}


5.2.4. User Info API Response – sub

PCR stands for "Pseudonymous Customer Reference". This is a unique identifier that Mobile

Connect uses to reference an end user. The PCR is a unique id that always represents a

specific user. Hence pseudonymous.

By leveraging the PCR, the user's privacy is protected while the service provider is assured

that this is an actual user. Developers can then request additional information about a user

with his consent. This allows users to be confident that their personal information will only be

shared with their explicit consent.

A PCR is unique to each application and user combined. Other Mobile Connect-enabled

service providers will not be able to copy and use your application's PCR in their system. In the

unlikely event third parties gained access to a PCR, the user’s information would not be

compromised.

Mobile connect generates PCR value after successful authentication and pass it under “sub”

parameter in id_token.

The PCR is generated as a GUID [UUIID Version 4 – as defined in RFC 4122 [Ref#3],

including the byte ordering]

The PCR is unique to the user [MSISDN] and the SP Sector ID [the Sector ID could be

same for different applications of the same SP]

The PCR is associated with the MSISDN + Sector ID [HOST part of the redirect_uri

registered by the service provider]

The SP may associate the PCR with the user account at their end – they need to do an

association of the PCR with their account

The PCR is generated independent of the MSISDN [the GUID is generated independently] -

although there is an association of the PCR with the MSISDN and needs to maintain that

association depending on the lifecycle events:

Event: MSISDN of the user changes, user is in the same MNO. Action: PCR changes

Event: MSISDN is recycled. Action: PCR changes

Event: MSISDN is ported out: Action: PCR may remain same [if user wants to port out

the Mobile Connect Account]


6. Best Practices redirect_uri: When using this flow, the Redirection URI SHOULD use the https scheme;

however, it MAY use the http scheme, provided that the Client Type is confidential, as defined

in Section 2.1 of OAuth 2.0

6.1. Optimisation

Service provider should improve application performance by following various aspects that will

give better user experience. Service provider should consider following points to optimize the

application.

Service provider should cache Discovery results, Operator Details along with other parameters that returns from Discovery.

It should also cache other reusable parameters used during authentication request like LoA etc.

Service provider should also cache attributes received from id_token including id_token expiry date.

Service provider must validate the expiry of id_token before initiating authentication request.

6.2. Security

6.2.1. Request Parameters

• state is an opaque value used to maintain state between the request and the callback.

Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by

cryptographically binding the value of this parameter with a browser cookie.

• nonce is used to associate a Client session with an ID Token, and to mitigate replay

attacks. The value is passed through unmodified from the Authentication Request to the

ID Token. Sufficient entropy MUST be present in the nonce values used to prevent

attackers from guessing values.

6.2.2. Tokens

• id_token which is a security token (in form of a json web token [JWT]) contains claims

about the authentication of an End-User by an Authorisation Server when using a

Client. The JWT comes in 3 parts separated by ".“ E.g.,

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJub25jZSI6Im5vbmNlXzAucHBzdHR1aGFwNWV6aDBrOSIsInN1YiI6IjMyMzljNmQxNmYzYjAxM2FmYTZkMTFkZjc1OTIyYWY0IiwiYW1yIjoiU01TX1VSTCIsImF1dGhfdGltZSI6MTQ0NjY0MDgyOSwiYWNyIjoiMiIsImF6cCI6IjBjOWRmMjE5IiwiaWF0IjoxNDQ2NjQwODI5LCJleHAiOjE0NDY2NDQ0MjksImF1ZCI6WyIwYzlkZjIxOSJdLCJpc3MiOiJodHRwOi8vb3BlcmF0b3JfYS5zYW5kYm94Lm1vYmlsZWNvbm5lY3QuaW8vb2lkYy9hY2Nlc3N0b2tlbiJ9.VuJFR71XqEGZmC1bnrn9iWUReYm0iJAji1oWailXqjk


• The first part (highlighted in yellow) is the header. It usually contains information

on how the id_token is signed.

• The second part (highlighted in blue), is the token payload. This contains all the

claims that are being passed over by the operator.

• The third part (highlighted in green) is the signature hash. Using information

obtained from the header, it can be know which hashing algorithm to use. If the

hash result of the first and the second parts matches the third part, you will

know that this id_token has not been tampered with and can be trusted. If they

don´t match, there is a chance that the id_token is corrupted or has been

tampered at some point and should not be trusted.

Validations on claims present in id_token (received in token api response):

• nonce: The nonce value present in decrypted id_token MUST be same as the

nonce used in the Authorisation request. The nonce parameter value needs to

include per-session state and be unguessable to attackers. One method to

achieve this for Web Server Clients is to store a cryptographically random value

as an HttpOnly session cookie and use a cryptographic hash of the value as

the nonce parameter. In that case, the nonce in the returned ID Token is

compared to the hash of the session cookie to detect ID Token replay by third

parties. A related method applicable to JavaScript Clients is to store the

cryptographically random value in HTML5 local storage and use a cryptographic

hash of this value.

• exp: Expiration time on or after which the ID Token MUST NOT be accepted for

processing.

• aud/iss: The Client MUST validate that the aud (audience) Claim contains

its client_id value registered at the Issuer identified by the iss (issuer) Claim as

an audience. The ID Token MUST be rejected if the ID Token does not list the

Client as a valid audience, or if it contains additional audiences not trusted by

the Client.

• iat: The iat Claim can be used to reject tokens that were issued too far away

from the current time, limiting the amount of time that nonces need to be stored

to prevent attacks.

• sub: Due to the possibility of token substitution attacks, the UserInfo Response

is not guaranteed to be about the End-User identified by the sub (subject)

element of the ID Token. The sub Claim in the UserInfo Response MUST be

verified to exactly match the sub Claim in the ID Token; if they do not match, the

UserInfo Response values MUST NOT be used.

• sub/iss: The sub (subject) and iss (issuer) Claims, used together, are the only

Claims that an RP can rely upon as a stable identifier for the End-User, since

the sub Claim MUST be locally unique and never reassigned within the Issuer

for a particular End-User. Therefore, the only guaranteed unique identifier for a

given End-User is the combination of the iss Claim and the sub Claim.


• Access Tokens are credentials used to access Protected Resources, Access Tokens

represent an End-User's authorisation and MUST NOT be exposed to unauthorised

parties.

• Token Substitution is a class of attacks in which a malicious user swaps various tokens,

including swapping an Authorisation Code for a legitimate user with another token that

the attacker has. One means of accomplishing this is for the attacker to copy a token

out one session and use it in an HTTP message for a different session, which is easy to

do when the token is available to the browser; this is known as the "cut and paste"

attack.

• In OpenID Connect, this is mitigated through mechanisms provided through the

ID Token. The ID Token is a signed security token that provides Claims such

as iss (issuer), sub (subject), aud(audience), azp (authorised

party), at_hash (access token hash), and c_hash (code hash). Using the ID

Token, the Client is capable of detecting the Token Substitution Attack.

6.2.3. TLS

• Communication with the Discovery/Token/UserInfo End-Points MUST use TLS. If

header enrichment is not used, Authorisation call should be invoked using TLS.

• Applications should not by-pass SSL validator. This can create security issues if

someone tries to proxy the request to a self-signed proxy server.

• Always use HTTPS for the redirect uri.

6.2.4. Generic

• The Authorisation Code flow is suitable for Clients that can securely maintain a Client

Secret between themselves and the Authorisation Server.

• Confidential information such as client credentials should not be logged.

• user information/ tokens/ authorisation codes should not be stored longer than needed,

should be disposed of when the user logs out or otherwise are not needed, and should

not be logged (except in an obscured way).

• Developers should protect their own applications e.g. using the various sets of OWASP

guidelines as a minimum.

• If developing client, applications, use code obfuscation to make it more difficult for a

hacker to create a malicious version of the app.

• It is recommended to make discovery and token api calls from server to keep the client

secret safe.

• It is recommended not to use incremental “unique_ID” for your own database. As

potentially hacker can just guess other IDs through the sequence

• Check the acr claim in the ID Token to confirm if the acr used by the Authentication

process is same as the one passed in the acr_values request parameter. If the acr

claim is different [e.g. LoA 3 was requested in acr_values and the acr claim indicates

LoA 2 – then take appropriate action in the implementation logic]


6.2.5. Pop-Up Blocker

Mobile Connect recommends developers do everything they can to avoid pop-up blockers.

Pop-up blockers do not block if the action of a button, or link is a direct window.open() and

users will not need to disable pop-up blockers in their browsers

That means by way of example: <a href=“/gf?profileSetup4=1&regId=0target=“changeMealItem"

onclick=“window.open('',‘changeMealItem','scrollbars=yes,resizable=yes,toolbar=no,location=no,width=570,height=5

10')">

<img src="/gf/change.gif" width="50" height="20" border="0"></a>

* If window.open() is called in a success callback, or from a timer function for example, the

browser is not opening a window as a result of a user action, but as a result of some

programmatic activity - that’s when browsers block pop-ups

E.g., if you are using ajax to invoke APIs from web client, then set attribute ‘async’ to ‘false’ as

illustrated below:

$.ajax({

url : url,

type: 'GET',

success : xxxxxxx,

error : xxxxxxx,

async: false

})

Setting async to false will not let the flow break between when user clicks the login-button

(when discovery API gets invoked) and when authorize API is hit programmatically basis

discovery response.

6.2.6. Webview for native apps OAuth2 authorisation is based on JavaScript technology. Developers building native apps can process callbacks with webviews. Webviews do not have to fill the entire screen – they can be simple 1 x 1 pixel views, where implementation is transparent to the user.

6.2.7. Allow vertical scrolling for webview

For text fields (for entering msisdn), allow vertical scrolling in webview so that keyboard does not hide text field.


About the GSMA

The GSMA represents the interests of mobile operators worldwide, uniting nearly 800 operators with more than 300 companies in the broader mobile ecosystem, including handset and device makers, software companies, equipment providers and internet companies, as well as organisations in adjacent industry sectors. The GSMA also produces industry-leading events such as Mobile World Congress, Mobile World Congress Shanghai, Mobile World Congress Americas and the Mobile 360 Series of conferences. For more information, please visit the GSMA corporate website at www.gsma.com. Follow the GSMA on Twitter: @GSMA.

customer verification (and number share ... share) technical implementation guide version 1.0 table...

Documents