OAuth2 with ORY Hydra, Vapor 3 and iOS 12

Part 1: Introduction and setup of ORY Hydra authorization server

In this tutorial we try to give you a broad understanding on how to implement the OAuth2 authorization code flow with an iOS app, a Vapor API and Hydra as the OAuth2 server.

Tutorial series

Part 1: Introduction and setup of ORY Hydra authorization server (you are here)

Part 2: User management in Vapor backend

Part 3: Set up Vapor backend as identity provider for ORY Hydra

Part 4: Set up OAuth2 authorization on iOS with AppAuth

Prerequisites

You need a Mac, at least for building the iOS app. It is also helpful for debugging the Vapor backend.

You need to have Docker installed (https://www.docker.com/get-started)

You should have a basic understanding of how the OAuth2 authorization code flow with OpenID Connect works. There is plenty of resources on this, you could checkout this introduction by DigitalOcean for example.

Note that this tutorial will just set up everything on your local machine and is considered non-production-ready. For example, we will store the client secret in the iOS app, which you should never do. If there will be demand for it, we might do an additional part of this tutorial that focuses on making the whole setup production ready.

Motivation

We are working on a product where security is a concern, so relying on best practice user authentication is definitely the way to go. Setting up OAuth2 usually is a big hassle though. ORY Hydra relieves you of the burden of implementing your own OAuth2 server, but still requires/allows you to use your own identity provider. This caused some confusion for us about which parts of the auth flow need to be implemented in our backend as part of the identity provider and which parts are provided by Hydra. In this tutorial we’ll try to make it a little bit clearer what responsibilities each part handles when developing an iOS app with a Vapor backend and Hydra as your OAuth2 server.

End result

This is what the app will look like when we are finished:

Closer look at the 3 components

iOS App

The iOS app will be very simple in nature and will just feature two native screens: The login prompt screen and the success screen that shows you that you just authenticated your user successfully. We will use AppAuth for handling OAuth tokens inside the app.

Vapor backend

The Vapor backend will contain the user management and also serve as an identity and consent provider to deliver the HTML Login and Register screens. The consent step will be automatically skipped as this is not needed for a first party app like this one. We can assume that a user that wants to login on our platform also wants to give it access rights to his data.

ORY Hydra

Hydra is an open source OAuth2 server that manages the authorization flow by delegating user authentication (login, register) to the identity provider (Vapor backend in our case). In case of success it will issue access, refresh and id tokens, that can be used to authenticate requests to access restricted data (i.e. user profile) on the backend.

Component setup

This might already be confusing, so let’s try to understand it better by breaking down what is needed for the setup: