SSO for Native Mobile Applications with WSO2 Identity Server

  • By Gayan Gunawardana
  • |
  • 18 Jul, 2014


The main objective of SSO is to provide a centralized, secure, convenient, and user-friendly method of authenticating a user one time within an environment. There are a bunch of technical and usability advantages that come with SSO. These include reducing phishing, needing to remember fewer passwords, assisting users with password recovery, making it easier to secure and speeding up development among others. Since mobile applications have to utilize small screens compared to other desktop applications, SSO functionality will be a more essential factor for mobile applications from a usability point of view. Imagine how difficult it is to type a username and password from a small touchpad keyboard every time you want to login to a new application.

SAML is the most widely used SSO standard for web applications [1]. The main reason for the success of SAML in web applications is the fact that web applications always expect web browsers as the client. Since native mobile applications do not run on web browsers, SAML does not work well in native mobile applications. This is where OAuth comes into the picture. However, there are a number of blogs and articles on the web that state open authorization (OAuth) is not a suitable protocol for SSP because the main purpose of OAuth is authorization not authentication. This will be discussed in detail later in this article.

For more information on SSO with WSO2 Identity Server watch our webinar on
or read our customer use case on how

What is OAuth?

OAuth is an open standard protocol for authorization. OAuth provides a facility for client applications which allows them to access secured resources on behalf of the resource owner. The main advantage of this is that OAuth2 specifies a process for resource owners to grant permission for third-party applications to access server resources without sharing their credentials. Access tokens are a key part of the OAuth process and are provided to third-party applications with the approval from the resource owner.

For example, suppose a third-party application needs to post on your Facebook wall on behalf of you. What would happen if you provide your username and password to that third party application? The third party application will be able do anything on your Facebook account. They can even change your existing password. Since this is impractical, you can give permission to that third party application to post on your Facebook wall without giving your username and password.

This is where the power of OAuth comes into play.

Is OAuth a good protocol for single sign-on?

The reason for this confusion is that single-sign on is somewhat relevant to the authentication process however OAuth primarily focuses on authorization. In order to grant a user permission to a resource, the user should be authenticated properly. So, in reality OAuth does authentication as a part of the authorization process. OAuth has a couple of handshake processes depending on the grant type but the ultimate goal is to provide an “access token” which can be used to access information from another application (For example, in order to access an OAuth secured API you need to pass a valid access token”). This access token is never intended to be given directly to a user or a particular application.

This is one of the main reasons why OAuth has become more popular in the mobile SSO world. If you are a mobile application developer and if you want to integrate Facebook, Twitter, Google or Linkedin login pages to your mobile application, you will be provided with a public SDK by each identity provider[2]. The important point is that all these identity providers utilize OAuth2 protocol underneath.

OAuth grant types

The authorization grant is defined by the resource owner according to an agreement with the authorization server. The client application will then have to follow a set of instructions or work flows given by the grant type to get an access token.

The OAuth 2.0 specification has four main types of authorization grants[3]. Each type has a different work flow and different security strengths. The authorization grant types are as follows;

  • Authorization Code
  • Implicit
  • Resource Owner Password Credentials
  • Client Credentials

Authorization Code

The authorization code grant type will be explained in detail because we will be using it in the implementation level.

Figure 1

Authorization code grant is a redirection-based flow. The client should be able to interact with the resource owner's user-agent (typically a web browser). The client application must be capable of receiving incoming requests via browser redirections from the authorization server.

The message flow is as follows. Resource owners invoke the client application and the client application use the resource owners user agent to send authorization requests with the client ID and callback url. If the user already has an authenticated session, the request will be redirected to the callback url with the authorization code without asking for the username and password. If not, the login page will be prompted to user, and after successful authentication the request will be redirected to the callback url with the authorization code. Once the authorization code is received, the client application can perform a token request to obtain the access token (client authentication happens through basic OAuth with client ID and client secret). The access token can be used to access OAuth secured APIs exposed by the service provider.


An implicit authorization grant is similar to an authorization code grant, except that there is no intermediate step where you need to get an authorization code. The access token is directly given when the user agent is redirected to the callback url. This means the access token is accessible to the user agent and the token is not stored securely on a web server. The client secret won’t be sent to the authorization server in this workflow, which means that there is no client authentication.

Resource Owner Password Credentials

This takes all parameters including client ID, client secret, username and password and makes a single call to the authorization server. The authorization server sends back the access token and refreshes the token as the response. There are no intermediate steps like in authorization grant type. The risk associated with resource owner password credentials is that the username and password are not directly given to the authorization server; they are given to the client application. The resource owner password credentials grant type is suitable for trusted client applications only.

Client Credentials

Client credentials can be used if a client application requests a resource from the resource server which is not specific to a particular user. It sends only the client ID and the client secret to the authorization server and gets an access token as a response. There are no user credential involvements or intermediate steps. For example, listing of venues from Foursquare which is not relevant to a particular user.

Proposed solution with WSO2 Identity Server

The proposed solution is to provide an SDK and IDP proxy application which will supply SSO functionality for native mobile applications provided that the SDK and IDP proxy application is capable of communicating the WSO2 Identity Server as the identity provider. WSO2 Identity Server is an enterprise-ready, fully-open source, lean, component-based solution for facilitating security and identity management of enterprise web applications, services, and APIs[4].

Implementation of REST security with OAuth 2.0 is one of the robust functionalities of the WSO2 Identity Server. Figure 2 displays the architecture of the proposed solution;

Figure 2

Step 1

Figure 3

The IDP proxy application sends the client ID, scope, callback url and grant type to the authorization server. If the user doesn’t already have an authenticated session, the login page will be prompted to the user. If the user already has an authenticated session they just have to be approved in order to obtain the authorization code.

Step 2
The IDP proxy application passes the authorization code to the client SDK and the client SDK invokes the token endpoint with the authorization code and scope. At this point, the client authentication happens through basic OAuth (client id:client secret).

Step 3
The client SDK receives the access token, refreshes token and id token as the response. The ID token contains the user profile including certain claims such as first name, last name and email address. If the client application wants to show the username or email after the login, id token would be useful. ID token comes as a base64 encoded string and once it is decoded the actual string can be seen. This contains a JSON object with user claims.

Step 4
The client application invokes OAuth secured REST APIs with the access token.

Step 5
The service provider contacts the identity provider and does the token validation. Then the token validation service provider grants access to invoke particular APIs. If you expose APIs via WSO2 API manager, the API manager itself does the token validation[5].

Why should you implement the authorization code grant type?

The following table shows the features offered by each grant type;

Authorization Code Implicit Client Credentials Resource owner password credentials
Client Authentication Yes No Yes Yes
Resource owner authentication Yes Yes No Yes
Provides refresh token Yes No No Yes
Maintain Resource owner authentication in a session Yes Yes No No

Let’s have a look at how those features are important for selecting a suitable grant type.

  • Client authentication verifies that requests are coming from a valid client application so that fake client applications cannot send requests to a token endpoint and obtain an access token.
  • Resource owner authentication is a key part of SSO functionality because grant types like client credentials don’t have any resource owner authentication and impossible to use at authentication scenarios at all.
  • Refresh token is also an important factor for SSO because if the grant type does not provide a refresh token the user won’t have a way to renew the access token unless they authenticate it again.
  • Maintaining an authenticated session between client user agent and authorization server is also a key factor because when a user wants to login to a new client application and the IDP proxy application already contains an authenticated session, the user can bypass the user login.

Background work before working with IDP SDK

Download and start WSO2 IS 4.6.0[6].

Figure 4

Initially you should create an OAuth application in the WSO2 Identity Server. Once logged in, go to Main > Manage > OAuth and click on ‘Register New Application’.

Figure 5

You can give any name for the callback URL and then change the constant file of the IDP proxy application. This need not to be a valid URL because mobile applications don't have URIs.

Repeat the above procedure to create three OAuth applications for two client applications and one IDP proxy application.

Get a git clone of android-idp-sdk[7].

“git clone [email protected]:GayanM/android-idp-sdk.git”

Go to the IDP-Proxy-App folder and open the android application from any Android IDE. There is a class named OauthCostants, you can enter the CLIENT_ID and CLIENT_SECRET values that were obtained for IDP proxy application during the previous step. Run this application as an Android project.

You will see the first screen as shown below. Go to the settings.

Figure 6

Set Host and Port as seen in the below diagram. Now you are ready to develop a client application with IDP SDK.

Figure 7

Develop client application with given SDK

If mobile application developers want to enable SSO in their mobile application they can integrate the given SDK. The SDK handles all server calls and always provides valid access tokens to client applications. This is somewhat similar to the usage of Facebook SDK. If you want to integrate Facebook login to your application you have to use SDK provided by Facebook.
Let’s see how we can integrate SDK with a mobile application.

Android IDP SDK is available in github[7]. You can clone and checkout the master branch. After cloning the SDK you can compile from the source ($ mvn clean install). Inside the target directory you will see the android-idp-sdk-1.0.jar file. Add it to the client application class path (in eclipse: right click on the project, go to Properties → Java Build Path → Libraries → Add External jars ). Change the OauthCostants CLIENT_ID and CLIENT_SECRET in the same manner as was done for the IDP proxy application.

As the first step, your login activity should extend IDPProxyActivity. Once this is done the init() method will be inherited to the login activity. In the login action you need to invoke the init() method by passing the client ID and client secret.

After initializing the identity proxy, the client application can get the access token from the callback method onTokenReceived(). To do that you need to pass an instance of type AccessTokenCallBack interface. In the given sample code MainActivity implements AccessTokenCallBack. Therefore the current instance can be used as the callback instance. That is why you can see “this” inside the init() method. You have flexibility to implement “AccessTokenCallBack” in your own class. You can then pass it during the initialization, inside the init(String clientID, String clientSecret, AccessTokenCallBack accessTokenCallBack) method.

public class MainActivity extends IDPProxyActivity implements AccessTokenCallBack {

    public boolean onMenuItemSelected(int featureId, MenuItem item) {
   		 case :
   	 return super.onMenuItemSelected(featureId, item);

    public void onTokenReceived() {
	Token token = IdentityProxy.getInstance().getToken();
	String accessToken = token.getAccessToken();

The complete sample can be found in the samples/azone application[7]. You can open the sample from your Android IDE and add android-idp-sdk-1.0.jar. to the application class path. Run the azone sample that will are displayed there.

(Click SIGN IN → Enter Username & Password → SIGN IN → Approve or Approve Always)

The phrase “WELCOME: SURESH” will appear at the top right corner. This means that the user Suresh has logged in to the azone application.

In order to demonstrate the SSO scenario open a second sample application ebuy (samples/ebuy[7]). You can follow the same steps you went through for the azone application. Run the ebuy application.

(Click on SIGN IN → Approve or Approve Always → signed on as SURESH)

As mentioned in the above workflow, the username and password page won’t be prompted to the user.

Possible security attacks

Phishing Attack

The SSO consumer application can redirect users to fake IDP proxy applications that can steal resource owners credentials. Fake IDP proxy applications load the legal OAuth login screen using a webview and then runs JavaScript on that webview object, attaching JavaScript event handlers to any [input] element on the page.

This attack can be avoided by using the simple image technique.

After downloading IDP proxy application from a trusted place you can set a profile image, when redirection happens the resource owner will see his profile image from the proxy application that verifies that the resource owner is giving his credentials to the legitimate application.

Decompile the source code and obtain the client key and the client secret

Hackers can decompile the mobile application source code and steal the client ID and secret.
The hacker will not be able to do much harm because he doesn’t have the resource owners username and password to obtain the authorization code.

Hackers can steal the access token

The IDP SDK does not save access tokens inside application private data therefore stealing access tokens is very difficult. During network communication if someone hijacks the access token, the risk can be minimised by setting up the scope and the access token validity period. (scope is the limit to what you can do with access token)

Advantage of IDP proxy application over mobile browser

As described in the authorization code grant type there is a resource owner authentication process that maintains the browser session. This can be achieved through either a mobile web browser or a web view embedded native application. In this implementation the IDP proxy application acts as a web view embedded native mobile application. The advantages of using IDP proxy application are as follows;

  1. uppose a user has to use native mobile web browser instead of IDP proxy application. They will have a choice to launch whichever the browser they like. If the user launches the same browser all the time SSO will work but if the user chooses a different browser SSO will fail because the browser sessions are not shared across different browsers.
  2. Assume that the user chooses the same mobile browser all the time. When the user wants to use that browser for some other purpose, the user has to maintain the browser session for SSO and do other work. This is a limitation from a usability standpoint.
  3. Suppose the user maintains a dedicated browser for IDP SDK and if they kill the browser session by mistake, SSO won’t work.
  4. A malicious program can act as a native mobile web browser and steal your username and password. During the authentication process the user enters their username and password in order to login. The login page is coming from authorization server and this can be considered as the most sensitive step. A malicious program can run an injected javascript to steal the username and password.


SSO for native mobile applications is one of the hottest topics these days[8]. Facebook, Twitter, Google and LinkedIn are some high end popular identity providers. All these identity providers support SSO for web applications and mobile applications. For mobile applications they provide platform dependent SDKs. WSO2 Identity Server is a lean open source product that can act as an identity provider. Given an SDK and IDP proxy application, you can use WSO2 Identity Server 4.6.0 or higher to implement SSO among native mobile applications.

Further Work

The proposed solution can satisfy most of the enterprise requirements but there are still some possible advancements. A hardcoded client secret is not a good idea sometimes because someone can decompile the application and get the client secret. OpenID Connect spec dynamic client generation provides a solution to this problem. We are hoping to integrate OpenID Connect dynamic client generation in the upcoming versions of IDP SDK. This article mainly focuses on SSO among mobile applications. How these applications can consume backend APIs will be explained in detail later on. This will be explained with WSO2 API manager in an upcoming article[5].



About Author

  • Gayan Gunawardana
  • WSO2