OAuth2 "resource" Query Parameter

The "resource" query parameter is an optional parameter in OAuth2 used to specify the target resource server for which the access token is intended.

Why It Is Used

  1. Audience Restriction -
    • It specifies the audience for the access token.
    • Ensures that the token can only be used at the designated resource server.
    • Prevents misuse of tokens at unintended endpoints.
  2. Multi-Resource Scenarios -
    • In multi-tenant or multi-resource systems, it specifies which API or service the client wants to access.
    • Example: A single authorization server managing access tokens for multiple APIs.
  3. Optimized Token Scope -
    • The authorization server can issue a token scoped specifically for the requested resource.
    • This minimizes token privileges, enhancing security.

Is It Required?

  • No, it is not required by the OAuth2 specification.
  • It is used by specific OAuth2 providers, particularly Azure Active Directory (AAD) and other Microsoft Identity Platform services.
  • When used, it is required by that provider to properly route and validate tokens.

Example Usage

https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=YOUR_CLIENT_ID&
response_type=code&
redirect_uri=https://yourapp.com/callback&
resource=https://graph.microsoft.com&
scope=openid+profile&
state=RANDOM_STATE
  • In this example, the token is intended for Microsoft Graph API ("https://graph.microsoft.com").

Which Providers Use It?

  • Microsoft Azure Active Directory (AAD) uses "resource" to specify which API the token is for.
  • Other providers like Google, Facebook, and GitHub generally use "scope" to determine the target resource and do not require "resource".

Difference from "scope"

  • "scope" - Specifies permissions or actions the client wants to perform (e.g., read, write).
  • "resource" - Specifies the target audience or API endpoint the token is meant for.

Summary

  • "resource" is optional but required by specific providers (like Azure AD).
  • It specifies the target resource server or audience.
  • Not part of the OAuth2 core spec, but useful for multi-resource environments.