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:
- The user’s identity is verified by an external server, i.e., external authentication.
- 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:
- 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.
- 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.
- 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.
1. Setup Resource/Authorization server:
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.
- Client directed login operation (Azure): http://msdn.microsoft.com/en-us/library/windowsazure/jj710106.aspx
- Service directed login operation (Azure): http://msdn.microsoft.com/en-us/library/windowsazure/dn283952.aspx
- Queries on tables (similar concept to access API endpoints): http://msdn.microsoft.com/en-us/library/windowsazure/jj710104.aspx
- oAuth 2.0 Specifications: http://tools.ietf.org/html/rfc6749
- Official Supported Client SDK for Android: http://www.windowsazure.com/en-us/documentation/articles/mobile-services-android-get-started/
- Official Supported Client SDK for iOS: http://www.windowsazure.com/en-us/documentation/articles/mobile-services-ios-get-started/
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.