Feature Spotlight: Resource Isolation

This is the second part in a series of posts covering new (and old) features of Duende IdentityServer. These posts are not supposed to be super technical deep dives (that’s what documentation is for), but rather explain the feature at a more conceptual level, why it exists, and why it might useful for you.

The Problem

OAuth itself only knows about scopes - the (API) resource concept we use in Duende IdentityServer 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.

tokens can become very powerful (and big). If such a token leaks, it allows access to multiple resources
resources within that single token might have conflicting settings, e.g. contained claims or cryptographic algorithms
without sender-constraints, a resource could potentially re-use (or abuse) a token to call another contained resource directly

The Solution

To solve this problem RFC 8707 adds an additional request parameter for the authorize and token endpoint called resource. This allows requesting a token for a specific resource - or in other words - making sure the audience claim has a single value only.

Using the resource parameter

Let’s assume you have the following resource design and that the client is allowed access to all scopes:

var resources = new[]
{
    new ApiResource("urn:invoices")
    {
        Scopes = { "read", "write" }
    },

    new ApiResource("urn:products")
    {
        Scopes = { "read", "write" }
    }
};

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 endpoints.

{
    "aud": [ "urn:invoice", "urn:products" ],
    "scope": "read",
    "client_id": "client"
}

Simple example

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.:

POST /token

grant_type=client_credentials&
client_id=client&
client_secret=...&

scope=read&
resource=urn:invoices

Thus resulting in an access token like this (some details omitted):

{
    "aud": [ "urn:invoice" ],
    "scope": "read",
    "client_id": "client"
}

Requesting access to multiple resources

It is also possible to request access to multiple resources. This will result in multiple access tokens - one for each requested resource.

This journey starts at the authorize endpoint:

GET /authorize?client_id=client&response_type=code&scope=read offline_access&resource=urn:invoices&resource=urn:products

When you redeem the code, you need to specify for which resource you want to have an access token, e.g.:

POST /token

grant_type=authorization_code&
client_id=client&
client_secret=...&
authorization_code=...&
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 round-trip to the token endpoint.

POST /token

grant_type=refresh_token&
client_id=client&
client_secret=...&
refresh_token=...&

resource=urn:products

The end-result will be that the client has two access tokens - one for each resource.

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.:

var resources = new[]
{
    new ApiResource("urn:invoices")
    {
        Scopes = { "read", "write" },

        RequireResourceIndicator = true
    },

    new ApiResource("urn:products")
    {
        Scopes = { "read", "write" }
    }
};

Summary

Resource isolation is an additional tool you can use to organize your API surface. It allows creating less-powerful tokens and enforces that certain APIs don’t share access tokens with others.

Resource isolation is included in Duende IdentityServer v5 starting with Preview 3 and is a feature of the Enterprise Edition. Please give it a try and give us feedback via our issue tracker.