Merge pull request #799 from DuendeSoftware/wca/enforcing-resource-isolation

Clarify what RequireResourceIndicator actually does

Author: wcabus

src/content/docs/identityserver/fundamentals/resources/isolation.md

@@ -14,7 +14,9 @@ redirect_from:
 This is an Enterprise Edition feature.
 :::
 
-OAuth itself only knows about scopes - the (API) resource concept does not exist from a pure protocol point of view. This means that all the requested scope and audience combination get merged into a single access token. This has a couple of downsides, e.g.
+OAuth itself only knows about scopes - the (API) resource concept does not exist from a pure protocol point of view. 
+This means that all the requested scope and audience combination get merged into a single access token.
+This has a couple of downsides:
 
 * tokens can become very powerful (and big)
     * if such a token leaks, it allows access to multiple resources
@@ -23,13 +25,15 @@ OAuth itself only knows about scopes - the (API) resource concept does not exist
     * resource specific processing like signing or encryption algorithms conflict
 * without sender-constraints, a resource could potentially re-use (or abuse) a token to call another contained resource directly
 
-To solve this problem [RFC 8707](https://tools.ietf.org/html/rfc8707) adds another request parameter for the authorize and token endpoint called `resource`. This allows requesting a token for a specific resource (in other words - making sure the audience claim has a single value only, and all scopes belong to that single resource).
+To solve this problem [RFC 8707](https://tools.ietf.org/html/rfc8707) adds another request parameter for the authorize and token endpoint called `resource`. 
+This allows requesting a token for a specific resource (in other words - making sure the audience claim has a single 
+value only, and all scopes belong to that single resource).
 
 ## Using The Resource Parameter
 
 Let's assume you have the following resource design and that the client is allowed access to all scopes:
 
-```cs
+```csharp title="ApiResources.cs"
 var resources = new[]
 {
     new ApiResource("urn:invoices")
@@ -44,10 +48,12 @@ var resources = new[]
 };
 ```
 
-If the client would request a token for the `read` scope, the resulting access token would contain the audience of both the invoice and the products API and thus be accepted at both APIs.
+If the client would request a token for the `read` scope, the resulting access token would contain the audience of both
+the invoice and the products API and thus be accepted at both APIs.
 
 ### Machine to Machine Scenarios
-If the client in addition passes the `resource` parameter specifying the name of the resource where it wants to use the access token, the token engine can `down-scope` the resulting access token to the single resource, e.g.:
+If the client in addition passes the `resource` parameter specifying the name of the resource where it wants to use 
+the access token, the token engine can `down-scope` the resulting access token to the single resource, e.g.:
 
 ```text
 POST /token
@@ -112,7 +118,8 @@ redirect_uri=...&
 resource=urn:invoices
 ```
 
-Which will return an access token for the invoices API and a refresh token. If you want to also retrieve the access token for the products API, you use the refresh token and make another roundtrip to the token endpoint.
+This will return an access token for the invoices API and a refresh token. If you want to also retrieve the access token
+for the products API, you use the refresh token and make another roundtrip to the token endpoint.
 
 ```text
 POST /token
@@ -125,24 +132,41 @@ refresh_token=...&
 resource=urn:products
 ```
 
-The end-result will be that the client has two access tokens - one for each resource and can manage their lifetime via the  refresh token.
+The end-result will be that the client has two access tokens - one for each resource and can manage their lifetime via the refresh token.
 
 ## Enforcing Resource Isolation
-All examples so far used the `resource` parameter optionally. If you have API resources, where you want to make sure they are not sharing access tokens with other resources, you can enforce the resource indicator, e.g.:
+All examples so far used the `resource` parameter optionally. If you have API resources, where you want to make sure 
+they are not sharing access tokens with other resources, you can enforce the resource indicator, e.g.:
 
-```cs
+```csharp title="ApiResources.cs" {6,12}
 var resources = new[]
 {
     new ApiResource("urn:invoices")
     {
         Scopes = { "read", "write" },
-
         RequireResourceIndicator = true
     },
 
     new ApiResource("urn:products")
     {
-        Scopes = { "read", "write" }
+        Scopes = { "read", "write" },
+        RequireResourceIndicator = true
     }
 };
-```
+```
+
+The `RequireResourceIndicator` property **does not** mean that clients are forced to send the `resource` parameter when
+they request scopes associated with the API resource. You can still request those scopes without setting the `resource` 
+parameter (or including the resource), and IdentityServer will issue a token as long as the client is allowed to request 
+the scopes.
+
+Instead, `RequireResourceIndicator` controls **when** the resource's URI is included in the **audience claim** (`aud`) 
+of the issued access token.
+
+* When `RequireResourceIndicator` is `false` (the default):
+  IdentityServer **automatically includes** the API's resource URI in the token's audience if any of the resource's scopes
+  are requested, even if the `resource` parameter was not sent in the request or didn't contain the resource URI.
+* When `RequireResourceIndicator` is `true`:
+  The API's resource URI will **only** be included in the audience **if the client explicitly includes the resource URI** 
+  via the `resource` parameter when requesting the token.
+