2. Resource Parameter
2. Resource Parameter
In requests to the authorization server, a client MAY indicate the protected resource (a.k.a. resource server, application, API, etc.) to which it is requesting access by including the following parameter in the request.
resource
: Indicates the target service or resource to which access is being requested. Its value MUST be an absolute URI, as specified by Section 4.3 of [RFC3986]. The URI MUST NOT include a fragment component. It SHOULD NOT include a query component, but it is recognized that there are cases that make a query component a useful and necessary part of the resource parameter, such as when one or more query parameters are used to scope requests to an application. The resource parameter URI value is an identifier representing the identity of the resource, which MAY be a locator that corresponds to a network-addressable location where the target resource is hosted. Multiple resource parameters MAY be used to indicate that the requested token is intended to be used at multiple resources.
The parameter value identifies a resource to which the client is requesting access. The parameter can carry the location of a protected resource, typically as an https URL or a more abstract identifier. This enables the authorization server to apply policy as appropriate for the resource, such as determining the type and content of tokens to be issued, if and how tokens are encrypted, and applying appropriate audience restrictions.
The client SHOULD provide the most specific URI that it can for the complete API or set of resources it intends to access. In practice, a client will know a base URI for the application or resource that it interacts with, which is appropriate to use as the value of the resource parameter. The client SHOULD use the base URI of the API as the resource parameter value unless specific knowledge of the resource dictates otherwise. For example, the value https://api.example.com/ would be used for a resource that is the exclusive application on that host; however, if the resource is one of many applications on that host, something like https://api.example.com/app/ would be used as a more specific value. Another example is when an API has multiple endpoints, e.g., when System for Cross-domain Identity Management (SCIM) [RFC7644] has endpoints such as https://apps.example.com/scim/Users, https://apps.example.com/scim/Groups, and https://apps.example.com/scim/Schemas. The client would use https://apps.example.com/scim/ as the resource so that the issued access token is valid for all the endpoints of the SCIM API.
The following error code is provided for an authorization server to indicate problems with the requested resource(s) in response to an authorization request or access token request. It can also be used to inform the client that it has requested an invalid combination of resource and scope.
invalid_target
: The requested resource is invalid, missing, unknown, or malformed.
The authorization server SHOULD audience-restrict issued access tokens to the resource(s) indicated by the resource parameter. Audience restrictions can be communicated in JSON Web Tokens [RFC7519] with the aud claim and the top-level member of the same name provides the audience restriction information in a Token Introspection [RFC7662] response. The authorization server may use the exact resource value as the audience or it may map from that value to a more general URI or abstract identifier for the given resource.