OAuth 2.0 with Swift Tutorial

It’s likely that you’ve bumped into OAuth 2.0 and the different families of flows while building apps to share content with your favorite social network (Facebook, Twitter, etc) or with your enterprise OAuth 2.0 server — even if you weren’t aware of what was going on under the hood. But do you know how to hook up to your service using OAuth 2.0 in an iOS app?

In this tutorial, you’ll work on a selfie-sharing app named Incognito as you learn how to use the AeroGear OAuth2 and OAuthSwift open source OAuth 2.0 libraries to share your selfies on Google Drive.

Getting Started

Download the Incognito starter project. The starter project uses CocoaPods to fetch AeroGear dependencies and contains everything you need, including generated pods and xcworkspace directories.

Open Incognito.xcworkspace in Xcode. The project is based on a standard Xcode Single View Application template, with a single storyboard which contains a single view controller ViewController.swift. All UI actions are already handled in ViewController.swift.

Build and run your project to see what the app looks like:

The app lets you pick your best selfie and add some accessories to the image. Did you recognize me behind my disguise? :]

Note: To add photos in the simulator, simply go to the home screen using Cmd + Shift + H and drag and drop your images onto the simulator.

The missing part in the app is adding the ability to share on Google Drive using two different OAuth 2.0 libraries.

Mission impossible? Nope, it’s nothing you can’t handle! :]

Instead of boring you with an introduction to the RFC6749 OAuth2 specification, let me tell you a story…

Explaining the Need for OAuth 2.0

On Monday morning, Bob, our mobile nerd bumps into Alice, another friendly geek, in front of the coffee machine. Bob seems busy, carrying a heavy bunch of documents: his boss wants him to delve into the OAuth 2.0 specification for the Incognito app.

Put any two developers in a coffee room and soon they’ll chat about geeky things, of course. Bob asks Alice:

“…what problem are we trying to solve with OAuth 2.0?”

On one side, you have services in the form of APIs, such as the Twitter API, which you can use to get a list of followers or Tweets. Those APIs handle your confidential data, which is protected by a login and password.

On the other side, you have apps that consume those services. Those apps need to access your data, but do you want to trust all of them with your credentials? Maybe — but maybe not.

This brings up the concept of delegated access. OAuth2 lets users grant third-party apps access to their web resources, without sharing their passwords, through a security object known as an access token. It’s impossible to obtain the password from the access token, since your password is kept safe inside the main service. If an app wants to connect to the service, it must get its own access token. Access tokens can then be revoked if you ever want to revoke access to just that app.

OAuth 2.0 works with the following four actors:

• authorization server: responsible for authentication and authorization — it provides the access token.
• resource server: in charge of serving up resources if a valid token is provided.
• resource owner: the owner of the data — that is, the end user of Incognito.
• client: the Incognito mobile app.

The OAuth 2.0 specification describes the interactions between these actors as grant flows.

The specification details four different grant flows that can be grouped into two different families:

• 3-legged flows: the end user needs to grant permission in these cases. The implicit grant is for browser-based apps that aren’t capable of keeping tokens secure. The authorization code grant, which generates an access token and optionally a refresh token, is for clients capable of keeping tokens secure. Such clients include mobile apps which have somewhere secure they can store the token, such as in the keychain on iOS.
• 2-legged flows: the credentials are given to the app. The key difference here is that the resource owner inputs the credentials directly into the client. An example of where you see this in practice is when accessing many APIs, e.g. Parse, as a developer and put your key in your app.

You’ll use your existing Google Drive account and upload your Incognito selfies there. This is a good case for implementation of the 3-legged authorization code grant.

The Authorization Dance

Although using open source libraries hides most of the sticky details of the OAuth 2.0 protocol from you, knowing its basic inner workings will help you get the configuration right.

Here are the steps involved in the authorization code grant dance:

Step 0: Registration

Your application needs to be registered with the service you want to access. In your case, for Incognito, that’s Google Drive. Don’t worry, the following section will explain how to do that.

Step 1: Authorization Code

The dance begins when Incognito sends a request for an authorization code to the third-party service that includes:

• client ID: Provided during service registration. Defines which app is talking to the service.
• redirect URI: Where the user should be redirected after entering their credentials into the service, and granting permission.
• scope: Used to tell the service what level of permission the app should have.

The app then switches to the web browser. Once the user logs in, the Google authorization server displays a grant page: “Incognito would like to access your photos: Allow/Deny”. When the end user clicks “Allow”, the server redirects to the Incognito app using the redirect URI and sends an authorization code to the app.

Step 2: Exchange Code for Token

The authorization code is only temporary; therefore the OAuth 2.0 library has to exchange this temporary code for a proper access token, and optionally, a refresh token.