Version: v1.5

Hydra's User Login and Consent Flow

ORY Hydra uses a User Login and Consent Flow to include third-party user management (implemented by you) into the OAuth 2.0 and OpenID Connect authorization flow. An incoming authorization request is redirected to:

  1. the Login Provider: authenticates the user by validating his or her credentials (login)
  2. the Consent Provider: allows to select the OAuth 2.0 scopes that should be granted to the requesting application ("Do you want to allow foobar-app access to all your personal messages and images?")

You implement the Login and Consent providers in the technology stack of your choice.

The flow steps

The flow itself works as follows:

  1. The OAuth 2.0 Client initiates an Authorize Code, Hybrid, or Implicit flow. The user's user agent is redirect to http://hydra/oauth2/auth?client_id=...&....
  2. ORY Hydra, if unable to authenticate the user (= no session cookie exists), redirects the user's user agent to the Login Provider URL. The application "sitting" at that URL is implemented by you and typically shows a login user interface ("Please enter your username and password"). The URL the user is redirect to looks similar to http://login-service/login?login_challenge=1234....
  3. The Login Provider, once the user has successfully logged in, tells ORY Hydra some information about who the user is (e.g. the user's ID) and also that the login attempt was successful. This is done using a REST request which includes another redirect URL along the lines of http://hydra/oauth2/auth?client_id=...&...&login_verifier=4321.
  4. The user's user agent follows the redirect and lands back at ORY Hydra. Next, ORY Hydra redirects the user's user agent to the Consent Provider, hosted at - for example - http://consent-service/consent?consent_challenge=4567...
  5. The Consent Provider shows a user interface which asks the user if he/she would like to grant the OAuth 2.0 Client the requested permissions ("OAuth 2.0 Scope"). You've probably seen this screen around, which is usually something similar to: "Would you like to grant Facebook Image Backup access to all your private and public images?".
  6. The Consent Provider makes another REST request to ORY Hydra to let it know which permissions the user authorized, and if the user authorized the request at all. The user can usually choose to not grant an application any access to his/her personal data. In the response of that REST request, a redirect URL is included along the lines of http://hydra/oauth2/auth?client_id=...&...&consent_verifier=7654....
  7. The user's user agent follows that redirect.
  8. Now, the user has successfully authenticated and authorized the application. Next, ORY Hydra will run some checks and if everything works out, issue access, refresh, and ID tokens.

This flow allows you to take full control of the behaviour of your login system (e.g. 2FA, passwordless, ...) and consent screen. A well-documented reference implementation for both the Login and Consent Provider is available on GitHub.

The flow from a user's point of view

The flow from a network perspective

ORY Hydra User Login and Consent Flow

Last updated on by aeneasr