Installation and Setup
The goal of this chapter is to introduce you to a fully functional set up that includes ORY Hydra as well as our User Login & Consent Provider reference implementation.
The goal of this section is to familiarize you with the specifics of setting up ORY Hydra in your environment. Before starting with this section, please check out the tutorial. It will teach you the most important flows and settings for Hydra.
This guide will:
- Download and run a PostgreSQL container in Docker.
- Download and run ORY Hydra in Docker.
- Download and run our reference User Login & Consent Provider.
- Create an OAuth 2.0 Client to perform the OAuth 2.0 Authorize Code Flow.
- Perform the OAuth 2.0 Authorize Code flow.
Before starting with this guide, please install the most recent version of Docker. While docker is not required for running ORY Hydra, we recommend using it for this tutorial as it will greatly reduce the complexity of setting up a database on your system without virtualization, installing Go, and compiling ORY Hydra.
Create a Network#
Before we can start, a network must be created which we will attach all our Docker containers to. That way, the containers can talk to one another.
Deploy PostgreSQL#
For the purpose of this tutorial, we will use PostgreSQL as a database. As you probably already know, don't run databases in Docker in production! For the sake of this tutorial however, let's use Docker to quickly deploy the database.
This command wil start a postgres instance with name
ory-hydra-example--postgres, set up a database called hydra and create a
user hydra with password secret.
Deploy ORY Hydra#
We highly recommend using Docker to run Hydra, as installing, configuring and running Hydra is easiest with Docker. ORY Hydra is available on Docker Hub.
Let's dive into the various settings:
--network hydraguideconnects this instance to the network and makes it possible to connect to the PostgreSQL database.-p 9000:4444exposes ORY Hydra's public API onhttps://localhost:9000/.-p 9001:4445exposes ORY Hydra's administrative API onhttps://localhost:9001/.-e SECRETS_SYSTEM=$SECRETS_SYSTEMsets the system secret environment variable (required).-e DSN=$DSNsets the database url environment variable (required).-e URLS_SELF_ISSUER=https://localhost:9000/this value must be set to the publicly available URL of ORY Hydra (required).-e URLS_CONSENT=http://localhost:9020/consentthis sets the URL of the consent provider (required). We will set up the service that handles requests at that URL in the next sections.-e URLS_LOGIN=http://localhost:9020/loginthis sets the URL of the login provider (required). We will set up the service that handles requests at that URL in the next sections.
Note: In this example we did not define a value for the optional setting
OAUTH2_ERROR_URL. This URL can be used to provide an endpoint which will
receive error messages from ORY Hydra that should be displayed to the end user.
The URL receives error and error_description parameters. If this value is
not set, Hydra uses the fallback endpoint /oauth2/fallbacks/error and displays
a default error message. In order to obtain a uniform UI, you might want to
include such an endpoint in your login or consent provider.
To confirm that the instance is running properly,
open the health check. If asked, accept
the self signed certificate in your browser. You should simply see ok.
On start up, ORY Hydra is initializing some values. Let's take a look at the logs:
As you can see, the following steps are performed when running ORY Hydra against a fresh database:
- If no system secret was given (in our case we provided one), a random one is generated and emitted to the logs. Note this down, otherwise you won't be able to restart Hydra.
- Cryptographic keys are generated for the OpenID Connect ID Token, the consent
challenge and response, and TLS encryption using a self-signed certificate,
which is why we need to run all commands using
--skip-tls-verify.
ORY Hydra can be managed using the Hydra Command Line Interface (CLI), which is using ORY Hydra's REST APIs. To see the available commands, run:
Deploy Login & Consent App#
The Login Provider and Consent Provider can be two separate web services. We provide a reference implementation which combines both features in one app. Here, we will use deploy that app using Docker.
Let's take a look at the arguments:
-p 9020:3000exposes this service at port 9020. If you remember, that's the port of theURLS_CONSENTandURLS_LOGINvalue from the ORY Hydra docker container (URLS_CONSENT=http://localhost:9020/consent,URLS_LOGIN=http://localhost:9020/login).HYDRA_ADMIN_URL=http://hydra:4445point to the ORY Hydra Administrative API.NODE_TLS_REJECT_UNAUTHORIZED=0disables TLS verification, because we are using self-signed certificates.
Perform OAuth 2.0 Flow#
Great! Our infrastructure is all set up! Next it's time to perform the OAuth 2.0 Authorize Code flow. For that purpose, the ORY Hydra CLI has a feature that sets up an OAuth 2.0 Consumer and an OAuth 2.0 callback URL. Typically, this would be a third-party application that requests access to a user's resources on your servers - for example a Facebook App you wrote that backs up a user's photos and thus requires read access to the user's photos.
Before we go ahead, the OAuth 2.0 Client that performs the request has to be set
up. Let's call the client facebook-photo-backup. We have to specify which
OAuth 2.0 Grant Types, OAuth 2.0 Scope, OAuth 2.0 Response Types, and Callback
URLs the client may request:
Let's dive into some of the arguments:
--skip-tls-verifyis supported by all management commands (create/delete/update/... OAuth 2.0 Client, JSON Web Key, ...) and tells the CLI to trust any certificate authority - even self-signed ones. We need this flag because the server uses a self-signed certificate. In production deployments, you would use a certificate signed by a trusted CA.--grant-types authorize_code,refresh_token,client_credentials,implicitwe want to be able to perform all of these OAuth 2.0 flows.--response-types token,code,id_tokenallows us to receive authorize codes, access and refresh tokens, and OpenID Connect ID Tokens.--scope openid,offline,photos.readallows the client to request various permissions:openidallows the client to perform the OpenID Connect flow and request an OpenID Connect ID Token.offlineallows the client to request a refresh token. Because we want to continuously backup photos, the app must be able to refresh expired access tokens. This scope allows that.photos.readthis is an imaginary scope that is not handled by ORY Hydra but serves the purpose of making it clear that we could request read access to a user's photos. You can obviously omit this scope or use your own scope.
--callbacks http://localhost:9010/callbackallows the client to request this redirect uri.
Perfect, let's perform an exemplary OAuth 2.0 Authorize Code Flow! To make this
easy, the ORY Hydra CLI provides a helper command called hydra token user.
Just imagine this being, for example, passport.js that is generating an auth
code url, redirecting the browser to it, and then exchanging the authorize code
for an access token. The same thing happens with this command:
open the link, as prompted, in your browser, and follow the steps shown there. You might encounter a screen like the following one:
;This happens because we run ORY Hydra with a self-signed TLS certificate. In production deployments, you would probably use a certificate signed by a trusted CA and not see this screen.
When you see this screen, click on "Advanced" and "Add Exception" to continue. In some browsers, this might work differently, but it's always possible to proceed.
When completed, you should land at a screen that looks like this one:
;