oAuth Flow for Mobile Apps with An External Identity Server

It is very common for mobile apps to depend on external login (like Facebook). In this article, we are going to discuss the oAuth flow for the following scenario:

  1. The user’s identity is verified by an external server, i.e., external authentication.
  2. The user’s access to a protected resource, i.e., an API endpoint, is determined by the internal server, i.e., internal authorization. In other words, the resource server and the authorization server in the oAuth 2.0 specification is the same server.

First, I will discuss the process and then I will give an example.

The oAuth Flow for the above scenario:

  1. The client, i.e., the mobile app, calls the external identity server and verifies the users identity. On a successful verification, it receives an token from the identity server. We will call it authorization_grant.
  2. The client sends the authorization_grant to the internal authorization server. The authorization server has a trust relationship with the identity server. So, it sends the authorization_grant to the identity server. If the identity server cannot verify the authorization_grant, it sends back 401 unauthorized to the authorization server, which it propagates to the client. If, however, the identity server successfully verifies the authorization_grant, then it sends back the user info to the authorization server. The authorization server checks the permissions of the user (by querying the database database or some other methods) and generates a token. We will call it the access_token. A typical access_token contains the user’s identity, permissions, and an expiry time. The authorization server sends back this access_token to the client.
  3. The client embed this access_token with each request for the protected resource, i.e., calling API endpoint. Depending on if the user is allowed to access the resource, he either gets it or receives 401 unauthorized.

Perhaps this flow is better explained by a diagram.

L

An Example:

In this example, we are going to use Facebook as the identity server, Windows Azure Mobile Services as the Resource and Authorization server, and Titanium SDK to build the client. We are choosing Titanium SDK because it is not officially supported by Windows Azure, which will let us implement these request calls from scratch as opposed to Android or iOS, which comes with an official Azure SDK that hides most of the implementation details. Also, Titanium SDK is JavaScript, which is easier to understand.

1. Setup Resource/Authorization server:

Go to Windows Azure, sign up for the free trial, and create a new mobile service (with JavaScript, i.e., Node.js as backend). You will find a pubic url to access the Mobile Service, say it is, https://my_resource_auth_server.azure-mobile.net

Click on Identity and under Facebbok Settings put you App ID and App Secret.

Setup 4 APIs called everyone, app, auth, and admin, and change the GET permission for these endpoints to Everyone, Anybody with the Application Key, Only Authenticated Users, and Only Administrators, respectively. So, for these 4 resources we added 4 levels of authorization that are supported by default by any Windows Azure Mobile Service. You can obviously override the Only Authenticated Users permission to implement more complex permission system, but that is out of scope of this article. Quickly change the GET scripts for these endpoints to add a custom message, for example:

To check if you are able to do this step correctly, go to https://my_resource_auth_server.azure-mobile.net/api/everyone from your browser and since this resource doesn’t require any authorization you should get something like:

However, if you try any of the other endpoints, for example, https://my_resource_auth_server.azure-mobile.net/api/auth, you should get a 401 unauthorized.

2. Get authorization_grant from Facebook:

Fire up Titanium Studio, create a new mobile project, and in your app.js write the following code to get an access_token (we call it authorization_grant) from facebook:

3. Get access_token from authorization_grant:

In this step, we are going to send the authorization_grant to our Resource/Authorization server to receive an access_token.

4. Get protected resources with access_token:

Now, we are going to use the access_token that we received in the previous step to get protected resources. You should notice that we are passing the access_token as X-ZUMO-AUTH header.

To get resource from https://my_resource_auth_server.azure-mobile.net/api/app, add a header called X-ZUMO-APPLICATION and pass your Application Key obtained from Azure website. Similarly, to access https://my_resource_auth_server.azure-mobile.net/api/admin pass your Mobile Service master key obtained from Azure website as X-ZUMO-MASTER header.

It should be noted that the above process will work with any JavaScript based client, however, if you want to do it from a browser you have to enable CORS (Cross Origin Resource Sharing) and add your website (where the JS code is hosted) url to your Mobile Service at Azure.

Happy coding!

Further Reading:

  1. Client directed login operation (Azure): http://msdn.microsoft.com/en-us/library/windowsazure/jj710106.aspx
  2. Service directed login operation (Azure): http://msdn.microsoft.com/en-us/library/windowsazure/dn283952.aspx
  3. Queries on tables (similar concept to access API endpoints): http://msdn.microsoft.com/en-us/library/windowsazure/jj710104.aspx
  4. oAuth 2.0 Specifications: http://tools.ietf.org/html/rfc6749
  5. Official Supported Client SDK for Android: http://www.windowsazure.com/en-us/documentation/articles/mobile-services-android-get-started/
  6. Official Supported Client SDK for iOS: http://www.windowsazure.com/en-us/documentation/articles/mobile-services-ios-get-started/

UPDATE:

Although, I used Titanium Mobile codes in this post as an example to make my point, but because of the lack of Titanium resources for Azure Mobile Services, I am getting a lot of questions on Titanium implementations. So, I have decided to quickly write a Titanium SDK for Windows Azure Mobile Services. You can check it out in github, it is very easy to use as it hides many technical details. The usage examples are also in the github. Let me know your feedback.

About these ads

Tagged: , , , , , , , , , , , , , , , , ,

13 thoughts on “oAuth Flow for Mobile Apps with An External Identity Server

  1. paulo March 24, 2014 at 3:12 pm Reply

    Hi Faisal,

    Thanks for taking the time and put this together. It really is helpful for all us Titanium Developers. I have one question though. I have been trying to get “POST” to work and all I get is “HTTP error” as a response. I have done all you suggested here, of course I customized to make it work for my case, yet nothing has worked. Do you have any ideas on how to solve this very unhelpful error response I am getting (“HTTP error”) ?

    Thanks for your time. Highly appreciated.

    • Faisal R. March 24, 2014 at 3:15 pm Reply

      Hi Paulo-
      I am looking into it, please check back within few hours.

    • Faisal R. March 24, 2014 at 4:12 pm Reply

      Hi Paulo-
      I know what happened.

      POST is meant for adding, means you may need to send a complex object to the api. So, you have to wrap it in JSON as the request body. Also, make sure that the content type is JSON.

      PUT is meant for update, that means you need to pass an id (to specify which entry to update) and a complex object that will be the updated entry. In this case, ideally you want to pass the id as an url parameter and the complex object as a JSON wrapped request body.

      Hope that make sense, feel free to ask me if you need more clarification.

      The following code shows examples of POST and PUT (I tested it, let me know if it doesn’t work for you): https://gist.github.com/rfaisal/9751003

  2. paulo March 25, 2014 at 11:20 am Reply

    Hi Faisal,

    Thanks for taking the time to help… really appreciate it. Going to try and will let you know.

    Again, you don’t know how grateful I am for helping.

  3. paulo March 25, 2014 at 12:05 pm Reply

    Hi Faisal,

    I went ahead and took a look at your code and all. I am not understanding something crucial in your examples.

    Please see my comment/questions here: https://gist.github.com/rfaisal/9751003

    Thanks Faisal!

  4. paulo March 26, 2014 at 4:43 pm Reply

    Hi Faisal,

    I will take a look and see if it works on my side. Here’s an example of table data in json format:

    [
    { "id" : "980UDKPL",
    "UserId" : "898UDKLMN",
    "Salutation" : "Mr.",
    "FirstName : "Andrew",
    ....

    ]

    I hope this makes sense.

    Thanks again!

    • Faisal R. March 26, 2014 at 4:46 pm Reply

      I was asking about the permission of your PATCH script, not the table data

  5. paulo March 27, 2014 at 10:18 am Reply

    Permission? Sorry, I don’t follow? Is there a way I can send you my script so you can take a look? I would post it on github, but there’s some sensitive info that I wouldn’t want to share with anyone else. Sorry for bugging you with this… I am just having lots of difficulties. I am not sure if it’s all on my side, or the webserver set up.

  6. […] this post, I am going to use the oAuth flow described in my previous blog post, which […]

  7. http://google.com/ June 14, 2014 at 5:45 pm Reply

    Thankfulness to my father who informed me about this blog,
    this webpage is genuinely awesome.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: