GSMA_MM_API_Security_Design

Change Request Form
V2020.11 CR1001 Mobile Money APIs -

Security design and implementation
guidelines
Document Summary
Official Document Number,

V2020.11 Mobile Money APIs - Security design and implementation
Document Title and Version
guidelines v0.1 (Current)
Number
Official Document Type Non-binding Permanent Reference Document
Change Request Security

Non-confidential
Classification
Is this a new document or a Major
Major Update
or Minor Change?
Will this Change Request result in
Major Version
a Major or Minor version update?
This document is for Approval
Input Editor and Organisation Laura Dawson (GSMA)
Donna Mackay (GSMA), Ian Pannell (GSMA), Niko Alexiadis (GSMA), Ethan
Additional Contributors
Duffell (GSMA),
Issuing Group/Project DCMM-PLG
Approving Group/Project PSMC
Change Request Creation Date 16/08/2016
The Mobile Money environment is fragmented with each platform

vendor offering their own API. For this reason, the GSMA defined a
RESTful harmonized Mobile Money API to standardize the connection
What are the reasons for and
benefits of creating this new between API Clients (e.g. Merchant, Aggregators, Utility Companies)
document or Change Request? and the Mobile Money Platforms. This security design provides
guidelines on the security methods to be used and best practices for
the platform/gateway providers
© GSMA © 2016. The GSM Association (“Association”) makes no representation, warranty or undertaking (express or implied) with respect to
and does not accept any responsibility for, and 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. This document has been classified
according to the GSMA Document Confidentiality Policy. GSMA meetings are conducted in full compliance with the GSMA Antitrust Policy.
Page 2 of 49
GSM Association Non-confidential
Mobile Money APIs - Security design and implementation guidelines
Page 3 of 49
Table of Contents
1 Introduction 6
1.1 Scope 6
1.2 Conventions 7
1.3 Abbreviations 7
1.1 References 8
1.4 Objective 10
1.5 Actors 10
1.6 Common OAuth 2.0 Terms 11
1.6.1 Interfaces 12
1.7 Intended Audience 13
1.8 Document Structure 13
2 API Client Authentication – Security Design 14
2.1 Solution Overview 14
2.2 Security Principles 14
2.2.1 Confidentiality 14
2.2.2 Integrity/authenticity 15
2.2.3 Availability 15
2.2.4 Authentication/Authorisation 15
2.3 Security Models 16
2.3.1 API Client Authentication using Basic Authentication 16
2.3.2 API Client Authentication using Oauth 2.0 Client Credentials Grant Type 17
2.4 Common Security Mechanisms 19
2.4.1 Server-side TLS Authentication 19
2.4.2 API Client Basic Identity Check based on API Key 20
2.4.3 Basic Data Integrity and Authenticity Check 20
2.4.4 JOSE Standards for Message Validation and Encryption 20
2.4.5 Protection of Sensitive Request Parameters – Query/URI Path variables 21
2.5 Certificate/Key Management 22
2.5.1 Enrolment 22
2.5.2 Certificate Revocation Management 22
2.6 Algorithms Selection 22
2.6.1 TLS 22
2.6.2 JOSE 22
2.7 Summary of Security Guidelines 25
2.7.1 Comparison between basic Auth and Oauth 2.0 Client Credentials Flow 25
3 End User Authentication – Security Design 26
3.1 Solution Overview 26
3.1.1 Overview of OpenID Connect Protocol 27
3.2 Security Models 28
3.2.1 End User Authentication by API Gateway 28
3.2.2 Delegated End User Authorisation 34
3.2.3 End User Authentication Using Username and PIN 38
Page 4 of 49
4 API Best Practices 38

4.1 Auditing/Monitoring 39
4.1.1 Logging 39
4.1.2 Monitoring/Reporting 39
4.2 Communication 41
4.2.1 Transport 41
4.2.2 Data Encryption 41
4.2.3 Storage of Cryptographic Keys and Credentials 41
4.3 Identity Management 42
4.3.1 Authentication and Session Management 42
4.3.2 Authorisation 44
4.4 Validating RESTful services 44
4.4.1 Input Validation 44
4.4.2 Output encoding 45
4.4.3 Error Handling 45
Annex A REST Security Standard Overview 46
Annex B Document Management 48
B.1 Document History 48
B.2 Other Information 48
Page 5 of 49
1 Introduction
The Mobile Money environment is fragmented with each platform vendor offering their own
API. For this reason, the GSMA defined a RESTful harmonized Mobile Money API
(Application Programming Interface) to standardize the connection between API Clients (e.g.
Merchant, Aggregators, Utility Companies) and the Mobile Money Platforms.
Section 2 of this Security design document for the GSMA Mobile Money API details the
security methods to be implemented for the connection between the API client and the API
Gateway. This security design provides guidelines on the security methods to be used and
best practices for the platform/gateway providers.
Section 3 of this Security design document details the security methods to be implemented
for securely authenticating end user to the Mobile Money platform. It captures various
scenarios for authenticating end users using industry standard authentication and
authorization protocol – OAuth 2.0 [22] and OIDC [27] along with custom authentication
models to support existing username/MSISDN and PIN based credentials.
Objectives which are achieved by implementing the security mechanisms and best practices
are to ensure confidentiality, integrity and authentication on the interface between the API
Client and the API Gateway.
With this harmonized Mobile Money API the GSMA aims to provide easy and secure building
blocks and rapid partner on-boarding and interoperability between multiple Mobile Money
deployments/implementation. This security design describes the security mechanisms to be
applied to this API.
REST APIs like the GSMA Mobile Money API, expose resources that could be associated to
sensitive information about the user and their actions can be subject to malicious activities
by third parties. To secure the information, cryptography mechanisms at the network layer
can be used, however, it is also important to address the pillars of secure computing which
will be further defined in section 2.2.
1.1 Scope
Section 2 focusses on protecting the interface between the API Gateway and other API
Client systems which will always be backend systems. Examples of API Client applications
are the following:
 Merchants
 Merchant aggregators
 Utility companies (for bill payments)
 Other Mobile Money platforms
Section 3 focusses on authentication of the end user using different security models. The
proposed models in this document are:
1. End user authentication using 3 legged OAuth flow

2. End user (Debit party) authorisation by a 3rd party IDP (Delegated authorisation)
3. End user authentication based on username/MSISDN and PIN
Page 6 of 49
Section 4 focusses on best practices in API design.
Security Pillar Description

Confidentiality The ability to keep information private while in transit
Integrity The ability to prevent information from being changed undetectably while
in transit.
Authenticity The ability to verify that a message is originating from a specific source
and has not been altered.
Availability Information exchange through the API should always be available when
needed. This implies that systems, access channels, and authentication
mechanisms must all be working properly.
1.2 Conventions
The key words “must”, “must not”, “required”, “shall”, “shall not”, “should”, “should not”,
“recommended”, “may”, and “optional” in this document are to be interpreted as described in
RFC2119 [24].
1.3 Abbreviations
Abbreviation Description
AES Advanced Encryption Standard
API Application Programming Interface
BAM Business Activity Monitoring
CA Certificate Authority
CEK Content Encryption Key
Consent Agreement that SP can use the attributes they're requesting
Consent Device The device through which the user provides consent for the sharing or
validation of attributes
Consumption device The device through which the user is accessing and consuming mobile
money service
CRL Certificate Revocation List
DDoS Distributed Denial of Service
GSMA GSM Association
HTTP(S) HyperText Transfer Protocol (Secure)
Identity Token Provides a set of metadata regarding the Authentication to the SP. This
includes the PCR, authenticator used, Level of Assurance etc.
IDP Identify Provider
IETF Internet Engineering Task Force
IP Internet Protocol
JOSE Javascript Object Signing and Encryption
JWA JSON Web Algorithm
JWE JSON Web Encryption
JWK JSON Web Key
JWS JSON Web Signing
Page 7 of 49
Abbreviation Description
JWT JSON Web Token
KPI Key Performance Indicator
MAC Message Authentication Codes
MSISDN Mobile Station International Subscriber Directory Number
MITM Man-in-the-middle attack - is an attack where the attacker secretly relays
and possibly alters the communication between two parties who believe
they are directly communicating with each other
MLS Message-Level Security - focuses on ensuring the integrity and privacy of
individual messages, without regard for the network
MMP Mobile Money Platform
MNO Mobile Network Operator
OIDC OpenID Connect
OWASP Open Web Application Security Project
PII Personally Identifiable Information
PKI Public Key Infrastructure
REST Representational State Transfer
RFC Request For Comments
RSA Asymmetric Encryption algorithm named after inventors: Rivest, Shamir,
Adleman
RP Relying Party (The application/service that needs the authentication and
identity services). It can either be API Client or API Gateway.
Scope Pre-defined collection of attributes that are logical to group together either
for sharing or for simplifying policy management
SHA Secure Hash Algorithm
SIEM Security Information and Event Management
SLA Service Level Agreement
SSL Transport level security is based on Secure Sockets Layer (SSL) - The
SSL is the industry accepted standard protocol for secured encrypted
communications over TCP/IP
TLS Transport-Level Security - such as HTTP Basic/Digest and SSL, is the
usual "first line of defence", as securing the transport mechanism itself
XML Extensible Markup Language
UMA User Managed Access
USSD Unstructured Supplementary Service Data
VPN Virtual Private Network
1.1 References
Ref. Title Author Date

[1]
RFC7515 - JSON Web Signature (JWS) IETF 05-2015
[2]
RFC7516 - JSON Web Encryption (JWE) IETF 05-2015
[3]
RFC7517 - JSON Web Key (JWK) IETF 05-2015
Page 8 of 49

[4]
RFC7518 - JSON Web Algorithms (JWA) IETF 05-2015
[5]
RFC7519 - JSON Web Token (JWT) IETF 05-2015
[6]
RFC7520 - Examples of Protecting Content Using JSON IETF 05-2015
Object Signing and Encryption (JOSE)
[7]
RFC4648 - The Base16, Base32, and Base64 Data IETF 10-2006
Encodings
[8]
RFC5246 - The Transport Layer Security (TLS) Protocol IETF 08-2008
Version 1.2
[9]
REST Security Cheat Sheet OWASP 04-2015
https://www.owasp.org/index.php/REST_Security_Cheat_S
heet
[10] RESTful Service Best Practices, Recommendations for
Todd 04-2012
Creating Web Services Fredrich
http://www.restapitutorial.com/media/RESTful_Best_Practic
es-v1_0.pdf
[11]
NIST Special Publication 800-122 : Guide to Protecting the NIST 04-2010
Confidentiality of Personally Identifiable Information (PII)
[12]
ISO/IEC 27000:2014: Information technology -- Security ISO 2014
techniques -- Information security management systems --
Overview and vocabulary
[13]
ICT guidelines for TLS: Dutch 11-2014
https://www.ncsc.nl/actueel/whitepapers/ict- Ministry of
beveiligingsrichtlijnen-voor-transport-layer-security-tls.html safety and
Justice
[14]
PayPal security guidelines and best practices Paypal
https://developer.paypal.com/docs/classic/lifecycle/info-
security-guidelines/
[15]
JSON and XML Threat Protection Policies MuleSoft
https://docs.mulesoft.com/anypoint-platform-for-apis/json-
xml-threat-policy
[16]
JSON Threat Protection policy APIGEE
http://docs.apigee.com/api-services/reference/json-threat-
protection-policy
[17]
JSON Threat Protection SAP HANA
https://help.hana.ondemand.com/apim_od/frameset.htm?95
2cbd7d32c342788ba699227e734547.html
[18]
Quota policy Will Witman 08-2015
https://github.com/apigee-127/a127-
documentation/wiki/Quota-reference
[19]
Spike Arrest Quick Start Will Witman 03-2015
https://github.com/apigee-127/a127-
documentation/wiki/Spike-Arrest-Quick-Start
[20]
SANS Institute InfoSec Reading Room - Four Attacks on SANS
OAuth - How to Secure Your OAuth Implementation
https://www.sans.org/reading-
Page 9 of 49

room/whitepapers/application/attacks-oauth-secure-oauth-
implementation-33644
[21]
RFC7617 – Basic HTTP Authentication Scheme IETF 09-2015
[22]
RFC6749 - The OAuth 2.0 Authorization Framework IETF 10-2012
[23]
RFC6750 - The OAuth 2.0 Authorization Framework: IETF 10-2012
Bearer Token Usage
[24]
RFC2119 - Key words for use in RFCs to Indicate S. Bradner 03-1997
Requirement Levels
[25]
OWASP Top Ten Project - OWASP 06-2013
https://www.owasp.org/index.php/Top10#OWASP_Top_10
_for_2013
[26]
OWASP Cryptographic Storage Cheat Sheet - OWASP 08-2016
https://www.owasp.org/index.php/Cryptographic_Storage_C
heat_Sheet
[27]
OpenID Connect IETF 11-2014
“An interoperable authentication protocol based on the
OAuth 2.0 family of specifications” available at
http://openid.net/specs/openid-connect-core-1_0.html
https://openid.net/specs/openid-connect-basic-1_0.html
[28]
Trusted Computer System Evaluation Criteria NIST 12-1985
http://csrc.nist.gov/publications/history/dod85.pdf
1.4 Objective
This security design document for the GSMA Mobile Money API is to ensure that:
1. Applicable security measures and best practices are applied to the connection between
the API Client and the API Gateway.
2. Applicable security measures and best practices are applied to authenticating end user
to the Mobile Money platform.
1.5 Actors
Actor Description
API Client The backend system of the clients of the API. These will be systems from e.g.
Merchants, Aggregators, Utility Companies.
API Gateway The API Gateway is the entry point for API Clients to connect to the Mobile
Mobile Platform. This API Gateway is the layer of harmonization standardized
by the GSMA at this moment to provide a generic interface for API Clients
across different Mobile Money Platform vendors.
Relying Party A Relying Party can either be API Client and API Gateway and integrates with
3rd party IDP or OAuth 2.0 authorisation server for authenticating and
authorising end user. Some examples of 3rd party IDP are GSMA’s Mobile
Connect, Facebook Connect, Google IDP etc.,
End user User performing mobile money transactions on the consumption device and
who will be authenticated on the authentication device as per the proposed
security models in this document.
Page 10 of 49
Actor Description
OIDC compliant The entity providing the authentication and identity services for authenticating
Identity Provider end users, e.g. GSMA’s Mobile Connect, Facebook Connect, Google IDP
Consumption This is the device where the user is consuming the service from the SP. This
Device can be any Internet connected device, e.g. a mobile device, a laptop, table,
smart TV etc. The access network used by this device can be any as long as
it can initiate an HTTP(S) interaction.
Authentication This is the device where the end user is authenticating or providing
Device authorisation. This device is always a mobile device, connected to the mobile
network.
Consent Device The consent device is the logical device through which the end user provides
consent to the IDP system, e.g. providing consent to debit wallet account in
case of P2P transfer.
Authenticator Authenticators are the authentication mechanism used by 3rd party IDP to
authenticate the user. Some examples of authenticators are USSD
Authenticator, SIM Applet Authenticator, Smartphone App Authenticator
Threat Actor also called a malicious actor, is an entity that is partially or wholly responsible
for an incident that impacts or has the potential to impact an
organization’s security. Some examples can be malicious ecommerce
websites, smart meters etc,
1.6 Common OAuth 2.0 Terms
Actor Description
Resource owner An entity capable of granting access to a protected resource. When the
resource owner is a person, it is referred to as an end-user. API Client plays
this role in the case of GSMA Mobile Money API.
Resource The server hosting the protected resources, capable of accepting and
server responding to protected resource requests using OAuth access tokens. API
Gateway is a resource server responsible for OAuth token validation to
process API requests. API Gateway interacts with its authorisation server for
OAuth token validation.
Authorisation The authorisation server is implemented in compliance with the OAuth 2.0
server specification, and it is responsible for validating authorisation grants and
issuance of access tokens that give the client access to the protected
resources on the resource server. It should be possible to configure "token
endpoints" on API Gateway, in which case the API Gateway takes on the role
of authorisation server. Alternatively, the API Gateway can use a third party
OAuth 2.0 compliant authorisation server.
Client The client credentials grant type can be used as an authorisation grant when
Credentials the authorisation scope is limited to the protected resources under the control
grant type of the client. Client credentials are used as an authorisation grant typically
when the client is acting on its own behalf (the client is also the resource
owner), or is requesting access to protected resources based on an
authorisation previously arranged with the authorisation server. This is the
recommended grant type for authenticating API Client to API Gateway.
Authorization Considered the most secure grant type. Before the authorization server
code grant type issues an access token, the RP (Relying Party) must first receive an
authorization code from the resource server. In this flow, 3rd party app opens
a browser to the resource server’s login page. On successful log in, the app
will receive an authorization code that it can use to negotiate an access token
with the authorization server. This grant type is considered highly secure
because the client app never handles or sees the user's username or
Page 11 of 49
Actor Description
password for the resource server. This grant type flow is also called "three-
legged" OAuth. This is one of the recommended grant type for authenticating
end users to API Gateway.
Access token Access tokens are credentials used to access protected resources. An
access token is a string representing an authorisation issued to the client.
The string is usually opaque to the client. Tokens represent specific scopes
and durations of access, granted by the resource owner, and enforced by the
resource server and authorisation server.
Protected Data owned by the resource owner. In case of GSMA Mobile Money API, the
resource protected resources are identified by API resources URL.
Access token The access token endpoint allow the client to specify the scope of the access
scope request using the “scope” request parameter. In turn, the authorisation server
uses the “scope” response parameter to inform the client of the scope of the
access token issued. The value of the scope parameter is expressed as a list
of space-delimited, case-sensitive strings. The strings are defined by the
authorization server. This parameter can be used by API Gateway to control
the access to different resources. It should be possible to group the API set
into individual product set each identified by a “scope” value. The API
Gateway can decide to assign these scope values to specific API Clients
based on policy and licensing rules thereby enforcing authorisation of
endpoints.
1.6.1 Interfaces
Interface 1: The interface between the API Client and the API Gateway
This interface is the interface which is in scope in this security design document and for
which integrity and confidentiality are considered. It covers the transport layer security on
this interface as well as application level authentication and authorisation. The security
mechanisms that must be applied to this interface are described in chapter Error!
Reference source not found..
API Client MNO
1 2
Mobile Money
Application API API Gateway
Platform
4 3
End user
Figure 1: Solution overview including interfaces
Error! Reference source not found. provides an overview of the other interfaces in a
Mobile Money solution which are shortly described below but these are considered out of
scope.
Page 12 of 49
Interface 2: Connection from API Gateway to Mobile Money platform
This connection is the proprietary interface for the connection to the existing Mobile Money
platform. This connection depends on the vendor chosen for the Mobile Money platform.
Interface 3: Interface between the Mobile Money platform and end user
For authentication within some use-cases the Mobile Money platform might request the end
user to provide an authentication. This interface could be IP (Internet Protocol) based or be
using protocols for example USSD (Unstructured Supplementary Service Data).
Interface 4: Interface between the end user and the API Client
In some use-cases the end user will communicate to the API Client. This interface can be
digital but it can also be different in the case of smaller shops.
API Client MNO
1
Mobile Money
Application API API Gateway
Platform
4 3
End user
Figure 2: Alternative where the API Gateway is directly connected to the Mobile
Money Platform
Error! Reference source not found. provides an alternative overview for when the API
Gateway is integrated within the Mobile Money Platform. In this case interface 2 does not
exist.
1.7 Intended Audience

This document is targeted towards Mobile Money platform vendors and mobile network
operators to guide them in implementing, setting up, and/or deploying a Mobile Money
Platform compliant to the GSMA Harmonized Mobile Money API.
Mobile Money Platform vendors will need to adapt their interface to API Clients by
implementing the harmonized API and perform remapping of the data elements between the
API Gateway and their Mobile Money Platform.
Page 13 of 49
1.8 Document Structure

This document acts as a single reference for the security design and implementation
guidelines of GSMA Mobile Money API. The document is structured as follows:
Chapter Description
Number
Chapter Error! Describes the security principles, tiered security model and common
Reference security mechanisms should be implemented and used on the GSMA
source not Mobile Money API to ensure these security principles can be achieved. A
found. summary section provides summary for recommended security option.
Chapter 3 Describes various security models for authenticating and identifying end
users
Chapter 4 Describes common best practices that must applied during the
development phase
2 API Client Authentication – Security Design
2.1 Solution Overview

The API Gateway is responsible for confidentiality and integrity/authenticity on interface 1
(API Client to API Gateway), see Error! Reference source not found., and API level
authentication of the API Client. The Mobile Money Platform is responsible for end user
authorisation - whether this entity is allowed to access, create or modify the information, e.g.
Transaction, Quotation.
Principles Responsible component

Confidentiality and integrity/authenticity of the messages API Client - API Gateway
exchanges on interface 1: API Client – API Gateway
API Client authentication API Gateway
Server Authentication API Client
Table 1: Responsibilities of components
Authorisation of the end user is delegated to the Mobile Money Platform by the API Gateway
by forwarding the end user identity.
Both confidentiality and integrity are not possible to the Mobile Money Platform as the
gateway needs to be able to read the data to perform the mapping of the data elements to
the format used by the Mobile Money Platform which depends on choices made by the
vendor that delivered the platform. During this mapping it would be possible to change the
data. Therefore, the API Gateway and mapping functionality should be performed in a
trusted system [28].
2.2 Security Principles

This section describes the definitions for the security concepts.
Page 14 of 49
2.2.1 Confidentiality
In information security, confidentiality "is the property, that information is not made available
or disclosed to unauthorized individuals, entities, or processes” [12]. This means protecting
data from unintended recipients, both at rest and in transit. Error! Reference source not
found. (MLS) below presents a comparison between Transport-Level security and Message-
Level security.
Transport-Level Security Message-Level Security1

Relies on the underlying transport No dependency on the underlying transport
Point-to-point End-to-end
Partial encryption not supported Partial encryption supported
High performance Relatively less performance
Table 2: Transport-Level Security vs. Message-Level Security
The use of TLS and MLS is complementary and the combination of both will enhance the
overall end to end security between the API Client and the API Gateway. Any
communication between the API Client and the API Gateway must always be protected by
the use of TLS. JOSE (Javascript Object Signing and Encryption) standards must be utilised
for achieving MLS of individual messages. Please see section Error! Reference source not
found. to understand JOSE concepts.
2.2.2 Integrity/authenticity
In information security, integrity is about “to protect the accuracy and completeness of
information’’. You can detect any unauthorized modifications of the message exchanged by
some parties involved in the communication. The security techniques that you can apply are
similar to those for the confidentiality property.
TLS is the chosen approach because it detects data modification. It sends a message-
authentication code in each message, which can be verified by the receiving party to ensure
that data has not been modified while in transit. For message authenticity the payload of the
message will be signed at the application level.
2.2.3 Availability
Availability “is a property or characteristic. Something is available if it is accessible and
usable when an authorized entity demands access”. High availability systems aim to remain
available at all times, preventing service disruptions due to power outages, hardware
failures, and system upgrades but also malicious attacks. On a public API, these attacks can
vary from an attacker planting malware in the system to a highly organized distributed denial
of service (DDoS) attack. DDoS attacks are hard to eliminate fully, but with a careful design
their impact can be minimized.
1 With only application level security HTTP header information might be readable by eavesdroppers.
Page 15 of 49
In most cases, DDoS attacks must be detected at the network perimeter level, however
vulnerabilities in the application code can be exploited.
2.2.4 Authentication/Authorisation
Authentication can be performed at two levels:
1. End user level authentication, also referred to as entity authentication, confirming the
identity of the user
2. Application, confirmation that the connecting client application is trusted.
Each Mobile Money Platform will have its own mechanisms for authentication and the API is
designed in a way that it is agnostic to the authentication method used by the Mobile Money
Platform. By doing so the API can be used with different authentication methods described in
this document in section 2.3 as well as existing methods already implemented within the
existing Mobile Money Platforms.
2.3 Security Models

The GSMA Mobile Money API will follow a tiered security model approach to become viable
for different API Clients and Mobile Money platform providers. The tiered approach will allow
the clients and platform providers to decide the best security model based on their expertise,
convenience and regulatory requirements. The different tiered models are:
1. API Client Authentication using HTTP Basic Authentication method over (Secure
Sockets Layer) SSL/TLS connection
2. API Client Authentication and Authorisation using OAuth 2.0 Client Credentials Grant
type over SSL/TLS connection
The next subsections describe the details about these security models.
2.3.1 API Client Authentication using Basic Authentication

This is the minimum level of security mechanisms to be supported by Mobile Money platform
provider implementing GSMA Mobile Money API. It consists of authenticating the API client
using the standard HTTP Basic Authentication method over secure SSL/TLS connection -
RFC7617 [21]. This option provided the least security and as such should be used for
development purpose only.
Client credentials are pre-shared as per Mobile Money platform provider’s policy with API
Clients. Each Mobile Money API call needs to have HTTP Basic Authentication headers built
from the client username and password as the Base64 encoded string. The API Client can
follow the below process for generating the basic authorisation header:
1. Construct the user-pass by concatenating the user-id, a single colon

(":") character, and the password. For example: if the user name is
“Aladdin” and password is “open_sesame”. The concatenated string will
be “Aladdin:open_sesame”
2. Base 64 encode the concatenated string to get an encoded string. For
example: encString = Base64Encode(“Aladdin:open_sesame”)
3. Pass the encoded string in Authorisation header as follows:
Authorisation: Basic QWxhZGRpbjpvcGVuX3Nlc2FtZQ==
Page 16 of 49
The API Gateway will be responsible for basic identity checks of API Clients as described in
section 2.4.2.
2.3.2 API Client Authentication using Oauth 2.0 Client Credentials Grant
Type
The GSMA Mobile Money API will utilise OAuth 2.0 authorisation framework (RFC 6749 [22])
for API Client authentication and authorisation. OAuth 2.0 is a standard way of allowing a
third-party application (API Client) to obtain limited access to an HTTP service i.e., protected
resources. The generic OAuth 2.0 flow is as follows:
Page 17 of 49
Authorisation request
Resource
Authorisation grant Owner
Authorisation grant
Authorisation
Client
Access token Server
Access token
Resource
Protected resource Server
Figure 3: OAuth 2.0 standard flow
Issuance of Access Token using Oauth 2.0 Client Credentials Grant Type
The API Gateway will be responsible for exposing an additional token endpoint over
SSL/TLS connection as defined in OAuth 2.0 specifications (RFC 6749 [22]). The API Client
requests an access token using only its client credentials as per client credentials grant type
OAuth flow. These credentials are pre-shared as per Mobile Money platform provider’s
Page 18 of 49
policy with API Clients. The client credentials grant type must only be used by protected and
confidential clients. Some of the protections that can be applied by API Clients are:
1. The client credentials should never be stored in end user’s user agent ie., browser.
2. The client credentials must always be encrypted and stored in secured key store on the
server of API Client.
3. Any connectivity with API Gateway must always be established between API Client
server and API Gateway.
The client credentials flow is illustrated below:
1. Client Authentication
API Client API Gateway
2. Access token
Figure 4: OAuth 2.0 client credentials flow
1. The API Client requests the access token from the token endpoint passing base64
encoded client credentials in basic authorisation header.
2. The API Gateway will be responsible for performing basic identity checks of API Clients
as described in section 2.4.2. If valid, the API Gateway interacts with its authorisation
server to issue an access token response containing the access token, expiry time and
optional scope values.
For example, the API Client makes the following HTTP request to the API Gateway using
secure SSL/TLS:
POST /token HTTP/1.1

Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
X-API-Key: czZCaGRSa3F0MzpnWDFmQmF0M2JW88jw66
grant_type=client_credentials
On successful authentication of the API Client, the API Gateway responds with an access
token response. For example:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"example",
"expires_in":3600
}
Page 19 of 49
Usage of Access Token

The API Client will be responsible for passing the access token received in section 2.3.2.1 to
every API call as a bearer token in the “Authorization” request header field as per RFC 6750
[23]. The API Gateway will be responsible for validating the token with its authorisation
server, and if valid, check that the client is allowed to invoke the protected resource based
on the access token scope value. It should return appropriate HTTP response codes in case
of invalid access token (expired or revoked) or invalid scope.
For example:
GET /resource HTTP/1.1

Authorization: Bearer mF_9.B5f-4.1JqM
X-API-Key: czZCaGRSa3F0MzpnWDFmQmF0M2JW88jw66
2.4 Common Security Mechanisms

The common security mechanisms that can be applied to the above two security models are:
1. Server-side TLS authentication

2. API Client basic identity check
3. Basic data integrity and authenticity check
4. JOSE standards for message encryption and validation
 Message encryption/decryption using JWE (JSON Web Encryption)

 Message signature validation check using JWS (JSON Web Signing)
5. API Client certificate based authentication

6. Protection of sensitive request parameters – query parameters and path variables
The next subsections describe the details about these mechanisms. Some of these security
mechanism allows the API requests and responses to be signed both by the API Client and
API Gateway. The authentication and authenticity information is implemented using
Javascript Object Signing and Encryption (JOSE) technologies as described in section
Error! Reference source not found.. Each API request can optionally go through some of
these checks when it arrives at the API Gateway. If any of these checks fails, the request
must be rejected with an error code in the response.
2.4.1 Server-side TLS Authentication

Server-side TLS authentication will guarantee confidentiality and allow for detection of
modification of the message (integrity) on the transport level. Server-side authentication
takes place when the API Gateway provides its public certificate for authentication to the API
Client. The SSL authenticates both peers during the connection handshake. The API Client
will need to pin the server certificate to be able to perform authentication of the server.
2.4.2 API Client Basic Identity Check based on API Key

The API Client will have pre-shared keys with unique identifiers. The keys are shared as per
Mobile Money platform provider’s policy with API Clients. One of the ways of sharing the API
key will be through the API Gateway developer portal. Initial identity of the API Client is
confirmed by providing this identifier in a custom request header. If the combination of the
Page 20 of 49
API key and client credentials/OAuth access token is not correct, the request must be
rejected with an error code in the response. The custom request header used by the API
client to pass the key will be “X-API-Key”.
It should be possible to revoke this key to stop a rogue API Client from accessing the API
Gateway. The actual mechanics of revoking a rogue API Client is dependent on API
Gateway implementation. Some API Gateway implementation like Apigee Edge provides a
developer portal through which such actions can be carried out.
2.4.3 Basic Data Integrity and Authenticity Check

It is not mandatory for a Mobile Money platform provider to implement the JOSE technology
stack for achieving data integrity and authenticity. An alternate approach to achieve basic
data integrity, detection of timing issues and authenticity checks is by using the following
request headers. The API Client must calculate these values and set it in the corresponding
headers. These headers are optional and should only be used if JOSE is not used in a
specific implementation. The different request headers are listed in Error! Reference
source not found..
HTTP Header Name Description

X-Content-Hash Custom request header - SHA-256 hex digest of the request
content (encrypted or plain)
Content-Length Length of request content - Requests having too long or non-
matching length are rejected
Date The date and time that the message was sent in HTTP-date format
including the time zone. One of the policy can be to reject the
requests having time deviation of more than ‘x’ minutes. It is the
responsibility of API Gateway to normalize the time to server’s time
zone for calculation purpose.
Table 3: Request headers for basic data integrity and authenticity check
2.4.4 JOSE Standards for Message Validation and Encryption

JOSE is a set of IETF (Internet Engineering Task Force) standards to enable cryptographic
protection of JSON objects, but also others type of objects, in fact, JOSE provides a general
approach to signing and encryption of any content. However, it is deliberately built on JSON
and base64 encoding, RFC 4648 [7] , to be easily usable in web applications.
The standards related to JOSE are listed in Error! Reference source not found..
Standard Description How the standard is RFC

used on interface 1 Reference
JSON Web JSON objects with digital JWS is used to sign the RFC7515
Signature signatures or Message payload of the message [1]
(JWS) Authentication Codes (MAC) being transmitted
JSON Web Encrypted JSON objects JWE is used to encrypt the RFC7516
Encryption payload of the message [2]
(JWE)
JSON Web Public and private keys (or sets Is used to exchange the RFC7517
Keys (JWK) of keys) represented as JSON public key used to sign the [3]
objects message payload with JWS
Page 21 of 49
JSON Web Authorizing a party to interact JWA is used to specify which RFC7518
Algorithms with a system in a prescribed algorithm is used for JWS [4]
(JWA) manner and JWE
JSON Web Is a compact, URL-safe means JWT is currently not used on RFC7519
Token (JWT) of representing claims to be interface 1 but can be used [5]
transferred between two parties to transport OAuth tokens in
Describes representation of future implementations. It is
claims encoded in JSON and possible to encrypt and sign
protected by JWS or JWE a JWT with JWE and JWS.
Table 4: Standards related to JOSE
JOSE has similar function to the XML Signature and XML Encryption standards, and
provides message-level protection of message confidentiality, authenticity and integrity.
Examples of protecting content using JSON Object Signing and Encryption can be found in
RFC7520 [6].
Message Encryption/Decryption using JWE

Asymmetric encryption is used to exchange a symmetric CEK (Content Encryption Key).
This CEK is encrypted with the public key of the receiving party to ensure that only the
receiving party will be able to decrypt the CEK. From this moment on both parties are in the
possession of the CEK. This Content Encryption Key can be used for the remainder of the
session using a symmetric algorithm.
Message Signature Validation using JWS

The payload of the messages sent to the GSMA Mobile Money API will need to be signed by
the private key belonging to the certificate of the API Client which must be enrolled within the
API Gateway of the Mobile Money platform. This ensures integrity of the messages
exchanged from the API Client to the API Gateway.
2.4.5 Protection of Sensitive Request Parameters – Query/URI Path variables

It is important to protect sensitive request parameters passed to a GET resource. These
parameters can be passed either as query parameters or URI path variables.
For example:
1. MSISDN/{value}
2. /accounts/{accountIdentifier1}@{value1}${accountIdentifier2}@{value2}${accountIden
tifier3}@{value3}
The following strategy should be used by API Client to protect these parameters:
1. API Client encrypts URI path variables using the pre-shared API key with pre-shared
symmetric encryption algorithm. The API key and algorithm details are pre-shared
during the provisioning of API Client.
2. Use a request object in a POST that can be either signed (JWS) or encrypted (JWE)
using standard JOSE framework described in section Error! Reference source not
found..
Page 22 of 49
2.5 Certificate/Key Management
2.5.1 Enrolment
To enrol API Clients within the API Gateway of the GSMA Mobile Money API the public
certificate belonging to the API Client should be enrolled within the API Gateway. This
should be performed by creating a trust store of API Client certificates that are issued by a
public CA (Certificate Authority).
IUt is important that the certificate is linked to the API Client and known within the API
Gateway.
2.5.2 Certificate Revocation Management

The certificates of API clients enrolled in the API Gateway should be maintained and if the
API Client is no longer trusted than the certificate should be blacklisted inside the API
Gateway by temporarirly removing the public certificate from the trust store.
When setting up a connection the certificate from the API Client should always be validated,
including validation of the chain, and may not be present on the CRL.
The API Client should validate the certificate of the API Gateway, including validation of the
chain, and may not be present on the CRL.
2.6 Algorithms Selection
2.6.1 TLS
For the Server side TLS at transport level, as described previously, the minimum TLS
version to use is TLS 1.2 and only a subset of the following cipher suites [13] shall be
supported from server side:
 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
 TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
 TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
 TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
 TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
 TLS_RSA_WITH_AES_256_GCM_SHA384
 TLS_RSA_WITH_AES_128_GCM_SHA256
A specific cipher suite shall not be hard coded in the configuration. Instead, the protocol
must be allowed to negotiate the highest version automatically [14].
2.6.2 JOSE
For JOSE the algorithms are defined in JWA as specified in RFC 7518 [4].
JWE
For JWE one of the following algorithms must be applied to exchange the CEK:
Page 23 of 49
 Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static, as described in

section 4.6 from [4]:
o ECDH-ES+A256KW: ECDH-ES using Concat KDF and CEK wrapped with

"A256KW"
"A192KW"
"A128KW"
 Key Encryption with AES GCM, as described in section 4.7 from [4]:
o A256GCMKW: Key wrapping with AES GCM using 256-bit key

 Key Encryption with RSAES OAEP, as described in section 4.3 from [4]:
o RSA-OAEP-256: RSAES OAEP using SHA-256 and MGF1 with SHA-256

o RSA-OAEP: RSAES OAEP using default parameters
 Key Encryption with RSAES-PKCS1-v1_5, as described in section 4.2 from [4]:
o RSA1_5: RSAES-PKCS1-v1_5
For the CEK one of the following algorithms must be applied:
 AES_CBC_HMAC_SHA2 Algorithms, as described in section 5.2 from [4]:
o A256CBC-HS512: AES_256_CBC_HMAC_SHA_512
 Content Encryption with AES GCM, as described in section 5.3 from [4]:
o A256GCM: AES GCM using 256-bit key

JWS
For JWE one of the following algorithms must be applied:
 Digital Signature with ECDSA, as described in section 3.4 from [4]:
o ES512: ECDSA using P-512 and SHA-512

 Digital Signature with RSASSA-PSS , as described in section 3.5 from [4]:
o PS512: RSASSA-PSS using SHA-512 and MGF1 with SHA-512

Page 24 of 49
 Digital Signature with RSASSA-PKCS1-v1_5, as described in section 3.3 from [4]:
o RS512: RSASSA-PKCS1-v1_5 using SHA-512

Page 25 of 49
2.7 Summary of Security Guidelines

It is possible to combine security modelS described in section 2.3 and security mechanisms
described in section 2.4 to come up with preferred security options. Some of the
recommended options are:
Development level: Testing of API connections; Low-value connections (e.g. single

customer smartphone)
Standard level: Low-value connections; and Medium value (e.g. single business / merchant
/ agent)
Enhanced level: Medium and High value (e.g. mobile money operator / IMT provider /
bank). This option provides the same level of protection that can be achieved by using a
dedicated VPN (Virtual Private Network) tunnel between API Client and API Gateway. It is
recommended to use this option as an alternative to a more expensive VPN tunnel option.
Security Security Description Server API Basic Data JOSE API Client
option method side Client Integrity - JWE certificate
TLS basic and & based
identity Authenticity JWS authentication
check Check
based on
API key
Development Basic API Client X X X
Level Auth + Authentication
HTTPS
Standard OAuth2 + API Client X X X
Level HTTPS Authentication &
Authorisation with
protection from
message tamper
and MITM attack
Enhanced OAuth 2 + API Client X X X X
Level HTTPS Authentication &
Authorisation with
advanced message
level protection
(message signing
and encryption)
Table 5: Summary of Security Guidelines
Note; Mobile Money platform providers should implement ‘Development Level’

security options defined above as a bare minimum viable option. It should be
possible for the providers to select any combination of security methods and
mechanisms above the development level to meet the regional security
requirements.
2.7.1 Comparison between basic Auth and Oauth 2.0 Client Credentials Flow
The table below provides a comparison between basic authentication and OAuth 2.0 client
credentials flow:
Page 26 of 49
Basic authentication OAuth 2.0 client credentials flow

Requires passing of encoded API Client Encoded API Client credentials (client_id,
credentials (client_id, client_secret) in every API client_secret) are passed once in an
request in “Authorization” header. authentication API to get back an access token.
In a man-in-the-middle SSL exploit, the It is possible to revoke the access token in the
credentials of API Client are left wide open. It event of man-in-the-middle SSL exploit or if an
makes it extremely difficult to diagnose the API Client is generating excessive or illicit traffic.
attack vector that is compromising logins.
There is no token management capability. This Access token can be issued with well-defined
deficiency makes it nearly impossible to limit scopes that can allow access to protected
access to secured resources without potentially resources. It should be possible to package
having to disable the client’s credentials related APIs as products and assign a scope for
completely. each product.
Possible to mitigate the risk of replay attacks by
selecting appropriate values for time to live on
access tokens.
Easier to implement and no inherent Slightly complex to implement and ideally requires
requirement for a separate authorisation server a separate OAuth 2.0 compliant authorisation
to manage lifecycle of access tokens. server to manage lifecycle of access tokens.
The investment in OAuth 2.0 compliant
authorisation server can be reused in
implementing end user authentication framework.
Table 6: Comparison Between Basic Authentication And Oauth 2.0 Client Credentials
Flow
In summary, while the OAuth 2.0 “client credentials” grant type is a more complex interaction
than Basic authentication, the implementation of access tokens may be the better option.
Managing an API program without access tokens can provide you with less control, and
there is little chance of implementing an access token strategy with Basic authentication. By
forcing SSL usage, either option is secure, but OAuth 2.0 “client credentials” grant type
should give a better level of control.
3 End User Authentication – Security Design
3.1 Solution Overview

The previous section focussed on API Client authentication models and common security
mechanisms applicable for protecting API Client and API Gateway. The focus of this section
is to provide implementation guidelines on end user authentication using different security
models. Some of the scenarios where the security models can be applied are:
1. Authentication and identification of end user (debit party/credit party) to API

gateway/Mobile Money platform. For example: As part of initial login process, API
Gateway can authenticate the user using Authorisation Code flow2 and API Client in
turn retrieving the access token from API Gateway. The API Client can subsequently
pass the access token in API calls to API Gateway for validation purpose.
2 Also known as 3 legged OAuth flow
Page 27 of 49
2. Authorisation consent from a debit party/account holder for a financial transaction. For
example: In the case of send money, cash out, buy goods; either API Gateway/API
Client can authenticate the debit party using 3rd party OIDC (OpenID Connect)
compliant IDP and retrieve the consent proof (access token) and passing the access
token to API Gateway in the API call.
3. End user consent to share their MSISDN and in-turn identifying their wallet account.
For example: In case of an ecommerce checkout, the merchant server can authenticate
the user using a 3rd party IDP and acquire consent to share their MSISDN. The consent
proof (access token) can then be passed to API Gateway who can validate the token
and retrieve the MSISDN to identify the wallet account.
4. Third party developer has developed an app to enable customers to send money. It
should not be possible for customers to enter their credentials (MSISDN + PIN) into the
app and pass it in Mobile Money API. Instead, the API Gateway should prompt the user
to authenticate using Mobile Money platform credential mechanism (MSISDN + PIN)
and if successfully authenticated, the API Gateway issues an access token to the app.
The app can supply the access token in the Mobile Money API to the API Gateway.
The security design proposes the following security models for authenticating end users:
1. End user authentication by API Gateway using OAuth 2.0/OIDC Authorisation Code
Flow
2. Delegated end user (debit party) authorisation using 3rd party OIDC compliant IDP
3. End user authentication using username and PIN
3.1.1 Overview of OpenID Connect Protocol

It is recommended that any 3rd party IDP used by API Client for authorising users should be
OIDC compliant. Some of the popular OIDC compliant IDPs are GSMA’s Mobile Connect,
Facebook Connect and Google IDP etc.
OpenID Connect (OIDC) [27] is an identity layer on top of OAuth 2.0 [22] that provides an
authentication context for the end-user in the form of Who, When, How etc. in a JWT based
claims set [ID Token].
The key functionality provided are:
 Pseudonymous Identity (claims assertion) /Authentication of end-user [ID Token]

 JSON/REST-like API for authentication and basic profile sharing [UserInfo]
OpenID Connect provides an additional token [ID Token] along with the OAuth 2.0
access_token. The ID Token is represented as a JWT and contains a claim set related to the
authentication context of the subject. The JWT can be a plaintext JWT or cryptographically
protected JWT – represented as signed JWT using JWS [JSON Web Signature] or as
encrypted JWT using JWE [JSON Web Encryption].
The security design recommends use of the OIDC Authorisation Code flow for the following
reasons:
 Tokens not revealed to the User Agent

 RP must be authenticated
Page 28 of 49
o client_secret is used in Authorisation Code flow to retrieve access and ID

tokens
 Usage of refresh token possible
3.2 Security Models
3.2.1 End User Authentication by API Gateway

The GSMA Mobile Money API will utilise industry standard OAuth 2.0/OIDC authorisation
framework for end user authentication.
Note: The authorisation server can be embedded inside the API Gateway
depending on the implementation of API Gateway or it can be a separate
authorisation server hosted by a 3rd party. The authorisation server must be
either OIDC or OAuth 2.0 compliant.
It will utilise Authorisation Code flow/three legged OAuth flow for authenticating end users.
Please see section 1.6 for definition of Authorisation Code flow. This flow is considered to be
highly secure as Mobile Money credentials of end users are never requested directly by API
Client.
Some of the advantages of using OAuth 2.0/OIDC authorisation framework are:
1. Use of industry standard protocols for authenticating users thereby avoiding the build
of bespoke solutions.
2. Use of OIDC compliant IDP providers means support for a wide array of advanced
authentication mechanisms including PIN and Biometrics3.
3. Single integration model for API Clients to authenticate end users.
4. More secure as end user credentials are never captured in API Client assets4 directly.
5. The use of access tokens allows time bound/one time access, if required.
A high-level component view of various actors and flow of information is illustrated below:
3 Finger scan or Facial recognition or Iris scan

4 Website or apps
Page 29 of 49
10. Payment API + access token, ID T oken
Payment
API Mobile Money Platform
API Client Serv er

7. Redirect: AuthZ code «api gateway»
Mobile Money API
Payment API Gatew ay
OIDC
«user agent» POST : introspect
API
1. Authenticate Consumption access token
Dev ice
8.POST : access token request with 11. Validate access token
AuthZ code
9. access token + ID T oken
2. GET : AuthZ code OIDC/OAuth 2.0
«OIDC/OAuth ...
6. HT T P 302 Redirect: AuthZ code
Authorisation
serv er
User
4. Authenticate and provide «authenticator» 5. AuthN response

consent Authentication
Dev ice 3. Initiate AuthN request
Figure 5: End User Authentication By API Gateway
The process for authenticating end user and retrieving access tokens can be broken down
into following steps:
1. The end user initiates authentication request on the consumption device’s user agent.
2. The user agent sends an authorisation request to an authorisation server for
authenticating end user passing client_id, redirect_uri, state and other parameters in
the request. See section 3.2.1.1 for details.
3. An authorisation server initiates an end user authentication process as per Mobile
Money platform’s authentication mechanism. The authorisation server can authenticate
the end user by presenting an authentication page either in a consumption device or a
separate authentication device. The actual implementation is left to the Mobile Money
platform provider.
4. The user is prompted to provide credentials either in a consumption device or separate
authentication device.
5. The authentication device generates an authentication response and returns to the
authorisation server.
6. An authorisation server validates the authentication response and returns a temporary
authorisation code to the RP server indirectly as a redirect through the user agent. See
section 3.2.1.2 for details.
7. The RP server receives the authorisation code in the redirect URL. It extracts the
authorisation code from the redirect URL’s query parameter.
8. The RP server exchanges the authorisation code to retrieve the access token and
optional ID Token with authorisation server. The RP server will provide its client
credentials in the token API request to retrieve the tokens. See section 3.2.1.3 for more
details.
Page 30 of 49
Note: If the authorisation server is not OIDC compliant, then it will only return an
access token. The advantage of using an ID Token is to allow the RP to
retrieve additional identity claims like MSISDN etc.
9. An authorisation server validates the authorisation code and the clients credentials, it
generates a new access token and ID Token and returns to RP server.
10. The RP server passes the end user’s access token to the API Gateway in the API
requests as a custom header value. See section 3.2.1.4 for more details.
11. The API Gateway validates the access token with the authorisation server before
processing the API request.
Authorisation Request for Authenticating End User

The API Client’s user agent will send an authorization request to the authorisation server’s
‘authorisation endpoint’ as described in section 3.1.2 of OIDC [27], using HTTP GET or
POST.
Communication to the authorisation server endpoint MUST use SSL/TLS. The request
parameters are added using query string serialization. The prompt parameter in the request
must be “login”.
Sample Request:
POST /authorize HTTP/1.1
response_type=code&
client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fsummer-heart-0930.chufeiyun1688.workers.dev%3A443%2Fhttps%2Fclient.example.org%2Fcb
&scope=openid
&state=af0ifjsldkj
&nonce=n-0S6_WzA2Mj
&prompt=login
&login_hint=<MSISDN>
The authorisation server validates the authorisation request and returns a HTML payload for
authenticating the user. The actual authentication mechanism (MSISDN + PIN or Biometrics5
or something similar) is dependent on the downstream Mobile Money platform. It should also
be possible for the authorisation server to perform out of band authentication using separate
authenticators6. The authenticators can also act as consent device for displaying an
authentication prompt to the user. The actual implementation of an authentication
mechanism adopted by the authorisation server is out of scope of this document.
Authorisation response
An authorisation server will generate an authorization code after authenticating the end user.
It will return the authorization code using redirect to the RP server7 at the redirect_uri.

6 USSD authenticator, SIM Applet authenticator, Smartphone App Authenticator
7 API Client
Page 31 of 49
Sample Response:
HTTP/1.1 302 Found
Location:https://server.sp.com/authorized?Code=AsdsdsMKDsd&state=af0
ifjsldkj
Issuance of Tokens Using Authorisation Code Flow

The RP server8 makes a token request by presenting its authorisation code to the token
endpoint exposed by authorisation server. The grant type value must be
“authorization_code”, as described in section 4.1.3 of OAuth 2.0 [22].
The RP server sends the parameters to the token endpoint using the HTTP POST method
and the form serialization, as described in section 4.1.3 of OAuth 2.0 [22]. Communication to
the authorisation server endpoint MUST use SSL/TLS.
The Authorisation Code flow is illustrated below:
8 API Client
Page 32 of 49
Authorisation request
API Gateway
Authorisation grant
Authorisation grant
Authorisation
API Client
Access token Server
Access token
API Gateway
Protected resource
Figure 6: OAuth 2.0 Authorisation Code flow
1. The API Client requests the access token from the token endpoint of authorisation
server passing base64 encoded client credentials in basic authorisation header. The
request parameters includes grant type value, authorisation code received in section
3.2.1.2 and redirect URI value. These parameters are passed “x-www-form-
urlencoded” values.’
Page 33 of 49
2. The authorisation server validates client credentials of the RP server and if valid,
returns an access token response containing the access token, refresh token, expiry
time and optional ID Token.
Sample token request:

POST /token HTTP/1.1
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fsummer-heart-0930.chufeiyun1688.workers.dev%3A443%2Fhttps%2Fclient.example.org%2Fcb
Sample successful access token response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "SlAV32hkKG",
"token_type": "Bearer",
"refresh_token": "8xLOxBtZp8",
"expires_in": 3600,
"id_token":
"eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
Jp6IcmD3HP99Obi1PRs-cwh3LO-
p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
NqeGpe-
gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
}
Usage of Access Token

The API Client will be responsible for passing the user’s access token received in section
3.2.1.3 to every API call as a custom header value. The API Gateway will be responsible for
validating the token with its authorisation server, and if valid, allow the processing of the API
request. It should return the appropriate HTTP response codes in the case of invalid access
tokens (expired or revoked).
Page 34 of 49
For example:
GET /resource HTTP/1.1
Authorization: Bearer mF_9.B5f-4.1JqM
X-User-Bearer: czZCaGRSa3F0MzpnWDFmQmF0M2JW88jw66
3.2.2 Delegated End User Authorisation

There are scenarios that require debit party/account holder authentication to authorise a
payment transaction. For example: In the case of Send Money, Cash Out, Buy Goods etc., it
should be possible for the API Gateway to directly authenticate the debit party as described
in section 3.2.1 or allow the API Client to use a 3rd party OIDC compliant IDP to authenticate
the debit party and pass the access token as consent proof9 to the API Gateway in the API
request. This allows the API Gateway to validate the access token using token introspection
endpoint described in section 3.2.2.1. On successful validation, it should continue
processing the payment request. The focus of this section is delegated authorisation of debit
party/account holder using a 3rd party IDP.
Some of the advantages of delegated authorisation model are:
1. Use of industry standard protocols for authorising users thereby avoiding build of
bespoke solutions.
2. A single integration model to support multiple 3rd party IDP providers.
3. A user’s credentials are never passed in the API request thereby reducing risk and
fraud.
4. The use of access tokens allows time bound/one time access, if required.
5. Allows the API Gateway to verify the consent proof before proceeding with payment
transactions. The consent proof can also provide an audit trail as it contains exact
timestamps of providing consent and the mechanisms used for authenticating the user.
6. The consent proof provides non-repudiation of payment transactions.
7. Use of OIDC compliant IDP providers means support for a wide array of advanced
authentication mechanisms including PIN and Biometrics10.
8. Streamlined UX flow as the user is not required to authenticate separately with Mobile
Money platform, resulting in fewer steps to complete a payment transaction.
A high-level component view of various actors and flow of information is illustrated below:
9 access token
Page 35 of 49
1. Process payment
API Client Serv er 5. Process payment API + «api gateway»
access token Mobile Money API
Gatew ay
4. access 2. Initiate consent flow

token 6. Validate access token
OIDC API
3. Prompt the user to
authenticate and provide
consent for payment «3rd party»
User 3rd party IDP
transaction
Figure 7: Delegated user authorisation
1. A user initiates payment request (For ex: Send Money) with API Client.
2. The API Client uses a 3rd party IDP to authenticate the user and authorise the payment
transaction.
3. A 3rd party IDP prompts the user to authenticate and provide consent for the payment
transaction.
4. On successful user authentication and consent, a 3rd party IDP issues an access token
and ID Token to the API Client.
5. The API Client invokes the Mobile Money payment API passing the access token, ID
Token and introspection endpoint URL of 3rd party IDP.
6. The API Gateway validates the access token by invoking the introspection endpoint
URL. The introspection endpoint is a protected endpoint requiring the API Gateway to
pass its client credentials or bearer token when invoking this endpoint. 3rd party IDP
returns meta-information of the access token if the token is still valid 11. The API
Gateway can optionally introspect the ID Token to retrieve identity claims for example,
the MSISDN etc. It can also check the level of assurance12 achieved by 3rd party IDP
when authenticating the user before continuing with the payment processing flow with
downstream Mobile Money platform.
Note: A user should be registered with a 3rd party IDP in order to authenticate and
provide consent. Also, the API Gateway should have a client relationship
with a 3rd party IDP in order to invoke the introspection endpoint.
OAuth 2.0 Token Introspection

The token introspection endpoint allows a resource server13 to query OAuth 2.0 authorisation
server to determine the active state of an access token and to retrieve meta-information
about this token. This method can be used by the RP14 to convey information about the
authorisation context of the token from the authorisation server to the protected resource. In
the context of Mobile Money APIs as illustrated in section 3.2.2, the API Client can pass a
user’s access token and introspection endpoint URL of the 3rd party IDP server to the API
11 Not expired or revoked

12 acr_value attribute in ID Token
13 API Gateway
14 API Client
Page 36 of 49
Gateway allowing the gateway to validate the access token by invoking the introspection
endpoint URL and passing the access token as "application/x-www-form-urlencoded" data.
The successful response contains meta-information about the token.
The endpoint also requires some form of client authorization to access this endpoint. The
calling client15 can authenticate using the mechanisms described in section 2.3 of OAuth
2.0 [22] or by passing a separate OAuth2.0 access token as bearer token.
The following is a non-normative example request:
POST /introspect HTTP/1.1

Accept: application/json
Authorization: Bearer 23410913-abewfq.123483
token=mF_9.B5f-4.1JqM&token_type_hint=access_token
Introspection Request Attributes

The protected resource16 calls the introspection endpoint using an HTTP POST request with
parameters sent as "application/x-www-form-urlencoded" data
Parameter Required Description

category in
spec
token Mandatory The string value of the token.
 For access tokens, this is the

"access_token" value returned from the
token endpoint
 For refresh tokens, this is the
"refresh_token" value returned from the
token endpoint
token_type_hint Optional A hint about the type of the token submitted for
introspection. The possible values are:
 “access_token” if the token is of type

access token
 “refresh_token” if the token is of type
refresh token
Table 7: Introspection Request Attributes
15 API Gateway
16 API Gateway
Page 37 of 49
Introspection Response Attributes

The authorisation server responds with a JSON object in “application/json” format with the
following top-level members:
Attribute Required Description

category in spec
scope Optional A JSON string containing a space-separated list of

scopes associated with this token, in the format
described in Error! Reference source not found.
section 3.3
client_id Optional Client identifier for the RP that requested this token
username Optional User’s username
token_type Optional Type of token as defined in section 5.1 of OAuth 2.0

[22]
exp Optional The expiration time after which the access token
MUST NOT be accepted for processing. The format is
the number of seconds from 1970-01-01T0:0:0Z as
measured in UTC until the date/time specified.
iat Optional The time of issue of access token. The format is the
number of seconds from 1970-01-01T0:0:0Z as
measured in UTC until the date/time specified.
nbf Optional Timestamp indicating when the access token is not to

be used before. The format is the number of seconds
from 1970-01-01T0:0:0Z as measured in UTC until
the date/time specified.
sub Optional Subject identifier of the user (PCR)
aud Optional
The intended audience for the access token. It is an
array of case-sensitive strings. It MUST contain the
client_id of the RP/Client, and MAY contains
identifiers of other optional audiences.
If there is one audience, the aud value MAY be a
single case sensitive string OR an array of case
sensitive strings with only one element. An
implementation MUST support both scenarios.
iss Optional
Issuer Identifier. It is a case-sensitive HTTPS based
URL, with the host. It MAY contain the port and path
element (Optional) but no query parameters.
jti Optional
Access token string identifier
Table 8: Introspection response attributes
Page 38 of 49
3.2.3 End User Authentication Using Username and PIN

There is a legacy option in some of the existing Mobile Money platforms that allows the API
Client to capture the user’s credentials17 directly in their own assets18 and pass it to the
Mobile Money platform securely in the API payload. This is not a recommended option but is
still provided in this document to support existing implementation requiring minimum
changes.
Some of the drawbacks of this option are:
1. A user’s credentials are known to the API Client resulting in increased fraud due to the
possibility of altering the credentials.
2. The API Gateway and Mobile Money platform are unable to receive explicit consent
from the user thereby potentially increasing customer service complaints and financial
liability.
3. The API Client has to support multiple authentication models for different Mobile Money
platform providers.
Some of the recommendations to support this option are:
1. This option should only be used in scenarios where the user is directly controlled by
the Mobile Money Platform. For example: if the user is using Mobile Money platform’s
website or app directly and needs to authenticate.
2. A user’s MSISDN is passed in the API and should be encrypted as defined in section
6.
3. The PIN is encrypted at the source using a pre-shared API key and symmetric
encryption algorithm. The API key and algorithm details are shared during the
provisioning of the API Client.
4. The use of a custom header in the API request to pass an encrypted PIN.
4 API Best Practices

This chapter describes a collection of the common security practices that must be applied to
RESTful API and the API Gateway platform. For these common best practices, the following
references have been used as a reference:
 OWASP REST Security Cheat Sheet [9].

 OWASP Top Ten [25]
 RESTful Service Best Practices [10]
 OWASP Cryptographic Storage Cheat Sheet [26]
Each section contains a table with a set of best practices encoded in the following way:
{BP_Category_number]
17 MSISDN and PIN

18 Website or app
Page 39 of 49
4.1 Auditing/Monitoring
4.1.1 Logging
An important aspect of building RESTful services in a complex distributed application is to
address logging functions, especially for the purpose of debugging production issues and
investigating eventual points of failure. With good logging practices it is possible to detect
security issues.
Note: PII (Personally Identifiable Information) [11] data should be handled with
care avoiding the logging of these types of information.
Code Description
BP_LOG_1 A detailed consistent pattern should be applied to log messages across

service logs.
It is good practice for a logging pattern to at least include the following: date
and current time, logging level, the name of the thread, the simple logger name
and the detailed message.
BP_LOG_2 It is important to obfuscate sensitive data. It is important to mask or obfuscate
sensitive data in production logs to protect the risk of compromising
confidential and critical PII information.
BP_LOG_3 Identifying the caller or the initiator as part of logs.
BP_LOG_4 Do not log payloads by default.
BP_LOG_5 Any end user device used for Mobile Money transaction purpose should not
log sensitive data
Table 9: Best Practices Logging [BP_LOG]
4.1.2 Monitoring/Reporting
Monitoring activities is useful to protect your application from some misuses or external
attacks, but also to keep track, with the help of a BAM (Business Activity Monitoring), of KPIs
(Key Performance Indicator) to verify the adherence to the SLA agreed with the
stakeholders. The API Gateway can be used to monitor, throttle, and control access to the
API. The following can be done by a gateway or by the RESTful service:
 Monitor usage of the API and know what activity is good and what falls out of normal
usage patterns and implement appropriate reporting functionality
 Throttle API usage so that a malicious user cannot take down an API endpoint (DOS
attack) and have the ability to block a malicious IP address
Code Description
BP_MON_1 Use a monitoring system which can collect data to evaluate and to control
anomalous behavior, SLA and other statistics in the background.
It is a good practice to collect logs in a SIEM (Security Information and Event
Management), to discover some anomalous behavior and to detect some
attack patterns.
Page 40 of 49
Code Description
As an alternative to SIEM systems, it is advisable that logs be captured in a

centralised cloud based logging systems such as Loggly or Splunk cloud. It is
possible to drive real-time management diagnostic reports from these systems
to detect possible attack patterns
Collecting information in the right manner you could do this following activities:
 Identity, Audit and Authenticate Administrator and 3rd Party Access
 Control and Audit of all privileged users access
 Logging, monitoring user access
 Track and Monitor all Access
 Access Policy and reporting for Forensics and Investigations on
incidents
 Continuous Security Training Awareness with Recording Message
 Remote Access Session Monitoring and Authentication to Servers
 Logging Access, Alert on Unauthorized Access to Sensitive systems
 Ports and Services Monitoring, Logging All Server and user activity
 Incident Response with Session Replay on Event logs
BP_MON_2 Should implement payload protection policy.

Malicious injection in the payload are mitigated using techniques described in
chapter 3.4. But the attackers can, for example, use recursive techniques to
consume memory resources and other techniques that can compromise the
availability of the services. In the optic of a layered approach, the JSON threat
protection policies help to protect applications from such intrusions and
possible damages. Some example of policy to define are:
 Specifies the maximum number of elements allowed in an array.
 Specifies the maximum allowed containment depth, where the
containers are objects or arrays.
 Specifies the maximum number of entries allowed in an object
 Specifies the maximum string length allowed for a property name
within an object.
 Specifies the maximum length allowed for a string value.
Some useful reference are MuleSoft documentation [15], Apigee
documentation [16] and SAP HANA documentation [17].
BP_MON_3 Should implement protection policy to monitor the traffic against malicious
behavior (eg. DOS Attack and spike arrest).
 Quotas [18] and rate limits control the number of connections apps
can make to the backend via the API
 Spike arrest [19] capabilities protect against traffic spikes and denial-
of-service attacks
It is suggested to implement this feature using an API Gateway such as
Apigee, SAP API Management.
BP_MON_4 It is suggested to provide real-time monitoring capability o provide real-time
API health visibility.
Define and implement a list of KPI to monitor the API health status and
performance issue. Examples of KPI:
1. If you have more than 5 consecutive errors in the invocation of a
service raise an alert
2. If the call for a function takes more than a fixed period ex. 4 second.
Page 41 of 49
Table 10: Best Practices Monitoring [BP_MON]
4.2 Communication
4.2.1 Transport
Switching between HTTP and HTTPS introduces security weaknesses and the best practice
is to use TLS (HTTPS) by default for all the communication.
Code Description
BP_TCOM_1 Data in transit. The use of TLS should be mandated, particularly where
credentials, updates, deletions, and any value transactions are performed.
TLS version 1.2 [8] or newer must be utilized.
Table 11: Best Practices Transport Communication [BP_TCOM]
4.2.2 Data Encryption

Encryption should always be used to transfer data or sensitive information between the API
Client and the API Gateway.
Code Description
BP_ TCRY_1 PII and sensitive information in general should be encrypted (i.e. JSON
encryption [2]).
BP_ TCRY_2 Data at rest. It is necessary to prevent database bypass, which occurs when
an attacker threatens to gain access to sensitive data by targeting operating
system files and backup media. In this case he may avoid most database
authentication and auditing mechanisms. The most common way of
preventing this is by encrypting/salted hashing of the data-at-rest, i.e.
whenever it is committed to memory. This has the added benefit of also
protecting against improper decommission or theft of drives.
BP_ TCRY_3 Hash-based message authentication code (HMAC) should be used because
it's the most secure. (Use SHA-2 and up, do not use SHA & MD5 because of
vulnerabilities)
BP_TCRY_4 Any PII and sensitive request parameters passed as query parameters or path
variables must be encrypted. Please see section 2.4.5 for more details.
Table 12: Best Practices Transport Encryption [BP_TCRY]
4.2.3 Storage of Cryptographic Keys and Credentials

Some of the best practices for cryptographic design and storage of cryptographic keys are
summarized below:
Code Description
BP_CPRS_1 All protocols and algorithms for authentication and secure communication
should be well vetted by the cryptographic community. Deprecated protocols
and algorithms should not be used.
Page 42 of 49
Code Description
BP_CPRS_2 Ensure certificates are properly validated against the hostnames/users i.e.
whom they are meant for
BP_CPRS_3 Avoid using wildcard and self signed certificates unless there is a business
need for it
BP_CPRS_4 Maintain a cryptographic standard to ensure that the developer community
knows about the approved ciphersuits for network security protocols,
algorithms, permitted use, crypto periods and Key Management
BP_CPRS_5 Store a one-way and salted value of passwords - Use PBKDF2, bcrypt or
scrypt for password storage
BP_CPRS_6 Ensure that the cryptographic protection remains secure even if access
controls fail - This rule supports the principle of defense in depth. Access
controls (usernames, passwords, privileges, etc.) are one layer of protection.
Storage encryption should add an additional layer of protection that will
continue protecting the data even if an attacker subverts the database access
control layer
BP_CPRS_7 Ensure that any secret key is protected from unauthorized access
BP_CPRS_8 Store unencrypted keys away from the encrypted data
BP_CPRS_9 Protect keys in a key vault
BP_CPRS_10 Document concrete procedures for managing keys through the lifecycle
BP_CPRS_11 Protect PII and cardholder data
BP_CPRS_12 Render PAN (Primary Account Number), at minimum, unreadable anywhere
it is stored
BP_CPRS_13 Protect any keys used to secure cardholder data against disclosure and
misuse.
As the requirement name above indicates, we are required to securely store
the encryption keys themselves. This will mean implementing strong access
control, auditing and logging for your keys. The keys must be stored in a
location which is both secure and "away" from the encrypted data. This means
key data shouldn't be stored on web servers, database servers etc.
Access to the keys must be restricted to the smallest amount of users possible.
This group of users will ideally be users who are highly trusted and trained to
perform Key Custodian duties. There will obviously be a requirement for
system/service accounts to access the key data to perform
encryption/decryption of data.
The keys themselves shouldn't be stored in the clear but encrypted with a KEK
(Key Encrypting Key). The KEK must not be stored in the same location as
the encryption keys it is encrypting.
Table 13: Best Practices for storage of crypto keys [BP_CRPS]
4.3 Identity Management

The API Client and/or end user should be authenticated and authorized prior to completing
an access control decision. All access control decisions should be logged.
4.3.1 Authentication and Session Management

Authentication validates if you are the right person who can login to the software system.
Page 43 of 49
A RESTful API should be stateless. This means that the request authentication should not
depend on cookies or sessions.
Code Description
BP_IMAU_1 Session-based authentication must be used, either by establishing a session

token via a POST or by using an API key as a POST body argument or as a
cookie. Username, passwords, session tokens, and API keys must not appear
in the URL.
In case of user log out or session timeout activity, all session tokens (ex:
cookies) must be properly destroyed or made unusable, and that proper
controls are enforced at API Gateway to prevent reuse of session tokens. The
most important thing is for API Gateway to invalidate the session on the server
side. If such actions are not properly carried out, an attacker could replay these
session tokens in order to “resurrect” the session of a legitimate user and
impersonate him/her
BP_ IMAU_2 Protect session state.
Most Web services and APIs are designed to be stateless, with a state blob
being sent within a transaction. For a more secure design, consider using the
API key to maintain client state if the API is using a server-side cache. It's a
commonly used method in Web applications and provides additional security
by preventing anti-replay. Replay is where attackers cut and paste a blob to
become an authorized user. In order to be effective, include a time-limited
encryption key that is measured against the API key, date and time, and
incoming IP address
BP_ IMAU_3 All access control decisions shall be logged. The data retention policy must
adhere to the regional data archival regulatory requirements
BP_ IMAU_4 Protect against replay attacks.
A replay attack (also known as playback attack) is a form of network attack in
which a valid data transmission is maliciously or fraudulently repeated or
delayed. This is carried out either by the originator or by an adversary who
intercepts the data and retransmits it, possibly as part of a masquerade attack
by IP packet substitution (such as stream cipher attack).
There are a lot of countermeasures that you can take in place that use a time
limited encryption key, keyed against the session token or API key, date and
time, and incoming IP address. For example, some mechanisms are: session
tokens, one time passwords, MAC (Message Authentication Code) and time
stamping.
One common best practice mechanism, also used by OAuth is to have the
following combination:
 Nonce (number used once): It identifies each unique signed request,
and prevent requests from being used more than once. This nonce
value is included in the signature, so it cannot be changed by an
attacker
 Timestamp: We can add a timestamp value to each request .When a
request comes with an old timestamp, the request will be rejected.
From a security standpoint, the combination of the timestamp value and nonce
string provide a perpetual unique value that cannot be used by an attacker.
A useful reference is a SANS whitepaper: Four Attacks on OAuth - How to
Secure OAuth Implementation [20].
Table 14: Best Practices Identity Management Authentication [BP_IMAU]
Page 44 of 49
4.3.2 Authorisation
Authorisation validates if you are the right person to have access to the resources.
Code Description
BP_ IMAZ_1 Protect HTTP methods.

RESTful API often use GET (read), POST (create), PUT (replace/update) and
DELETE (to delete a record) methods. Not all of these are valid choices for
every single resource collection, user, or action. Make sure the incoming
HTTP method is valid for the session token/API key and associated resource
collection, action, and record.
BP_ IMAZ_2 Whitelist allowable methods.
For an entity the permitted operations should be defined. For example, a GET
request might read the entity while PUT would update an existing entity, POST
would create a new entity, and DELETE would delete an existing entity. It is
important for the service to properly restrict the allowable verbs such that only
the allowed verbs would work, while all others would return a proper response
code (for example, a 403 Forbidden).
BP_ IMAZ_3 Protect privileged actions and sensitive resource collections.
Not every user has a right to every web service. The session token or API key
should be sent along as a cookie or body parameter to ensure that privileged
collections or actions are properly protected from unauthorized use.
BP_ IMAZ_4 Protect against cross-site request forgery.
For resources exposed by RESTful web services, it's important to make sure
any PUT, POST, and DELETE request is protected from Cross Site Request
Forgery. Typically one would use a token-based approach.
Table 15: Best Practices Identity Management Authorisation [BP_IMAZ]
4.4 Validating RESTful services

When exposing RESTful service APIs, it is important to validate that the API behaves
correctly.
4.4.1 Input Validation
Code Description
BP_VALI_1 Use a secure parser for parsing the incoming messages.

BP_VALI_2 It is suggested the using of strongly type techniques for incoming data. Limit
and define the permitted values for an input parameter.
BP_VALI_3 Validate incoming content-types. The service should never assume the
Content-Type. When is not present in the header the server should reject the
content with a 406 Not Acceptable response.
BP_VALI_4 Validate response types. It is common for REST services to allow multiple
response type (in this case: application/json) and the client specifies the
preferred order of response types by the Accept header in the request. Do not
accept the request if the content type is not one of the allowable types. Reject
the request (ideally with a HTTP 406 Not Acceptable response)
Page 45 of 49
Code Description
BP_VALI_5 Use some framework (e.g. Jersey) that enable validation constrains to be
enforced automatically at request or response time. This kind of framework
provide automatic validation after unmarshaling.
BP_VALI_6 To prevent abuse, it is standard practice to add some sort of rate limiting to an
API. RFC 6585 introduced a HTTP status code 429 Too Many Requests to
accommodate this. However, it can be very useful to notify the consumer of
their limits before they actually hit it.
Table 16: Best Practices Input Validation [BP_VALI]
4.4.2 Output encoding
Code Description
BP_VALO_1 Send security headers. To make sure the content of a given resources is
interpreted correctly by the browser, the server should always send the
Content-Type header. The server should also send an X-Content-Type-
Options: nosniff to make sure the browser does not try to detect different
Content-Type than what is actually sent (can lead to XSS).
BP_VALO_2 JSON encoding. A key concerns with JSON is preventing arbitrary JavaScript
remote code execution within the browser. When inserting values into the
browser DOM, strongly consider using .value/.innerText/.textContent rather
than .innerHTML updates, as this protects against simple DOM XSS attacks.
BP_VALO_3 XML as JSON should never be built by string concatenation. It should always
be constructed using an appropriate serializer. This should be useful to be
sure that the content is parsable and does not contain injected elements.
Table 17: Best Practices Output Validation [BP_VALO]
4.4.3 Error Handling

You have to take in consideration that unhandled exceptions could reveal, to an attacker,
useful information about your API.
Code Description
BP_ERR_1 Utilize error codes. It is highly recommended that error codes are returned
whenever an error is encountered. A cautionary note here is to not provide too
much information (such that it would provide an adversary an advantage).
Successful error codes/messages are a balance between enough information
and security.
Table 18: Best Practices Error Handling [BP_ERR]
Page 46 of 49
Annex A REST Security Standard Overview

This section provides a brief overview of open security standards defined by the IETF, the
OpenID Foundation (OIDF), and other standards organizations for securing RESTful web
interfaces.
Standard Description
Transport Layer IETF standard for secure communications between a client and server,
Security (TLS) providing transport-layer encryption, integrity protection, and authentication
of the server using X.509 certificates (with optional client authentication)
OAuth 2.0 IETF standard for an authorisation framework whereby resource owners
can authorize delegated access by third-party clients to protected
resources; OAuth enables access delegation without sharing resource
owner credentials, with optional limits to the scope and duration of access
JavaScript Object Ecma19 standard text format for structured data interchange – not a security
Notation (JSON) standard per se, but a key component of several standards listed here
JSON Web IETF standard for attaching digital signatures or Message Authentication
Signature (JWS) Codes (MAC) to JSON objects
JSON Web IETF standard for encrypted JSON objects
Encryption (JWE)
JSON Web Keys IETF standard for representing public and private keys (or sets of keys) as
(JWK) JSON objects
JSON Web Specifies cryptographic algorithms to be used in the other JOSE standards
Algorithms (JWA)
JavaScript Object Collective name for the set of JSON-based cryptographic standards (JWS,
Signing and JWE, JWK, and JWA)
Encryption (JOSE)
JSON Web Token IETF standard for conveying a set of claims between two parties in a JSON
(JWT) object, with optional signature and encryption provided by the JOSE
standards
19ECMA was originally an acronym standing for the European Computer Manufacturers Association,
but the organization changed its name in 1994 to Ecma International to reflect its global focus
Page 47 of 49
Standard Description
OpenID Connect 1.0 OpenID Foundation standard for identity federation based on OAuth 2.0,
using JWT to convey signed and optionally encrypted identity claims
User-Managed Draft IETF standard for an OAuth 2.0-based access management protocol
Access (UMA) enabling resource owners to create access policies authorizing requesting
parties to access their resources through OAuth clients
Table 19: Open Security Standards for RESTful Interfaces
Error! Reference source not found. below illustrates the dependencies among the security
standards, with each standard depending on the others that lie directly beneath it.
Figure 8: REST Security Standard Dependencies
Page 48 of 49
Annex B Document Management
B.1 Document History

Version Date Brief Description of Change Approval Editor /
Authority Company
1.0 06.09.2016 New PRD – Major Change PSMC Laura Dawson,
GSMA
B.2 Other Information

Type Description
Document Owner GSMA Mobile Money Prgramme
Editor / Company GSMA
It is our intention to provide a quality product for your use. If you find any errors or omissions,
please contact us with your comments. You may notify us at prd@gsma.com
Your comments or suggestions & questions are always welcome.
Page 49 of 49

GSMA_MM_API_Security_Design

Uploaded by

GSMA_MM_API_Security_Design

Uploaded by

Change Request Form

V2020.11 CR1001 Mobile Money APIs -

Official Document Number,

Official Document Type Non-binding Permanent Reference Document

Change Request Security

This document is for Approval

Input Editor and Organisation Laura Dawson (GSMA)

Issuing Group/Project DCMM-PLG

Approving Group/Project PSMC

Change Request Creation Date 16/08/2016

The Mobile Money environment is fragmented with each platform

4 API Best Practices 38

1. End user authentication using 3 legged OAuth flow

Section 4 focusses on best practices in API design.

Security Pillar Description

Ref. Title Author Date

Ref. Title Author Date

Ref. Title Author Date

1.6 Common OAuth 2.0 Terms

API Client MNO

Figure 1: Solution overview including interfaces

Interface 2: Connection from API Gateway to Mobile Money platform

API Client MNO

1.7 Intended Audience

1.8 Document Structure

2 API Client Authentication – Security Design

2.1 Solution Overview

Principles Responsible component

2.2 Security Principles

Transport-Level Security Message-Level Security1

2.3 Security Models

2.3.1 API Client Authentication using Basic Authentication

1. Construct the user-pass by concatenating the user-id, a single colon

The client credentials flow is illustrated below:

Figure 4: OAuth 2.0 client credentials flow

POST /token HTTP/1.1

Usage of Access Token

GET /resource HTTP/1.1

2.4 Common Security Mechanisms

1. Server-side TLS authentication

 Message encryption/decryption using JWE (JSON Web Encryption)

5. API Client certificate based authentication

2.4.1 Server-side TLS Authentication

2.4.2 API Client Basic Identity Check based on API Key

2.4.3 Basic Data Integrity and Authenticity Check

HTTP Header Name Description

2.4.4 JOSE Standards for Message Validation and Encryption

Standard Description How the standard is RFC

Message Encryption/Decryption using JWE

Message Signature Validation using JWS

2.4.5 Protection of Sensitive Request Parameters – Query/URI Path variables

2.5 Certificate/Key Management

2.5.2 Certificate Revocation Management

2.6 Algorithms Selection

 Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static, as described in

o ECDH-ES+A256KW: ECDH-ES using Concat KDF and CEK wrapped with

o A256GCMKW: Key wrapping with AES GCM using 256-bit key

o RSA-OAEP-256: RSAES OAEP using SHA-256 and MGF1 with SHA-256

 Key Encryption with RSAES-PKCS1-v1_5, as described in section 4.2 from [4]:

For the CEK one of the following algorithms must be applied:

 AES_CBC_HMAC_SHA2 Algorithms, as described in section 5.2 from [4]:

o A256GCM: AES GCM using 256-bit key

 Digital Signature with ECDSA, as described in section 3.4 from [4]:

o ES512: ECDSA using P-512 and SHA-512

 Digital Signature with RSASSA-PSS , as described in section 3.5 from [4]:

o PS512: RSASSA-PSS using SHA-512 and MGF1 with SHA-512

o PS256: RSASSA-PSS using SHA-256 and MGF1 with SHA-256

 Digital Signature with RSASSA-PKCS1-v1_5, as described in section 3.3 from [4]:

o RS512: RSASSA-PKCS1-v1_5 using SHA-512

2.7 Summary of Security Guidelines

Development level: Testing of API connections; Low-value connections (e.g. single

Note; Mobile Money platform providers should implement ‘Development Level’

Basic authentication OAuth 2.0 client credentials flow

3 End User Authentication – Security Design

3.1 Solution Overview

1. Authentication and identification of end user (debit party/credit party) to API