Securely Consume APIs on Mobile Devices – Part 2

by May 4, 2018

Introducing OAuth 2.0

In Part 1 of this article, we briefly talked about OAuth 2.0 and its relationship with OpenID Connect 1.0. In part 2, we will provide more details about it and continue to increment the security of your app.

If you use the OAuth 2.0 Authorization Framework (RFC6749) to implement your client API, it can be a bit confusing. To make it easy to understand, we will describe it in a simple way, and highlight the choices that are appropriate for most implementations of mobile apps. If you want go deeper on OAuth 2.0, there are many books, blogs, and sites devoted to this subject.

Let’s begin with clarifying some of the OAuth 2.0 terminology. Client is used to refer different types of applications in the specification, for us in this article it is a mobile app. A Resource Owner is the user. A Resource Server is a backend (API server) interacting with the app through API calls. An Authorization Server, if present, will authenticate user and/or client credentials and authorize limited access to an API server. An User Agent is the user’s browser, used for redirect-based flows where the user must authenticate and optionally provide consent to share their resources.

The first step to use OAuth in your application is register the application with a service (Facebook, GitHub, Google, etc.). This is usually done through a registration form in the service’s website, where you will provide some information such as application name, website, redirect URI, etc. The Redirect URI is important because it is where the service will redirect the user after the authorization (the part of your application that will handle authorization codes or access tokens). The service will only redirect users to a registered and protected URI, which helps prevent some attacks.

After your application is registered, the service will issue Client Credentials in the form of a client identifier and a client secret. The Client ID is a public string used by the service API to identify the application, and is also used to build authorization URLs that are presented to users. The Client Secret is used to confirm the identity of the application to the service API when the application requests to access an user account, and must be kept private between the application and the API.

Grant Types

With the Client ID, the next and most important step is define how the client will receive an access token. The method used to retrieve this token is called a grant type. The specification defines four grant types and also an extensibility mechanism for defining additional types. Deciding which grant type to implement depends on the type of client the end user will be using, and the experience you want for your users.

The Authorization Code is the most common OAuth 2.0 grant type. It is considered the most secure and is commonly used when the application resides on a server, where source code is not exposed, and Client Secret confidentiality can be maintained. This is also a redirection-based flow, which will be familiar if you’ve ever signed into an app using your Facebook or Google account. In this flow, the client will redirect the user to the authorization server which will display an interface to authenticate the user, then prompt the user to authorize or deny the application access to their account. If the user authorizes the application, the server redirects the user-agent to the application redirect URI, which was specified during the client registration, along with an authorization code. Lastly, the client requests an access token from the server, by passing the authorization code.

Password Credentials is officially named as Resource Owner Password Credentials grant type. Most of the use cases for this flow are mobile or desktop apps. This flow does not require a client secret, once those apps cannot maintain the confidentiality of it (the source code can be exposed). This grant type should be restricted to applications owned by the service itself. For example, the native Facebook app. In this flow, the user gives their credentials (username and password) directly to the app, the application will then request an access token from the authorization server. If the user credentials check out, the authorization server returns an access token to the application.

The Client Credentials is the simplest of all of the grant types and is frequently used for machine-to-machine authentication where the user permission to access data is not required. For example, a client making requests to an API that do not require user’s permission. In this flow, the application requests an access token by sending its credentials (client ID and client secret) to the authorization server. If the application credentials check out, the authorization server returns an access token to the application.

Implicit grant type is similar to the Authorization Code, but instead of the authorization server returning an authorization code, which is exchanged for an access token, the authorization server returns an access token. It is intended to be used for user-agent-based clients (e.g. single page web apps) that cannot keep a client secret because all of the application code and storage is easily accessible. In this flow, the user is asked to authorize the application, then the authorization server passes the access token back to the user-agent, which passes it to the application.

Choosing a Grant Type

Ok, now you have a general idea about each grant type. Which one should you choose for your app? The best practices says if the client is a native app that you trust enough to handle the end user credentials you should implement the Password grant. For example, Facebook app is owned and developed by Facebook so therefore they implicitly trust it. If it is a third-party native app, you should use the Authorization Code grant (via the native browser or use SFSafariViewController).

To exemplify what we learned so far, let’s assume you are building a “Catalog of Products” app to consume APIs hosted by your company. You also probably want to allow the company’s users to authenticate themselves against your Identity Provider. In this scenario, the natural option is to use the Password grant, once you trust your own app to handle user credentials. In the following diagram you will see a summary of the steps required to implement the password grant type. Let’s assume that you have already registered the client app to obtain a Client ID from your API server.

1. The user launches the mobile app and is prompted to enter username/email and a password to identify themselves as an authorized user.

2. The app sends a POST request over TLS to the Authorization Server with the type of flow, client ID and user’s credentials.

3. If validation is successful, the app will receive a 200 OK response with the access token that expires after a certain amount of time (and optional a refresh token). Here is a sample of the returned JSON structure:

4. The app stores the access token on the mobile device somewhere (you know exactly where, because we talked about that in the part 1 of this article).

5. Like an API key, you can now include the access_token in the authorization header of your requests to access to protected resources.

6. Once the access token expires and no longer works, you re-prompt the user for their username/email and password.

An important advantage of using OAuth 2.0 to secure APIs is that it does not require you to store API keys in an unsafe environment. Instead, it will generate access tokens that can be stored in an untrusted environment temporarily. If attackers somehow manage to obtain your temporary access token, they can potentially invoke malicious operations, such as deleting data. However, OAuth provides several improvements over API keys. Additionally, access tokens can be tied to particular scopes, which restrict the types of operations and data the application can access. Also, combined with refresh tokens, access tokens will expire, so the negative effects could have a limited impact.

Ok, you now have an idea about what is OAuth and could see some details about how to implement the Password flow, one of the most used grant types. Let’s continue by expanding on another way to enhance security for your app.

Introducing JWT

JSON Web Token (JWT) is an open standard (RFC7519) that defines a JSON object as a safe way to represent a set of information between two parties. It looks like a longer randomly-generated string; the size depends on how much data you store within them. This string has generally three parts: a header, a payload, and a signature.

Sample of Decoded JWT

The header is the part that identifies which algorithm is used to generate the signature. The payload contains the data stored. The signature is calculated by base64 encoding the header and payload. The result is three Base64 strings separated by dots that can be easily passed in HTTP requests.

Sample of Encoded JWT

In our example, we did only put two claims into the payload, the “name” of the user and “role”. You can put as many claims as you want. Also, there are different standard claims for the JWT payload, “exp” for example is used for the expiration time, but they are optional. In short, JWTs are more convenient than traditional access tokens, and have many more benefits, including:

  • Holds JSON data
  • Can reduce the number of API calls to your service while still not compromising security by allowing users to validate their API credentials locally
  • Can be signed so you can be sure the senders are who they say they are
  • Also, as the signature is calculated using the header and the payload, you can verify if the token was not tampered with.

The most common scenario for using JWT is for Authentication. So wow your “Catalog of Products” app could take advantage of JWT You could change the server configuration to return a JWT with a set of claims instead a regular access token. So when the user successfully logs in using their credentials, a JSON Web Token will be returned. Then the app will give to it the same treatment, securely storing tokens locally and sending within each request in the authorization header. Additionally to the security advantages previously mentioned, using JWT, your API service also avoids multiple queries to the databases (once the data required to determine the identity and scope of access are in the token).

You should now have a good understanding why is it useful to use JWT as the OAuth access token. But keep in mind that you should restrict the usage to data that you are ok with being publicly exposed. It is normally used to store user ID and permissions.

Proof Key for Code Exchange

Proof Key for Code Exchange by OAuth Public Clients‘ (RFC7636) is a specification designed to address some of the security issues that exist when using OAuth 2.0 Authorization Code flow on public clients (JavaScript and native apps).
In the section describing the OAuth 2.0 grant types, we only went in details on the Password grant flow. The main difference between Password and Authorization Code grants instead of getting the user credentials and sending them to the server to obtain the access token, the client will redirect the users to authenticate themselves on the authorization server. Then the server will return the authorization code representing the authorization delegation performed by the user. On public clients, this code is all the application needs to obtain the access token allowing access to the User’s resources.

Where is the security issue? If attackers creates a native application that registers the same redirect URI used by your app, they can obtain the authorization code, because the server will sent it to any installed app with the same URL scheme. Unfortunately, there is no central entity controlling these scheme registrations, so an application can hijack the message from the browser to the client app. Having obtained the authorization code, the malicious app has all the information required to retrieve an access token and access the User’s resources.

To address this vulnerability, the PKCE specification introduces additional parameters to certain messages of the flow. When the client app is redirected to the authorization server page in the browser, it generates a random secret, stores it and uses its hash value on the new code_challenge authorization request parameter. The server stores away this hash value and associates it with code before returning it back to the app. When the app then exchanges the code for the access token, it will include the code_verifier parameter with the secret on that call. The server computes the hash of the code_verifier value and compares it with the original code_challenge associated with the code. If it is missing or does not match, the authorization server will not return the access token.

This ensures that only the entity that started the flow can end the flow and obtain the access token. Even if a malicious app is able to obtain a code, without the corresponding code_verifier it will be unable to obtain an access token, making the knowledge of the code insufficient to use it.

So, if you plan to use the Authorization Code flow in your app, make sure to use PCKE (if supported by your Authorization server) because it provides an important security enhancement..

Which of the presented security mechanisms should I use in my app?

As you can see, these security options are not mutually exclusive. In fact, it is possible an API could use all of these at the same time. Or, each could be used independently of the others. You can rely on API keys if you expect to build a internal app that do not need to access more than another application data. You can use OAuth with Authorization Code flow if you want users to easily provide authorization to apps without needing to use their credentials in the app. You can use OAuth with Password flow to allow your employees to identify themselves using their Intranet credentials to access protected corporation systems. There are many others scenarios, but no matter which scenario you need to cover, the application developer is responsible to handle some important implementation considerations regarding security. As mentioned in the beginning, this is just an introduction about some of the security mechanisms available to secure the consume of APIs on mobile devices. To summarize, there is a lot to learn. There are entire books on OAuth 2.0 security framework with details of authenticating multiple types of applications in various scenarios. Plus, we did not cover other security concepts like PKI and SSO. Therefore there is a significant time investment.

Ok, so what if you are daunted by all of these tasks you just read about because you know it will take several months to implement. Is there anything simpler? Yes there is.

CA Mobile API Gateway SDK

You can save a lot of time on developing your app using the Mobile SDK for CA Mobile API Gateway to access any protected API. App developers can rely on our Mobile SDK to provide security using OAuth, OpenID Connect, PCKE, JWT, Social Login, SSO, Public key Infrastructure (PKI), MutualSSL, Dynamic Client Registration, and much more. Using a token-based system with individually issued tokens for users, apps and devices provides the most flexibility for API access policies. It is an open source solution designed to help you develop cross-platform mobile applications, desktop applications, or web applications, along with many services to help you rapidly develop mobile and IoT apps.

Our CA Mobile API Gateway (MAG) includes an authorization server implementation, and as such, can generate and validate access tokens. Developers begin by registering their apps with MAG. Registered apps can request access tokens through any of the four grant type interactions. MAG provides a multi-faceted OAuthV2 policy that implements the details of each grant type, making it relatively easy to set up OAuth on MAG. For example, you can configure a policy that receives a request for an access token, evaluates all required credentials, and returns an access token if the credentials are valid.

Because everything is secured through the MAG, mobile developers can take advantage of best-in-class security without the hassle of setting up security policies. Plus, we provide a set of application services for apps spanning user and group management, Pub/Sub, storage and messaging services—all of which are available as SDK functionality for iOS, Android and Cordova platforms.

User & Group Management

One of the basic capabilities that apps need to deal with is user management—in many ways considered the basic building block for any enterprise app. CA Mobile API Gateway provides open APIs and SDKs, which feature retrieval and management of users via System for Cross-Domain Identity Management 2.0 APIs and native mobile SDKs; out-of-the-box integration with identity providers that support LDAP; and OAuth protected endpoints.

There is also the the capability to create and manage groups through SDKs. This means that an app can engage with its own group or other existing groups. The APIs on the backend follow the SCIM specification, which allow ease integration and interoperability. However, key to this feature is the ability to create new groups based on application-determined criteria such as location, proximity to other objects or Internet Protocol (IP) address domain.


The Pub/Sub pattern in CA Mobile API Gateway is built on MQ Telemetry Transport (MQTT) support. This is a huge add-on to the APIM solution in many ways. First, it allows for a messaging consumption paradigm where an app does not need to poll for data but can be notified whenever new data is available. This scales much better than the traditional request-response paradigm when the system has a high number of entities that need to consume the data. Second, pub-sub is integral to any IoT deployment where data and events will need to be propagated to other systems in near-real time. The heterogeneousness of these systems calls for a loose coupling, which is one of main benefits of pub-sub because the publisher is ignorant to who and how data is consumed. Now, from a system operator perspective, the latter is still important and needs a way to easily control who can publish and subscribe to particular topics.

User-to-User Messaging

App developers always strive to make applications more collaborative, including through social features. But in an enterprise-type app, you would often want to be able to contact other colleagues via a quick note or a call. The user-to-user messaging component in CA Mobile API Gateway allows an app developer to easily build messaging into apps with a few lines of code. The app developer can do either direct user-to-user or user-to-group messaging. In the latter, all members of the group will receive the message. While there are some messaging platforms, only a few provide the simplicity that CA Mobile App Services does, and even fewer provide the advanced security layer with auto-encryption of payload so that only the recipient can decrypt the messages.


The ability to store data in a secure manner is fundamental to any mobile app. CA Mobile API Gateway offers a locally encrypted data storage service for data at rest. Depending on the app developer’s preferences, secure private cloud storage can be used for off-device storage. Storage services features include easy-to-use local and cloud data store for developers via standard-based APIs and native mobile SDKs, as well as user, group and app-level data access permissions.


Our Mobile SDK provide these advantages and give the developer the flexibility to tweak the code for their own purpose. By using open and well-documented APIs, the developer can easily integrate with other systems as needed. By leveraging open standards like MQTT 3.1.1, SCIM 2.0, OAuth 2.0, OpenID Connect 1.0 and PKI, developers can easily implement security and integrate with other systems.