Resource Indicators (RFC 8707) for OAuth 2.0: A developer's guide

If you’re building apps that interact with multiple APIs using OAuth 2.0, you’ve probably wondered:

How does the authorization server know which resource server the client wants to access?

Deployment and implementation experience with OAuth 2.0 has revealed the need for clients to explicitly signal their intended resource usage to authorization servers. That’s where RFC 8707 comes in. It's a simple but powerful addition to OAuth 2.0 that lets clients explicitly tell the authorization server which specific resource they want to access.

Indicators for OAuth 2.0, as standardized in RFC 8707, provide a way to specify resource indicators so that access tokens can be restricted to particular resources.

This might sound minor, but it solves key security and usability challenges in modern multi-API environments. The authorization server needs to know about the associated resources in order to construct, encrypt, and secure tokens appropriately for each resource.

Introduction to Resource Indicators for OAuth

Resource indicators are a powerful extension to the OAuth 2.0 Authorization Framework, designed to give clients a standardized way to tell the authorization server exactly which protected resource they want to access. Traditionally, OAuth 2.0 left the destination of access tokens somewhat ambiguous, but with resource indicators, clients can now specify their target using the “resource” parameter.

When making authorization requests or token requests, the client includes the resource parameter to identify the intended protected resource. This parameter can be a uniform resource identifier (URI) that points to the specific API or service the client wants to access. By providing this information up front, the authorization server can make more informed decisions about issuing access tokens, applying the right audience restrictions, and ensuring that tokens are only valid for the requested resource.

Resource indicators can be used in various parts of the OAuth 2.0 flow, including the initial authorization request, subsequent token requests, and even within request objects. This flexibility allows clients to clearly communicate their intent when requesting access, making it easier for the authorization server to enforce security policies and prevent illegitimate access to protected resources.

In summary, resource indicators and the resource parameter bring clarity and precision to OAuth 2.0 authorization requests, helping both clients and authorization servers manage access to protected resources in a secure and interoperable way.

The Problem: ambiguous token destinations

In classic OAuth 2.0, when a client requests an access token, the authorization server doesn't know where that token will be used. Consider this scenario:

• Your company has multiple APIs: Photos API, Videos API, and Documents API
• All three are protected by the same authorization server
• A mobile app requests an access token

The question: Which API is this token for? All of them? Just one?

Without knowing the intended destination, the authorization server faces several problems:

• Security risks: Access tokens might be valid for multiple resources, leading to unintended access, and without resource identification, it becomes difficult to prevent token redirect and token misuse.
• Poor optimization: Without knowing the destination, the token might include the wrong scopes or be misconfigured
• Weak audience restrictions: Hard to prevent token theft and replay attacks. The authorization server doesn't know what audience (^aud) to set in the token. This increases the risk of token redirect, where a bearer token could be used at unintended endpoints.

When audience restrictions are weak, a bearer token is at risk of being misused across different resources or tenants. Without resource indicators, it is difficult to issue an audience restricted access token, which increases the risk of misuse. In short: The client knows where it’s going, but the authorization server doesn’t.

The solution: ^resource parameter

RFC 8707 introduces a new ^resource parameter that clients include in OAuth requests:

Clients should specify the exact resource value, such as a URI, to ensure the authorization server applies the correct audience restriction and access policies. In this example, a single resource parameter value is used to target a specific resource.

This tells the authorization server: "I want a token specifically for the Photos API." If the resource parameter is omitted, the authorization server may use a predefined default resource as the target.

Practical example

Say a client wants to access the Photos API as part of a code flow authorization request in OAuth 2.0. In this context, the client initiates the authorization process by sending a request to the authorization server, specifying the desired target service using the resource parameter. The resource parameter here indicates that the access token is being requested for the Photos API as the desired target service. Additionally, the scope parameter can be included to define the scope values, which specify the permissions and targeted resources for the access token.

Result

The authorization server issues a token that:

• Only works at ^{https://api.photos.example.com}‍
• Has ^{"aud": "https://api.photos.example.com"} in the JSON Web Token (JWT) as the ^aud claim, specifying the intended audience
• Prevents use of other APIs. Even if the token is leaked, it won’t work elsewhere

JWT Secured Authorization Request (JWT-SAR) can be used to securely convey the resource parameter during the authorization request, encapsulating resource indicators within the JWT.

Note: JSON Web Tokens are commonly used to represent access tokens with audience restrictions in OAuth 2.0.

Learn more - OAuth Tokens Explained: for M2M Authentication

Guidelines for developers

1. Use specific base URIs

Guideline: Use the most specific resource URI for the complete API or set of resources you intend to access. This ensures that access tokens are tied to the precise protected resource, including tenant identifiers if applicable, which helps enforce proper audience restrictions and mitigates cross-tenant access risks.

Examples:

• ^{https://api.example.com/}: For exclusive application on that host
• ^{https://api.example.com/app/}: For one of many apps on that host
• ^{https://apps.example.com/scim/}: For SCIM API with multiple endpoints like ^/Users, ^/Groups, ^/Schemas

In scenarios where APIs host user content, using a specific resource uri helps prevent unauthorized access by restricting tokens to the intended resource or tenant.

2. Single resource preferred

Guideline: Prefer requesting a single ^resource per token.

Why: Multiple audiences create security risks: if the Photos API gets your token, it could potentially use it to access the Videos API too. Before the standardization of the resource parameter, some clients employed proprietary parameters to signal their intended resources to the authorization server.

3. Tenant-specific access

In multi-tenant systems, tokens should not be valid across tenants. You can scope them by embedding tenant IDs in the ^resource URI:

For multi-tenant systems:

• Avoid: ^{https://api.example.com/app}
• Use: ^{https://api.example.com/tenant123/app}

Why it matters

Knowing the data contained within the access token helps ensure proper encryption and security, as it allows the authorization server to construct tokens with the appropriate characteristics for their intended use.

Additionally, signaling the token's intended recipients enables the authorization server to tailor the token for specific resources, reducing the risk of misuse and enhancing overall security.

Real-world implementation example

Here's how this looks in a typical authorization code flow:

1. The client directs the user to the authorization server with an authorization request.
2. The authorization server authenticates the user and, upon success, sends an authorization response back to the client, typically including an authorization code.
3. The client exchanges the authorization code for an access token.
4. The client uses the access token to access protected resources on the resource server.

Note: After the initial access token is obtained, the client may use a refresh token to make a subsequent access token request, allowing it to obtain new access tokens for different resources or scopes as needed. Additionally, subsequent access token requests can be made to request tokens for additional resources, depending on the application's requirements.

Step 1: Authorization request

Step 2: Token exchange

Step 3: Receive audience restricted token

The token's ^aud claim will be ^{https://api.photos.example.com}, making it useless anywhere else.

Access token request and validation

When a client needs to access a protected resource, it initiates an access token request to the authorization server, including the “resource” parameter to specify the target resource server. This resource parameter enables the authorization server to issue an access token that is tightly scoped to the requested resource, ensuring that the token can only be used with the intended resource server.

The authorization server validates the access token request by checking the requested resource against the list of resources the client is allowed to access. If the resource parameter value is valid, the authorization server issues an access token with the appropriate audience restrictions—typically by setting the “aud” claim in the token to the URI of the requested resource server. This means the access token enables access only to that specific resource, and cannot be used elsewhere, significantly reducing the risk of token misuse.

If the authorization server does not recognize or support the requested resource, it will return an “^{invalid_target}” error in the access token response. Clients should be prepared to handle this error gracefully, perhaps by prompting the user to select a different resource or by logging the error for further investigation.

In scenarios where a client requests access to multiple resources by including multiple resource parameters, the authorization server may issue an access token with multiple intended recipients. However, this approach increases security risks, as any one of the associated resource servers could potentially use the token to access the others. For this reason, it’s best practice to request access tokens for a single resource server at a time, ensuring that each token is audience-restricted to just one protected resource.

Resource indicators can be used across different OAuth 2.0 flows, such as the authorization code flow and the implicit flow. In the authorization code flow, the client includes the resource parameter in the authorization request, receives an authorization code, and then exchanges it for an access token scoped to the requested resource. In the implicit flow, the resource parameter is included directly in the authorization request, and the access token is returned immediately with the correct audience restriction.

By leveraging resource indicators in OAuth 2.0, developers can ensure that access tokens are issued with precise audience restrictions, improving the security and reliability of access token based systems—especially in environments with multiple APIs and resource servers. This approach helps prevent tokens from being used to illegitimately access resources owned by other services, and gives both clients and authorization servers greater control over how and where access tokens are used.

Where to use the ^resource parameter

The resource parameter, as defined in the OAuth specification, enables granular resource targeting by allowing clients to specify which resource server the access token is intended for. When the resource parameter contains an abstract identifier instead of a direct network address, it is the client's responsibility to ensure that the abstract identifier correctly maps to the intended network endpoint.

Error handling

If the authorization server fails to parse or accept the resource parameter—such as due to an invalid or unsupported value—it will return an error response with the error code: ^{invalid_target}. This scenario occurs when the authorization server fails to successfully interpret the resource request.doesn’t recognize or support the requested resource, it may return: Error: ^{invalid_target}

Response:

Make sure your client handles this gracefully.

Note: Error codes like ^{invalid_target} are registered in the IANA 'oauth extensions error registry' to ensure standardized error handling for OAuth extensions.

TL;DR

Final thought

Think of RFC 8707 as adding a “destination address” to OAuth tokens. It’s a small addition, but it makes a big difference when you're dealing with complex, multi-API ecosystems and want your tokens to be precise, secure, and reliable.

If your authorization server supports it, start using the ^resource parameter today.

Want to issue more secure, auditable tokens that only work for their intended API? Sign up for a Free Forever account with Scalekit and start enforcing per-resource audience restrictions out of the box. Got questions on token design or multi-API setups? Book time with our auth experts.