Advanced OAuth2 and OpenID Connect flows

OAuth 2.0

Audience

There are two types of audience concept in the context of OAuth 2.0 and OpenID Connect:

1. OAuth 2.0: Access and Refresh Tokens are "internal-facing". The aud claim of an OAuth 2.0 Access and Refresh token defines at which endpoints the token can be used.
2. OpenID Connect: The ID Token is "external-facing". The aud claim of an OpenID Connect ID Token defines which clients should accept it.

While modifying the audience of an ID Token isn't desirable, specifying the audience of an OAuth 2.0 Access Token is. This isn't defined as an IETF Standard but is considered good practice in certain environments.

For this reason, Hydra allows you to control the aud claim of the access token. To do so, you must specify the intended audiences in the OAuth 2.0 Client's metadata on a per-client basis:

{
    "client_id": "...",
    "audience": ["https://api.my-cloud.com/user", "https://some-tenant.my-cloud.com/"]
}

The audience is a list of case-sensitive URLs. URLs must not contain whitespaces.

OAuth 2.0 authorization code, implicit, and hybrid flows

When performing an OAuth 2.0 authorize code, implicit, or hybrid flow, you can request audiences at the /oauth2/auth endpoint https://my-hydra.com/oauth2/auth?client_id=...&scope=...&audience=https%3A%2F%2Fapi.my-cloud.com%2Fuser+https%3A%2F%2Fsome-tenant.my-cloud.com%2F which requests audiences https://api.my-cloud.com/user and https://some-tenant.my-cloud.com/.

The audience query parameter may contain multiple strings separated by a url-encoded space (+ or %20). The audience values themselves must also be url encoded. The values will be validated against the whitelisted audiences defined in the OAuth 2.0 Client:

• An OAuth 2.0 Client with the allowed audience https://api.my-cloud/user is allowed to request audience values https://api.my-cloud/user https://api.my-cloud/user/1234 but not https://api.my-cloud/not-user nor https://something-else/.

The requested audience from the query parameter is then part of the login and consent request payload as field requested_access_token_audience. You can then alter the audience using grant_audience.access_token when accepting the consent request:

hydra.acceptConsentRequest(challenge, {
  // Ory Hydra checks if requested audiences are allowed by the client, so we can simply echo this.
  grant_audience: {
    access_token: response.requested_access_token_audience,
    // or, for example:
    // access_token: ["https://api.my-cloud/not-user"]
  },

  // ... remember: false
  // ...
})

When introspecting the OAuth 2.0 Access Token, the response payload will include the audience:

{
  "active": true,
  // ...
  "audience": ["https://api.my-cloud/user", "https://api.my-cloud/user/1234"]
}

OAuth 2.0 client credentials grant

When performing the client credentials grant, the audience parameter from the POST body of the /oauth2/token is decoded and validated according to the same rules of the previous section, except for the login and consent part which does not exist for this flow.

JSON Web Tokens

Ory Hydra issues opaque OAuth 2.0 Access Tokens per default for the following reasons:

1. OAuth 2.0 Access Tokens represent internal state but are public knowledge: An Access Token often contains internal data (such as session data) or other sensitive data (such as user roles and permissions) and is sometimes used as a means of transporting system-relevant information in a stateless manner. Therefore, making these tokens transparent (by using JSON Web Tokens as Access Tokens) comes with risk of exposing this information, and with the downside of not storing this information in the OAuth 2.0 Access Token at all.
2. JSON Web Tokens can't hold secrets: Unless encrypted, JSON Web Tokens can be read by everyone, including 3rd Parties. Therefore, they can't keep secrets. This point is similar to (1), but it's important to stress this.
3. Access Tokens as JSON Web Tokens can't be revoked: Well, you can revoke them, but they will be considered valid until the "expiry" of the token is reached. Unless, of course, you have a blacklist or check with Hydra if the token was revoked, which however defeats the purpose of using JSON Web Tokens in the first place.
4. Certain OpenID Connect features won't work when using JSON Web Tokens as Access Tokens, such as the pairwise subject identifier algorithm.
5. There is a better solution: Use Ory Oathkeeper! Ory Oathkeeper is a proxy you deploy in front of your services. It will "convert" Ory Hydra's opaque Access Tokens into JSON Web Tokens for your backend services. This allows your services to work without additional REST Calls while solving all previous points. We really recommend this option if you want JWTs!

If you aren't convinced that Ory Oathkeeper is the right tool for the job, you can still enable JSON Web Tokens in Ory Hydra by setting:

strategies:
  access_token: jwt

Be aware that only access tokens are formatted as JSON Web Tokens. Refresh tokens aren't impacted by this strategy. By performing OAuth 2.0 Token Introspection you can check if the token is still valid. If a token is revoked or otherwise blacklisted, the OAuth 2.0 Token Introspection will return { "active": false }. This is useful when you don't want to rely only on the token's expiry.

JSON Web Token validation

You can validate JSON Web Tokens issued by Ory Hydra by pointing your jwt library (for example node-jwks-rsa) to http://ory-hydra-public-api/.well-known/jwks.json. All necessary keys are available there.

Adding custom claims top-level to the Access Token

Assume you want to add custom claims to the access token with the following code:

let session: ConsentRequestSession = {
  access_token: {
    foo: "bar",
  },
}

Then part of the resulting access token will look like this:

{
  "ext": {
    "foo": "bar"
  }
}

If you instead want "foo" to be added top-level in the access token, you need to set the configuration flag oauth2.allowed_top_level_claims like described in the reference Configuration.

Note: Any user defined allowed top level claim may not override standardized access token claim names.

Configuring Hydra to allow "foo" as a top-level claim will result in the following access token part (allowed claims get mirrored, for backwards compatibility):

{
  "foo": "bar",
  "ext": {
    "foo": "bar"
  }
}

OAuth 2.0 Client Authentication with private/public keypairs

Please head over to the RFC7523 Documentation.

OpenID Connect

Subject identifier algorithms

Hydra supports two Subject Identifier Algorithms:

• public: This provides the same sub (subject) value to all Clients (default).
• pairwise: This provides a different sub value to each Client, so as not to enable Clients to correlate the End-User's activities without permission.

You can enable either one or both algorithms using the following configuration layout:

oidc:
  subject_identifiers:
    supported_types:
      - public
      - pairwise

When pairwise is enabled, you must also set oidc.subject_identifiers.pairwise.salt. The salt is used to obfuscate the sub value:

oidc:
  subject_identifiers:
    supported_types:
      - public
      - pairwise
    pairwise:
      salt: some-salt

This value shouldn't be changed once set in production. Changing it will cause all client applications to receive new user IDs from Ory Hydra which will lead to serious complications with authentication on their side!

Each OAuth 2.0 Client has a configuration field subject_type. The value of that subject_type is either public or pairwise. If the identifier algorithm is enabled, Ory Hydra will choose the right strategy automatically.

While Ory Hydra handles sub obfuscation out of the box, you may also override this value with your own obfuscated sub value by setting force_subject_identifier when accepting the login challenge in your user login app.

Using login_hint with different subject

When a user already logged in with a subject(for example user-A), and she would like to log in as another user using login_hint(for example login_hint=user-B), directly accepting the latter login request in your login provider will make hydra reply: Subject from payload doesn't match subject from previous authentication

The suggested flow is:

Check the response from GET login request, if both the subject and login_hint are NOT empty and also NOT the same user, redirect UserAgent to request_url which is appended with '?prompt=login'. This will make hydra ignore the existing authentication, and allow your login provider to log in a different subject.

For more information on prompt=login and other options, please check Authentication Request.