What Is Token Audience In OAuth?

The audience claim specifies the intended recipient of a security token. This is a crucial concept in OpenID Connect, a delegated authentication protocol often used to build Single-Sign-On (SSO) systems. In such systems, a single authentication event allows a user to access multiple services. Each service obtains tokens signed by the same authority, which are inherently valid.

However, if every service were to trust all tokens indiscriminately, a user authenticated to one service could gain access to others, which may be a significant security risk. The audience claim prevents this by ensuring a token is only accepted by its designated recipient.

Use of the audience claim is specified in a number of RFCs, including RFC7519 section 4.1.3.:

The “aud” (audience) claim identifies the recipients that the JWT is intended for. Each principal intended to process the JWT MUST identify itself with a value in the audience claim. If the principal processing the claim does not identify itself with a value in the “aud” claim when this claim is present, then the JWT MUST be rejected. In the general case, the “aud” value is an array of case- sensitive strings, each containing a StringOrURI value. In the special case when the JWT has one audience, the “aud” value MAY be a single case-sensitive string containing a StringOrURI value. The interpretation of audience values is generally application specific. Use of this claim is OPTIONAL.

Understanding Invalid Audience Errors link

You may have encountered error messages such as:

• Access token validation failure. Invalid audience.
• error="invalid_token",error_description="The audience '<client id>' is invalid"

While these errors might initially suggest a faulty OAuth 2.0 implementation or an invalid application configuration, that is rarely the case. To understand why they occur, you must first grasp the core concept of audience in OAuth 2.0. To illustrate, consider the following use case:

A Use-Case link

Consider a common scenario: a business offers several capabilities that are exposed through multiple channels, such as websites or internal applications. These applications are secured by a separate authorization server, which eliminates the need for a monolithic landscape:

• An authorization server
• An external-facing web application
• An internal-facing web application
• Various internal applications that automate business capabilities

Commonly, businesses have capabilities such as:

• Human Resource Management
• Order Management
• Customer Relationship Management
• Etc.

These business capabilities are used to automate processes. For example, to allow customers to check their order status.

To display the order status in the customer portal, the portal needs access to data from the Order Management system. At the same time, various back-office applications may need to access and update those same resources in order to automate background processes involved in order management.

However, a back-office application may need broad access across multiple internal systems. In contrast, a consumer-facing application typically requires much more restricted access.

For example, while back-office software might legitimately interact with HR, finance, and order management systems, a customer-facing portal should be tightly constrained to only the resources relevant to the customer experience. After all, a customer has no business accessing the HR system.

This is exactly the problem that the aud (audience) claim is designed to solve.

• In this example, the Customer Portal, the Backoffice Portal, the Order Status API, and the Human Resource API are all considered clients.
• Each client has an audience: a list of clients or services that are allowed to consume the tokens issued for it.
• An audience can also include external APIs.

Configuring an audience in an Identity Provider alone has no effect. The audience must be configured in both the client and the Identity Provider:

• The Identity Provider includes the list of allowed audiences in the tokens it issues.
• The client must be configured to validate that any token it receives contains the correct audience.

How To Use Audience link

The Audience claim is used to specify the clients that are permitted to use a token. In this example, the correct audience values would be:

This configuration ensures that a token issued to the Customer-Portal API will be rejected by the Human Resource API because the latter is not included in its list of allowed audiences.

Audience vs. Scope link

Both audience and scope are mechanisms for defining a token’s permissions, but they originated from different contexts and serve distinct, though related, purposes. Understanding their history helps clarify the distinction.

OAuth came first, and its primary purpose was authorization. At this time, tokens were often random, opaque strings that required a backend call to validate. To define what a token was authorized to do, the concept of scope was introduced. Scopes are typically granular and specify the types of actions a client can perform, such as read, write, or delete, or access to specific resource types like email or calendar.

OpenID Connect (OIDC) was built on top of OAuth 2.0 to add an authentication layer. OIDC introduced the idea of the ID token, which is a stateless JSON Web Token (JWT) containing user information (claims). With OIDC, scopes took on a dual role. While they still restrict access to resources, they are also used to request specific user claims. For instance, a client requests the openid scope to get the required sub (subject) claim for authentication, and the profile scope to receive additional profile claims like name or picture.

The audience claim (or aud claim) was introduced with JWTs to specify the intended recipient of the token. It answers the question, “Who is this token for?” The audience is a string or an array of strings that represents the client or service that should accept the token. If a token is sent to a service whose identifier is not in the aud claim, the service should reject it. This is a powerful security mechanism that prevents a token from being used by an unintended party. In short, audience restricts who can use the token, while scope restricts what the token can be used for.

The client_id, Aud- and the Azp Claim link

As with many concepts in OpenID, a claim is used for a given feature. But in most cases, just a single claim is not enough to make the functionality work. Audience is part of a bigger picture that includes the use of the client_id, the aud, and the azp claim.

• When a client is issued a token, it can always use that token to access itself. Therefore, a client is always its own audience. If a client’s tokens are intended to be used only by itself, the aud claim may be omitted.
• token may specify multiple audiences. However, when a token has multiple audiences, it can be unclear which client originally requested it. To clarify this, tokens with multiple audiences include an additional claim: the azp (authorized party) claim. This claim contains the client_id of the client that requested the token.

Configuring the Audience Claim link

The technical task of getting authorization to work is fairly straightforward, but the concept of an audience can be quite abstract.

It’s more important to have a clear understanding of what clients should have access to what resources, and why, than it is to simply configure the audience to get it to work. Without this, your configuration may not align with your security needs.

To configure your audience claims, we recommend you follow these steps:

• Audit your clients: Create a list of all your clients and give them concise, unambiguous names.
• Define access: Clearly determine which clients need to access specific resources. This is a critical step that should be based on your application’s security requirements.
• Configure clients: Apply the access rules you’ve defined to each client’s configuration.
• Implement validation: Ensure all clients are configured to validate at least the audience and issuer claims. This validates that the authorization token was issued for the intended recipient and by a trusted server.

Summary link

When securing applications with OAuth, it is important to understand who is using each application and what permissions or authorization scopes are appropriate.

This authorization model can be enforced using the aud claim and OAuth scopes.