Implementing OAuth with ASWebAuthenticationSession

Do you need to authenticate your users against a third-party app? Perhaps your client has requested that you implement such a mechanism using the OAuth standard?

What if you’re working in an enterprise setting and your client uses Active Directory to manage users and Okta or Ping Federate to control how a third-party app interacts with protected resources?

In this tutorial, you’ll create a third-party GitHub app that you can authenticate via the OAuth standard using ASWebAuthenticationSession and display a list of repositories owned by the user. In the process, you’ll learn about:

• OAuth
• Session tokens
• Ephemeral sessions

Getting Started

In a traditional client app that authenticates against a server, the server stores the username and password to authenticate a user and permit user access. This is fine when no third parties are involved.

But what happens when apps like GitHub want to add support for third-party apps?

That’s where things get tricky and a few shortcomings surface. Without OAuth, several issues can come up:

• To avoid constantly requesting the user’s credentials, the third-party app has to store and manage them somewhere.
• The password authentication method is more vulnerable.
• GitHub cannot restrict, revoke or limit access to third-party apps, as they have the user’s full credentials.
• If the third-party app is compromised, so is the user’s GitHub account.

How can GitHub (the server app) provide you (a third-party app) with access to its protected resources without giving full, unrestricted access? That’s where OAuth comes in.

Understanding OAuth

From the Internet Engineering Task Force’s (IETF) website, here’s the definition of the OAuth 2.0 standard:

“The OAuth 2.0 authorization framework enables a third-party app to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party app to obtain access on its own behalf.”

Your third-party app doesn’t store any user credentials or handle authenticating users directly. That’s something you’re hoping to have GitHub, with its robust infrastructure and security, do for you.

What you want your third-party app to do is allow users to log in with their own GitHub credentials to access specific resources within GitHub.

Another scenario is using GitHub to implement user authentication — without having to spend too much time on the implementation and security details — but not access any GitHub resources outside of validating the user’s identity.

This is why apps and websites often use the Sign in with buttons for a third-party service like Facebook, Apple or Google. They’re leaving it up to those parties to handle the server security and sign-in infrastructure.

Authorization Versus Authentication

OAuth helps by separating the authentication process from the authorization process.

But what exactly is the difference? Aren’t they the same? You might be surprised, after years of using the two terms interchangeably, that they are not.

• Authentication: Who you are.
• Authorization: Which permissions the service has given you.

In this tutorial, GitHub will give your app certain accesses and permissions: authorization. But it’s up to users to validate themselves and verify who they are against GitHub: authentication.

OAuth Roles

So far, you’ve read about what OAuth is and the difference between authentication and authorization. Behind the scenes, OAuth has a few more concepts that are important to learn about. The first is roles.

OAuth defines four roles:

• Resource Owner: Whoever can give access to a protected resource.
• Resource Server: The server that contains the protected resource.
• Client: An app that tries to access protected resources with authorization and on behalf of the resource owner.
• Authorization Server: Gives access tokens to the client upon successful authentication and authorization.

The OAuth Flow

The OAuth standard defines the following as the typical flow of a third-party app. This is what you’ll implement in this tutorial:

1. Your app asks for an access token, a short-lived token used in requests against the resource owner. To do so, it must present the authorization server with a client ID and allow the user to authenticate with their credentials.
2. The authorization server authenticates the client, then returns an access token and a refresh token for this user, to be used in your app only. This is assuming everything’s valid and went well.
3. Your app, the client, makes a request to a protected resource from the resource owner. The client must then present the user’s access token or the request will fail.
4. The resource owner validates your user’s access token. If it’s valid, then it returns the requested resource.
5. Your app continues to make requests on behalf of the user until the access token expires. When this happens, the next request you make to the resource owner will result in an invalid token error.
6. Your app can use the refresh token, often a longer-lived token, to request a new access token from the authorization server. The same scope and restrictions apply as before.
7. If your refresh token is still valid, the authorization server will issue a new access token for your app. If the refresh token expired, the user must authenticate with their credentials again.

OAuth is heavily web-based, which means most implementations show some sort of web view to your users to let them enter their credentials. Behind the scenes, there are some redirects and callbacks that take place and make everything work. Don’t worry, this tutorial will help you handle all of that.

There’s been quite a bit of theory so far, but now you have a better understanding of OAuth and how it works.

Creating a GitHub App

You want your app to talk to GitHub. GitHub needs to know where the user is trying to access its resources from — your app — and which resources it should grant access to.

It’s time to create a GitHub app from your account. Here’s how to get started!

On your web browser, open and log in to GitHub. In the top-right corner, click your profile image. Then, click Settings:

Click Developer settings:

Click GitHub Apps. Click the New GitHub App button:

When creating a new app, there are quite a few options and settings. You’ll go through them now.

Name your app AuthHub-. Give your app a description of your choice.

Add the homepage URL for your app. This example uses https://www.raywenderlich.com/. If you’re creating your own app, it should link to your app’s homepage, where users can get more information.