Understanding how the "audience" concept actually works

[matt.hintzke]

I am trying my best to fully understand the relationship between Applications, APIs, Audience, and Scopes within the world of Auth0 and oauth 2.0.

I think the best way to illustrate the relationships is through an example. Let’s say I have a service topology for the following system

1 Application to many APIs

www.foo.com is the Application that services a SPA and is backed by 2 APIs, bar.foo.com and baz.foo.com

In this scenario, I thought I would create a single Auth0 application, and 2 APIs, each with their own audience. However, it appears that Auth0 (and oauth 2.0) only allows a single audience to be set during a flow, so an Application has a 1-1 mapping to an API.

The problem I have with this is you can go to an API in the Auth0 portal and go to the Machine to Machine Applications and Authorize the 1 Application. It seems confusing to be able to allow somethign called an API to Authorize multiple Applications or many APIs Authorize the same Application, yet the “audience” can only be set to a single URI.

If I were to define the terms Application and API myself, I would probably define them as follows:

Application - the logical authentication boundary in which a user’s authentication context can span.

API - like an Application, an API is not a single physical instance of an API, but a logical grouping of services that present APIs that can be authenticated against using a single authentication context. This means my 2 APIs from my scenario would both really use the same API and therefore have the same audience value. This audience value wouldn’t be bar.foo.com OR baz.foo.com, but rather something like api.foo.com which doesn’t actually exist, but is just an “identifier” of my logical grouping of API services.

By the above, I basically mean that an Application isn’t a physical app, but really any number of apps that can be treated as a single authentication context. This means that a user can authenticate against the Application and bounce around to the different physical apps (nodejs, .NET Core, rails, etc) and hit different APIs all without having to re-login.

With that said, what is the point in validating the audiences? What is a scenario where you would have different Audiences (e.g. different Application with a different ClientID, ClientSecret, etc), but that Audience needs to be validated? If the Audience is different than isn’t the Application different as well? And if the Application is different that means the ClientId is different as well, so why not just validate against the ClientId?

I’m failing to see the purpose in having Audience validation and would love to hear about an example/scenario where this would be useful. E.g. where the signed token verification passes, but Audience validation fails.

P.S. I did try reading the spec, but I don’t see how it relates to the terminology Auth0 uses to describe these concepts.

Thanks!

[lily.wisecarver]

Hi @matt.hintzke,

Thank you for reaching out to us!

I think the easiest way to understand these relationships is by understanding the Access Tokens. Access Tokens are used in token-based authentication to allow an application to access an API. The application receives an Access Token after a user successfully authenticates and authorizes access, then passes the Access Token as a credential when it calls the target API. The passed token informs the API that the bearer of the token has been authorized to access the API and perform specific actions specified by the scope that was granted during authorization. See: Access Tokens

Auth0 supports only one resource identifier (“audience”) per access token, but an access token can carry multiple scopes (and custom claims). If an app requires access to multiple resource servers, the app will need to ask for different access tokens (or create one global resource server with multiple scopes).

Applications can request an ID Token (where the audience is the web app itself, and carries information about the user), but can also request an access token where the audience is the resource server, by including the “audience” parameter in the request.

Let’s say that you didn’t want to have all your APIs/Apps share the same “Auth0 Application”, as proposed in the api-auth0 documentation. Also, if you wanted each to be its own Auth0 Application.

You can use Auth0 to request both:

ID token, with information about the user, where the audience is the client app itself.
Access token, with maybe permissions, scopes, where the audience is the backend API (“resource server”). This is done by adding the “audience=xxxx” parameter in the authorize request.
The app should use the ID token to get information about the user, like name, email, roles and so on.

The app should use the Access token to make requests to the resource server.

In summary, Auth0 provides the 2 tokens the id token and access token which both are in JWT format. The id token will stay in the application and the access token will be used to make requests to its unique resource server. We usually recommend to model a single conceptual resource server (taking Google as an example, that would be the “Google API”) with different scopes to model different access permissions (e.g. “read:email”, “read:contacts”, “write:files”, and so on.)
But you can still model different APIs (resource servers) in Auth0, just keep in mind that applications will have to request multiple tokens if they need to access multiple APIs.

Please let me know if this makes sense and help you understand the relationships.

[udaykumar.kr1]

Hi @matt.hintzke,

Could you point me to the sample SPA (react) code to generate 2 access tokens for 2 different audiences ?
We are building microservices architecture where we have 7 audiences and each audience (maps to separate resource server) needs to configured with different permissions in auth0 and should have separate access token for web client to invoke api’s on those resource servers.

We know that we have to pass a audience to generate access token which we are already doing it. How to get separate access token based on separate audience is the question ?

Please reply asap, as it is bit urgent for our application development perspective.

Regards,
Uday

[jani.krunniniva]

I would like to see also example how to use multiple access tokens

-jani-

[lily.wisecarver]

Hi,

Sorry for the huge delay.

Please check this related post. Let me know if you have any more questions!

[James.Morrison]

As referenced in the post above:

@jmangelo

You can indeed authorize a second time to use a different audience and as a consequence obtain an access token suitable to another API, however, you mention that one of the two audiences being used is the Management API. In this situation I would consider the following, only request an audience targeting your API and obtain access tokens meant for the Management API only through a client credentials flow that would be performed by your API/ Node server.

The above would mean that any access to the Management API would be brokered through your own API and the client application would only manage access tokens associated with your own API (the Management API access tokens would only be available with the server-side of your API).

In addition, the scope openid profile grants access to user profile information, but email is not included in the set of properties associated with the profile scope. If you also want to have access to the email address, you should also include the email scope. In relation to user metadata, since this is not standard information you’ll need to use custom claims if you want to include it in the issued ID token. Finally, in order for the access tokens issued to your API to also be usable in the /userinfo endpoint you need to ensure that your API is configured to use RS256 as the signing method.

We are in the process of building out a supporting FAQ for this topic and will share as it becomes available!

[tyf]

Relevant FAQs for future reference

What is the Audience?

Question: What is the Audience? Answer: The audience parameter exists as part of the OAuth2.0 protocol. You can read more information from the specification here. What is it? The audience (presented as the aud claim in the access token) defines the intended consumer of the token. This is typically the resource server (API, in the dashboard) that a client (Application) would like to access. It can be added to the request to authorize i.e. audience: 'https://test-api' Here is an example where …

How do I specify multiple audiences?

Question: How do I specify multiple audiences? Answer: This is not supported. If you have a microservice architecture or something similar, you should use scopes to distinguish between them in combination with a single audience. Video Tutorial [Managing Multiple Audiences Using a Logical API -- Auth0 Community Response Series]