Secure Digital

A new service that lets you login to websites and apps on any device without having to remember
usernames or passwords.

You are safely identified through your mobile phone number ( Mascom,Orange, Be Mobile)
networks currently available.

Reason for the use of this new technology, its simple and safe in terms of logging in. Take for
instance the internet consists of websites and on these websites user names and passwords are
required for every website you visit to remain a loyal customer and be part of the customer chain,
this can be a frustrating remembering all those usernames and passwords. Not anymore the
introduction of this new technology has created a gateway to alleviate the frustration all in the
palm of your hand .

The new tech maintains your consent on personal information being kept confidential to you as
the user and nit to third parties.

HOW IT WORKS

Verifies your identity through your personal hand held device, that is your mobile phone number,
improving safer logins .

FAQ

What is an API?

“Application Programming Interface”. This allows a third party application to use a common set of
services (such as Mobile Connect) via a defined interface. In the case of Mobile Connect the API
can be called via an “Internet” connection so that Mobile Connect can be used in any application/
service that is internet enabled e.g. a website or application.

What is a REST API?

REST (Representational State Transfer) is a simple stateless architecture i.e. each operation is
entirely defined by the information sent to and received from the service. When an API uses this
architecture, it is known as a REST API.

How do I incorporate Mobile Connect in my application?

Mobile Connect can be used from any application which is internet enabled. In practice the service
will require the user to have a web client that connects to the Mobile Connect service (actually a
system component called the Identity Gateway) for the step when the user is logging in with their
operator.

Developers are recommended to use the SDKs available from the developer portal – where
available for their application platform. If developing an application and there is no SDK available
the ‘REST’ versions of the Mobile Connect APIs can be used.
The developer portal details how the APIs work and should be used, and provide API references
also. It is also a good idea to look at the Mobile Connect test applications to see how these use the
APIs.

How should I associate a user’s Mobile Connect account with an existing account in my
application?

Once a user has used Mobile Connect to authorize access to your application, the mobile network
operator's Identity Gateway provides a Pseudo-anonymous Customer Reference (PCR) to the
application. PCR is a unique reference to an individual user of Mobile Connect which reveals no
personal information about the user. The PCR will be persistent for the same application and user
(or MSISDN) logging in to the application and so this can be used to recognize either a first time
user or a returning user.

In case there might already be a user account this can be paired by the application with the PCR
value so that the user can use Mobile Connect to log in to the application in the future.

How do I recognise Mobile Connect is being used for a new user of my application?

Once a user has used Mobile Connect to authorize access to your application, the mobile network
operator's Identity Gateway provides a Pseudo-anonymous Customer Reference (PCR) to the
application. PCR is a unique reference to an individual user of Mobile Connect which reveals no
personal information about the user. The PCR will be persistent for the same application and user
(or MSISDN) logging in to the application and so this can be used to recognize either a first time
user or a returning user.

In the case this is a new user of your application you will receive a new PCR and this shows you it’s
a new user. From this you can create the relevant user record/ state/ settings in your application.

How do I obtain API keys?

Simply create a account on this developer portal and then can create one or more applications.
Each application will get its own API keys. Once your application is ready to go live you can request
API access from each of the mobile network operators that have a user base you want your
application to access. This process is described in Request access to operator networks.

What data can I get from the Mobile Connect API?

The Mobile Connect service currently supports a simple authentication service – though there are
plans to expand these capabilities in the future.
At the completion of the authentication process the mobile network operator's Identity Gateway
provides a Pseudo-anonymous Customer Reference (PCR) – a unique reference to an individual
user of Mobile Connect which reveals no personal information about the user. This is then used as
the unique identifier for that user.

Some operators are already offering additional services and functionality such as “authorization”
and “user attributes”. Please contact each mobile network operator directly for more information.
Where possible, contact details are listed on the Mobile Connect Operators section of this portal.

Can Mobile Connect be used via Wi-Fi only device (i.e. a device with no SIM)

The Mobile Connect button can be used on any internet connected device. The Mobile Connect
service itself requires that your users authentication device must be a SIM based device. This is
because Mobile Connect account is linked to the SIM card and is provided and managed by the
your users operator.

Technical

I see mention of a Redirect URI – what is this for?

I am writing a mobile app – how should I define a Redirect URI?

How do I handle any service errors that are returned?

What happens if an operator doesn't support Mobile Connect?

What happens if a user accesses Mobile Connect but I've not signed an agreement with the
operator?

What happens if a user accesses Mobile Connect but they cannot use it for some reason?

What happens if the authentication request times out?

Does Mobile Connect work on all mobile devices?

Are there any limitations on browser versions?

How should I integrate Mobile Connect in my application?

Why does the sandbox only offers pretend operators and doesn't work with real operators?
Why does the sandbox only offers SMS authentication?

I see mention of a Redirect URI – what is this for?

This is part of the OpenID Connect authorization framework. This ensures authentication
responses only go to your application/ service. This should point to a secure server hosted on your
behalf – this should participate in the authorization process so that you can keep certain
information from the APIs confidential (API secret, access token, PCR).

I am writing a mobile app – how should I define a Redirect URI?

Security is best when the Redirect URL points to a secure server that receives the authorization/
authentication response. You are advised to deploy a hosted service which participates in the
authorization process and can keep certain details confidential to your application (API secret,
access token, PCR). Although you may see code examples elsewhere which rely on ‘custom
schemes’ e.g. calendar:// you are advised that your service should not use custom schemes (other
than https) as these may not be supported across all Operator's.

How do I handle any service errors that are returned?

You will see details of various error responses within the API specifications. The Error description
field in an authentication response is meant to detail a message for the user. Refer to the error
code information that details what these mean and how these error codes should be handled.

Note that error text may vary between Operator's – it is intended to be displayed to the user who
should be familiar with it.

What happens if an operator doesn't support Mobile Connect?

An error message will be returned to the application/ service to advise that Mobile Connect is not
available for the user’s network – this will happen at the discovery stage. Your service should
consider offering the user an alternate authentication method if available. Refer to documentation

What happens if a user accesses Mobile Connect but I've not signed an agreement with the
operator?

The user will be presented with an error response at discovery or when the request is submitted
for authorisation. Your service should consider offering the user an alternate authentication
method if available. Refer to documentation
What happens if a user accesses Mobile Connect but they cannot use it for some reason?

The user will be presented with an error response when the request is submitted for
authorisation. Your service should consider offering the user an alternate authentication method if
available. Refer to documentation

What happens if the authentication request times out?

Your application will receive an error response indicating that the user has not authenticated. You
should offer the user the ability to authenticate again with Mobile Connect or using an alternative
authentication method.

The time out might have occurred for various reasons e.g. they took a phone call, were out of
coverage for a while, or because the network is busy.

Does Mobile Connect work on all mobile devices?

There are certain device dependencies that may vary across mobile networks. In general operators
are working on making Mobile Connect available to their whole customer bases. It should be
possible to authenticate via all 3G/4G mobile devices but it may work differently across different
versions of devices.

Are there any limitations on browser versions?

This may vary across mobile networks - Mobile Connect may not be usable on some networks if
the user is accessing it from older, insecure browsers

How should I integrate Mobile Connect in my application?

Mobile Connect can be integrated into any ‘Internet Connected’ software environment. GSMA
currently offers SDKs for Android, iOS and HTML5 integration and plans to introduce a range of
server side SDKs for Java and PHP and others during 2016. See the SDK section in Documentation
for the latest information.
In general, developers are encouraged to make most API calls from a server environment as this
provides improved security and end user privacy. Some of the interactions in Mobile Connect must
however be invoked within the user’s browser and therefore even if developers have built a
typical client/server web application the GSMA SDKs will support certain API calls from the server
side and other API calls from the client side. The recommendation is:

Discovery API calls are best made from a server environment

When the discovery user interface is displayed, this must be opened in the client browser
(/webview)

The Mobile Connect authorization request must be opened in the client browser (/webview)

Mobile Connect token API (/userinfo API) should be made from the server environment

If the application platform is not supported by a GSMA SDK the API calls can instead be made
using HTTP based network API requests. Details on these network API requests are available in the
API section of the Developer Portal.

Why does the sandbox only offers 2 pretend operators and doesn't work with real operators?

The sandbox is a emulator for the APIs and has been designed to be simple and global. It purpose
is to to support the early stage of application development, which is why it offers only two
emulated "operator's" APIs. Once an application has been tested against the sandbox APIs it is
expected that the application will then require access to ‘real’ Mobile Connect services offered by
the Mobile Network Operators. In line with this defined purpose, the sandbox is also only able to
provide the simplest authorization method of SMS+URL.

Why does the sandbox only offers SMS authentication

SMS authentication is the authentication service that works universally across all devices and
services. Other authenticators require integrations with specific operators (USSD + SIM App),
operator linked downloads (SIM App) or integration with a specific smart app.

I don't get the authentication SMSs, what should I do?

If you are not able to receive an authentication SMS then please report the issue to the support
team. You can also use the passthrough numbers that allow authentication with user interaction.
You can find details on these here
SDKs

What is an SDK?

Why is there more than one SDK?

Which software environments does the SDK support today?

How are SDK tested?

Who provides support for the SDKs?

Why do you only recommend the HTML5 SDK for prototyping and non-commercial use?

What is an SDK?

The abbreviation is for “software development kit” ... it is a kit of parts to support software
/application developers in creating new applications for a particular environment or framework.

There are SDKs for software environments and frameworks e.g. Java, iOS, android. These SDKs are
big and contain all the tools a developer needs to create a new applications in these particular
environments.

There are also SDKs that support particular APIs e.g. Facebook Connect, Mobile Connect. These
SDKs have a set of tools aimed specifically at supporting developers wanting to use the API
services. These SDKs are a lot smaller than the full software environment SDKs but perform the
same function i.e. they make it quicker and easier for the software developer to integrate the APIs
in to their applications.

Why is there more than one SDK?

The GSMA Mobile Connect Platforms Team provide SDKs for the most popular software
development environments that they believe will be using the Mobile Connect APIs.

Which software environments does the SDK support today?

Server side
Java SE/EE

PHP

.NET

Client side

Android

iOS

HTML5 (demo purposes only)

How are SDK tested?

Once a new version of an SDK is ready, is it sent to an independent software test house to be fully
tested against the SDK requirement specification. Any bugs found are then fixed and it is re-tested.
An SDK is not releases to developers until it has passed all the tests.

Who provides support for the SDKs?

The GSMA Mobile Connect Platforms Team provides on-boarding support to developers and in
case there is an issue will normally get involved with problem identification. In case there is a
problem with the SDK it will be referred to the supplier for rectification. The GSMA Mobile
Connect Platforms Team also aims to help with related questions and maintaining the knowledge
base for the SDKs.

For all developer support issues related to SDKs including deployment of the SDKs on local servers
please contact: [email protected]

Why do you only recommend the HTML5 SDK for prototyping and non-commercial use?

HTML5 is not a strongly secure environment and given the promise of Mobile Connect to keep
user's personal data safe and private the HTML5 environment is not strong enough.

As such whilst the SDK has some use in developers understanding how to integrate Mobile
Connect, but we would recommend other SDKs are used in commercial applications.
There are no plans to upgrade the HTML5 SDK to support Mobile Connect Release 2 Authorization
and Identity services.

Why do I need API credentials?

The API credentials identify your application/ service so that the user knows who/what is initiating
Mobile Connect. These credentials are used by the operator to ensure they know which
application/ service is originating the request.

Operator Identity Gateways will use this knowledge of the application/ service initiating the
request to apply the relevant authenticator mechanism for a request, apply other operator
policies e.g. API throttling limitations, and to guard against spoof authentication requests.

How do I keep credentials secure in a mobile app?

The general advice is that, as far as possible, API requests should be made exclusively from a
server side environment – even if you have developed an Android or iOS application. You are
encouraged to use mechanisms such as the iCloud keychain, and use methods such as code
obfuscation to hide any API calls you make at a client environment.

Some API calls have to be placed from the client environment e.g. part of the discovery API
request and part of the Mobile Connect authorization API call, but any time an API call involves a
“secret” e.g. the second part of discovery or the Mobile Connect token API call you should make
this from the server.

As a related note you should make sure that any of your code (client/ server) which is making API
calls is using default SSL certificate checking. This will guard your applications/ users from
potential man in the middle attacks if they are using an insecure network e.g. a WiFi hotspot.

If I have a native app without a server how can I secure the API credentials?

Certain OS platforms will provide secure storage environments e.g. the Apple iOS keychain.

You should certainly make sure not to store keys/ secrets to any form of removable storage.
“Hide” keys’ secrets in your code by breaking into ‘fragments’ which are spread in various places
in your application and only combined when needed. And/ or use encryption and code
obfuscation technologies particularly for Android applications which can be reverse compiled.

How do I invoke Discovery so that requirements for GDPR within the EEA are fulfilled?

GDPR (General Data Protection Regulation) kicks-in if you (the Service Provider) use Mobile
Connect for an end user of your service which is a citizen of one of the EEA states or a subscriber of
a Mobile Network Operator within EEA. In that case, it needs to be ensured that the MSISDN,
which is regarded as “personal data”, is not transferred to a country outside the EEA and
processed there. In general this could happen as there a multiple data centres around the globe
which provide the Discovery service and some of them are located outside the EEA to serve
requests of these respective regions. To prevent from this, Discovery needs to be invoked with the
eu.discover.mobileconnect.io URL. This ensures that the Discovery invocation is always routed to a
data centre within the EU and processed there.

What is EEA with respect to GDPR

The EEA is the European Economic Area this is basically the European Union member states plus
Iceland, Lichtenstein and Norway.

Commercial

Is there any restriction on the types of services I can use Mobile Connect for?

Am I charged for Mobile Connect API services?

Is there a fair use/ reasonable use restriction?

How do I find out which operators are offering Mobile Connect?

How can I get in contact with the operators providing Mobile Connect?

Is there any restriction on the types of services I can use Mobile Connect for?
Mobile Connect is intended to be used for commercial services – however individual mobile
operators may have specific policies in place over the types of services that they will allow Mobile
Connect to be used with. You will need to consult the respective Terms & Conditions of each
mobile operator to see what services are allowed or disallowed and may need to contact a team
within the operator to discuss/ approve your application.

You should in general expect that Mobile Connect cannot be used for services which are
considered illegal or immoral or otherwise forbidden in the user’s home country.

Am I charged for Mobile Connect API services?

Mobile Connect is provided by a global network of Mobile Operators and is delivered via a
standardised technical interface. Each Operator has its own commercial proposition, pricing and
commercial terms for Mobile Connect. You’ll need to agree to the Mobile Operator’s Terms and
Conditions before you can access the service.

Some operators offer Mobile Connect Authenticate free of charge, subject to a fair usage policy,
via a standard set of Terms and conditions on this developer.mobileconnect.io portal. Registered
users can view and accept the Standard Terms and Conditions for these operators via the My
Operators page.

For information about the commercial terms for operators not offering the Standard Terms and
Conditions for Mobile Connect Authenticate, or other Mobile Connect products please contact the
operators directly. Commercial contact details can be found in each Operator profile available at
Operators page.

Is there a fair use/ reasonable use restriction?

Traffic levels for applications/ services will be monitored and may be subject to limitations to
avoid problems for users, other applications or service platforms. Operator's may also have their
own service limitations - please refer to the Operator’s specific terms & conditions.

How do I find out which operators are offering Mobile Connect?

A list of Operator's offering Mobile Connect with contact details can be found here.
How can I get in contact with the operators providing Mobile Connect?