Welcome to the Hydra documentation. This documentation will
Let us begin with the first part, understanding what OAuth2 and OpenID Connect are.
This section will give you some ideas of what OAuth 2.0 and OpenID Connect 1.0 are for. If you already know what OAuth2 and OpenID Connect are and how they works, you can skip to the next Section. This section will not explain how the various flows of OAuth2 work and how they look like. We strongly recommend to read the following articles:
The OAuth 2.0 authorization framework is a memo in the Request for Comments document series published by the IETF Internet Engineering Task Force (IETF). Memos in the Requests for Comments (RFC) document series contain technical and organizational notes about the Internet. They cover many aspects of computer networking, including protocols, procedures, programs, and concepts [...].
The OAuth 2.0 authorization framework enables a third-party application 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 application to obtain access on its own behalf.
In the traditional client-server authentication model, the client requests an access-restricted resource (protected resource) on the server by authenticating with the server using the resource owner's credentials. In order to provide third-party applications access to restricted resources, the resource owner shares its credentials with the third party. This creates several problems and limitations.
OAuth addresses these issues by introducing an authorization layer and separating the role of the client from that of the resource owner. In OAuth, the client requests access to resources controlled by the resource owner and hosted by the resource server, and is issued a different set of credentials than those of the resource owner.
Instead of using the resource owner's credentials to access protected resources, the client obtains an access token -- a string denoting a specific scope, lifetime, and other access attributes. Access tokens are issued to third-party clients by an authorization server with the approval of the resource owner. The client uses the access token to access the protected resources hosted by the resource server.
Source: IETF RFC 6749
An end-user (resource owner) can grant a printing service (client) access to her protected photos stored at a photo- sharing service (resource server), without sharing her username and password with the printing service. Instead, she authenticates directly with a server trusted by the photo-sharing service (authorization server), which issues the printing service delegation- specific credentials (access token).
Source: IETF RFC 6749
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
As background, the OAuth 2.0 Authorization Framework and OAuth 2.0 Bearer Token Usage specifications provide a general framework for third-party applications to obtain and use limited access to HTTP resources. They define mechanisms to obtain and use Access Tokens to access resources but do not define standard methods to provide identity information. Notably, without profiling OAuth 2.0, it is incapable of providing information about the authentication of an End-User.
OpenID Connect implements authentication as an extension to the OAuth 2.0 authorization process.
Source OpenID Connect Core 1.0
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
There are different work flows for OpenID Connect 1.0, we recommend checking out the OpenID Connect sandbox at openidconnect.net.
Hydra is a server implementation of the OAuth 2.0 authorization framework and the OpenID Connect Core 1.0. Existing OAuth2 implementations usually ship as libraries or SDKs such as node-oauth2-server or fosite, or as fully featured identity solutions with user management and user interfaces, such as Dex or Okta.
Implementing and using OAuth2 without understanding the whole specification is challenging and prone to errors, even when SDKs are being used. The primary goal of Hydra is to make OAuth 2.0 and OpenID Connect 1.0 less painful to set up and easier to use.
Hydra implements the flows described in OAuth2 and OpenID Connect 1.0 without forcing you to use a "Hydra User Management" or some template engine or a predefined front-end. Instead it relies on HTTP redirection and cryptographic methods to verify user consent allowing you to use Hydra with any authentication endpoint, be it authboss, auth0.com or your proprietary PHP authentication.
Hydra incorporates best practices in the area of the web service technology:
Hydra has a limitations too:
OAuth2 is used in many areas, for various purposes and supported by all well known programming languages, but it is important to understand what the vision of OAuth2 is. This non-exclusive list might help you decide, if OAuth 2.0 and Hydra are the right fit for you.
OAuth2 and OpenID Connect are tricky to understand. It is important to understand that OAuth2 is a delegation protocol. It makes sense to use Hydra in new and existing projects. A use case covering an existing project explains how one would use Hydra in a new one as well. So let's look at a use case!
Let's assume we are running a ToDo List App (todo24.com). ToDo24 has a login endpoint (todo24.com/login). The login endpoint is written in node and uses MongoDB to store user information (email + password + settings). Of course, todo24 has other services as well: list management (todo24.com/lists/manage: close, create, move), item management (todo24.com/lists/items/manage: mark solved, add), and so on. You are using cookies to see which user is performing the request.
Now you decide to use OAuth2 on top of your current infrastructure. There are many reasons to do this:
These are only a couple of reasons to use OAuth2. You might decide to use OAuth2 as your single source of authorization, thus maintaining only one authorization protocol and being able to open up to third party devs in no time. With OpenID Connect, you are able to delegate authentication as well as authorization!
Your decision is final. You want to use OAuth2 and you want Hydra to do the job. You install Hydra in your cluster using docker. Next, you set up some exemplary OAuth2 clients. Clients can act on their own, but most of the time they need to access a user's todo lists. To do so, the client initiates an OAuth2 request. This is where Hydra's authentication flow comes in to play. Before Hydra can issue an access token, we need to know WHICH user is giving consent. To do so, Hydra redirects the user agent (e.g. browser, mobile device) to the login endpoint alongside with a challenge that contains an expiry time and other information. The login endpoint (todo24.com/login) authenticates the user as usual, e.g. by username & password, session cookie or other means. Upon successful authentication, the login endpoint asks for the user's consent: "Do you want to grant MyCoolAnalyticsApp read & write access to all your todo lists? [Yes] [No]". Once the user clicks Yes and gives consent, the login endpoint redirects back to hydra and appends something called a consent token. The consent token is a cryptographically signed string that contains information about the user, specifically the user's unique id. Hydra validates the signature's trustworthiness and issues an OAuth2 access token and optionally a refresh or OpenID token.
Every time a request containing an access token hits a resource server (todo24.com/lists/manage), you make a request to Hydra asking who the token's subject (the user who authorized the client to create a token on its behalf) is and whether the token is valid or not. You may optionally ask if the token has permission to perform a certain action.