Skip to main content

OAuth 2.0

This section describes on a high level what OAuth 2.0 is and how it works. Please keep in mind that Ory Hydra is a technology targeted at professionals using OAuth 2.0 on a regular basis. While we try to cover some of the concepts, OAuth 2.0 and OpenID knowledge is expected from you in order to understand and use Ory Hydra to its fullest potential.

If you are new to these topics we recommend watching the following talk

and read these articles:

note

If you aren't building a system that involves third parties - for example a third party company (CircleCI) using your (GitHub) APIs - but instead are looking to solve "Single Sign On", mobile / single page app authentication, or generally "I want an API token after someone logs in", take a look at Ory Kratos instead!

OAuth 2.0​

The OAuth 2.0 authorization framework is specified in IETF RFC 6749. OAuth 2.0 enables a third-party application to obtain limited access to resources on an HTTP server on behalf of the owner of those resources.

Why is this important? Without OAuth 2.0, a resource owner who wants to share resources in their account with a third party would have to share their credentials with that third party. As an example, let's say you (a resource owner) have some photos (resources) stored on a social network (the resource server). Now you want to print them using a third-party printing service. Before OAuth 2.0 existed, you would have to enter your social network password into the printing service so that it can access and print your photos. Sharing secret passwords with third parties is obviously very problematic.

OAuth addresses this problem by introducing:

  • the distinction between resource ownership and resource access for clients
  • the ability to define fine-grained access privileges (called OAuth scopes) instead of full account access for third parties
  • an authorization layer and workflow that allows resource owners to grant particular clients particular types of access to particular resources.

With OAuth, clients can request access to resources on a server, and the owner of these resources can grant the requested access together with dedicated credentials. In our example, you could grant the printing service read-only access to your photos (only your photos, not your friend list) on the social network. These credentials come in the form of an access token -- a string denoting a specific scope, lifetime, and other access attributes. The client (printing service) can use this access token to request the protected resources (your photos) from the resource server (the social network).

Terminology​

To read more natural, this guide uses simpler terminologies like user instead of resource owner. Here is a full list of terms.

  1. A resource owner is the user account who authorizes an external application to access their account. This access is limited (scoped) to particular actions (the granted "scopes" like read photos or write messages). This guide refers to resource owners as users or end users.
  2. The OAuth 2.0 Authorization Server implements the OAuth 2.0 protocol (and optionally OpenID Connect). In our case, this is Ory Hydra.
  3. The resource provider is the service that hosts (provides) the resources. These resources (for example blog articles, printers, todo lists) are owned by a resource owner (user) mentioned above.
  4. The OAuth 2.0 Client is the external application that wants to access a resource owner's resources (read a user's images). To do that, it asks the OAuth 2.0 Authorization Server for an access token in a resource owner's behalf. The authorization server will ask the user if he/she "is ok with" giving that external application for example write access to personal images.
  5. The Identity Provider is a service that allows users to register accounts, log in, etc.
  6. User Agent is usually a browser.
  7. OpenID Connect is a protocol built on top of OAuth 2.0 for just authentication (instead of authorizing access to resources).

A typical OAuth 2.0 flow looks as follows:

  1. A developer registers an OAuth 2.0 Client (external application) with the Authorization Server (Ory Hydra) the intention to obtain information on behalf of a user.
  2. The application UI asks the user to authorize the application to access information/data on his/her behalf.
  3. The user is redirected to the Authorization Server.
  4. The Authorization Server confirms the user's identity and asks the user to grant the OAuth 2.0 Client certain permissions.
  5. The Authorization Server issues tokens that the OAuth 2.0 client uses to access resources on the user's behalf.

OAuth 2.0 Scope​

note

Please read the section about OAuth2 Scope in Do You Need OAuth2?.

A second important concept is the OAuth 2.0 Scope. Many people confuse OAuth 2.0 Scope with internal Access Control like for example Role Based Access Control (RBAC) or Access Control Lists (ACL). Both concepts cover different aspects of access control.

Internal access control (RBAC, ACL, etc) decides what a user can do in your system. An administrator might be allowed to modify everything. A regular user might only be allowed to read their own messages.

OAuth 2.0 Scopes, on the other hand, describe what a user allowed an external application (OAuth 2.0 client) to do on his/her behalf. For example, an access token might grant the external application to see a user's pictures, but not upload new pictures on his/her behalf (which we assume a user could do herself).

In an extreme case, the user could lie and grant an external application OAuth scopes that he himself doesn't have permission to ("read all classified documents"). The OAuth Access Token with those scopes wouldn't help the external application read those documents because it can only act in the name of the user, and that user doesn't have these access privileges.

The scope of an OAuth 2.0 scope defines the permission the token was granted by the end-user. For example, a specific token might be allowed to access public pictures, but not private ones. The granted permissions are established during the consent screen.

Ory Hydra has pre-defined OAuth 2.0 Scope values:

  • offline_access: Include this scope if you wish to receive a refresh token
  • openid: Include this scope if you wish to perform an OpenID Connect request.

When performing an OAuth 2.0 Flow where the end-user is involved (for example Implicit or Authorize Code), the granted OAuth 2.0 Scope must be set when accepting the consent using the grant_scope key.

OAuth 2.0 Access Token Audience​

The Audience of an Access Token refers to the Resource Servers that this token is intended for. The audience usually refers to one or more URLs such as

  • https://api.mydomain.com/blog/posts
  • https://api.mydomain.com/users

but may also refer to a subset of resources:

  • https://api.mydomain.com/tenants/foo/users

When performing an OAuth 2.0 Flow where the end-user is involved (for example Implicit or Authorize Code), the granted audience must be set when accepting the consent using the grant_access_token_audience key. In most cases, it's ok to grant the audience without user-interaction.

OAuth 2.0 Refresh Tokens​

OAuth 2.0 Refresh Tokens are issued only for the following flows:

  • Authorization Code Flow: response_type=code
  • OpenID Hybrid Flow with Authorization Code Flow reponse type: response_type=code+{other_response}

To get Refresh Tokens, OAuth 2.0 clients must be allowed to request the offline_access scope.

When performing the Authorization Code Flow, offline_access must be included in the requested scope:

https://authorization-server.com/auth
 ?response_type=code
 &scope=offline_access
 &client_id=...
 &redirect_uri=...
 &state=...

When accepting consent requests, the offline_access scope must be included in the list of grant_scope:

fetch('https://hydra/oauth2/auth/requests/consent/accept?challenge=' + encodeURIComponent(challenge), {
    method: 'PUT',
    body: JSON.stringify(body),
    headers: { 'Content-Type': 'application/json' }
}).
const body = {
    grant_scope: ["offline_access"],
}

You can adjust the Refresh Token lifespan (TTL) using the ttl.refresh_token configuration key. By default, the TTL is set to 1 hour.

tip

If you set ttl.refresh_token to -1, Refresh Tokens never expire.

OAuth 2.0 Token Introspection​

OAuth2 Token Introspection is an IETF standard. It defines a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token. OAuth 2.0 deployments can use this method to convey information about the authorization context of the token from the authorization server to the protected resource.

The usage of an access token or client credentials is required to access the endpoint. Ory Hydra will however accept any valid token or valid credentials as there is no built-in access control.