OAuth 2.0 Clients

3

This chapter is a short overview of working with typical OAuth 2.0 APIs. While each implementation of OAuth 2.0 can be slightly different, in practice, most of them share a lot in common. This chapter serves as an introduction to OAuth 2.0 for those new to it, and gives an example of how the three main types of applications interact with OAuth 2.0 APIs.

Creating an Application

Before you can interact with an OAuth 2.0 API, you must first register an application with the service. The registration process typically involves creating an account on the service’s website, then entering basic information about the application such as the name, website, logo, etc. After registering the application, you will be given a client_id and client_secret that will be used during the authorization process.

One of the most important things when creating the application is to register one or more redirect URLs the application will use. The redirect URLs are where the OAuth 2.0 service will return the user to after they have authorized the application. It is critical that these are registered, otherwise it is easy to create malicious applications that can steal user data. This is covered in more detail later in this chapter.

Each service implements the registration process a slightly different way, so we’ll walk through an example of creating an application on GitHub.

GitHub

From your “Account Settings” page, click on the “Applications” link in the sidebar. You will end up on https://github.com/settings/applications. From there, click “Register new application” and you will be presented with a short form, as shown below.

Register a new application on GitHub

Fill out the required information, including the callback URL. If you are developing an application locally, you’ll have to use the local address for the callback URL. Since GitHub allows only one registered callback URL per application, it is useful to create two applications, one for development, and a separate one for production.

After completing this form, you’ll be taken to a page where you can see the client ID and secret issued to your application, shown below.

GitHub application has been created

The client ID is considered public information, and is used to build login URLs, or can be included in the Javascript source code of a web page. The client secret must be kept confidential. If a deployed app cannot keep the secret confidential, such as Javascript or native apps, then the secret is not used during authorization.

Redirect URLs and State

OAuth 2.0 APIs will only redirect users to a registered URL, in order to prevent redirection attacks where an authorization code or access token can be obtained by an attacker. Some services may allow you to register multiple redirect URLs, which can help when using the same client ID for a web app and a mobile app, or when using the same client ID for development and production services.

In order to be secure, the redirect URL must be an https endpoint to prevent tokens from being intercepted during the authorization process. If your redirect URL is not https, then an attacker may be able to intercept the authorization code and use it to hijack a session. If a service allows non-https redirects to be used, then they must take extra precautions to ensure this kind of attack is not possible.

Most services treat redirect URL validation as an exact match. This means a redirect URL of https://example.com/auth would not match https://example.com/auth?destination=account. It is best practice to avoid using query string parameters in your redirect URL, and have it include just a path.

Some applications may have multiple places they want to start the OAuth process from, such as a login link on a home page as well as a login link when viewing some public item. For these applications, it may be tempting to try to register multiple redirect URLs, or you may think you need to be able to vary the redirect URL per request. Instead, OAuth 2.0 provides a mechanism for this, the “state” parameter.

The “state” parameter can be used for whatever you want, it is a string that is opaque to the OAuth 2.0 service. Whatever state value you pass in during the initial authorization request will be returned after the user authorizes the application. One common application of this is including a random string to prevent CSRF attacks. You could also encode a redirect URL in something like a JWT and parse this after the user is redirected back to your application so you can take the user back to the appropriate location after they sign in.