Simple usage example

EDIT:
Note, this PR now longer supports to configure the allowed resource indicators via the ResourceIndicatorMapper.
This is just here to document the idea.
This PR now uses a new ResourceIndicatorResolver SPI to resolve the allowed resource indicators.
There is currently no configuration / UI support to define allowed resource indicators.

Client config for myclient

ResourceIndicatorMapper for myclient contains the allow resource identifier patterns:

• foo
• bar
• baz
• https://api.acme.test/contacts

Initial Auth Request:

$ISSUER/protocol/openid-connect/auth
?client_id=myclient
&redirect_uri=...
&state=...
&response_mode=fragment
&response_type=code
&scope=openid
&nonce=...
&code_challenge=...
&code_challenge_method=S256
&resource=foo
&resource=bar

-> This restricts the current auth session to use only foo and bar as resource indicators, even if the client myclient would also allow baz.

Token Request

POST $ISSUER/protocol/openid-connect/token
grant_type=authorization_code
&client_id=myclient
&code=...
&resource=foo
...

Access Token response

Decoded Access Token with audience:

{
    ...
    aud: [foo]
}

Token Refresh Request

POST $ISSUER/protocol/openid-connect/token
Authorization: ...
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=...
&resource=bar
...

Access Token response

Decoded Access Token with audience:

{
    ...
    aud: [bar]
}

Token Refresh request with invalid resource

POST $ISSUER/protocol/openid-connect/token
Authorization: ...
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=...
&resource=gugu
...

Access Token response

Returns error

{"error":"invalid_grant","error_description":"Invalid resource"}

Haven't had a chance to look at this properly or think too much about it; but feels a bit like shoehorning/abusing protocol mappers, and not a natural way to manage resources for a client.

I think how we want to support resource indicators in Keycloak is better done first as a design/discussion rather than a PR.

Few random thoughts around this:

• We'll probably eventually need some way of querying clients given a resource indicator
• Resource indicators according to the spec must be a URI
• RFC8693 has audience and resource has optional parameters; that means it's perfectly valid to only specify the resource parts, which again means there needs to be a efficient way to lookup the client for a given resource
• Clients can have a base-url, kinda makes sense to allow configuring resources relative to that, rather than having to specify the full URI, at least in most common cases
• Not sure how this all fits together with authz services, but there's definitively some overlap between resources defined for authz and resource indicators

Hi @stianst, thanks for your helpful comments! I created the following discussion to revise the design of the resource identifiers support: #35743

In this discussion I address the concerns you mentioned.

Yes, I agree this is somewhat abusing the protocol mappers mechanism beyond token generation since it also alters the Authorization Server behaviour. However, I felt quite pragmatic to do so. However, I agree that this protocol mapper usage might be uncommon - but I have to start somewhere :O)

Also the implementation can easily changed to load the resource identifiers list from somewhere else :)

We'll probably eventually need some way of querying clients given a resource indicator

I understand the use-case. I added the point to the discussion.

Resource indicators according to the spec must be a URI

Yes, that's written in the spec and the resource examples I gave were just that, examples. Quite often Keycloak users also model resource servers / APIs as clients without flows in Keycloak to configure client specific roles etc, that can be used by other clients. In my mind resource identifiers == client_id for resource server clients, my be this is a bit off, but since client_ids are usually not URIs (at least it's not enforced) I used non-URI values as resources in the examples.
I'm fine with using URIs though which would probably support your requirement for performing lookups for clients by resource identifier.

RFC8693 has audience and resource has optional parameters; that means it's perfectly valid to only specify the resource parts, which again means there needs to be a efficient way to lookup the client for a given resource

Noted, and added to the discussion.

Clients can have a base-url, kinda makes sense to allow configuring resources relative to that, rather than having to specify the full URI, at least in most common cases

Sometimes the configured base URL might not necessarily match the resource identifiers. I'm thinking of deployments of a resource server in different environments (dev, test, qa, prod), where the base URL is different but the logical resource URIs might be the same for all environments.

Not sure how this all fits together with authz services, but there's definitively some overlap between resources defined for authz and resource indicators

I think the resources in authz services could indeed be used for this, but this would lead to a stronger coupling of the authorization services with the oauth2 functionality which might cause other problems.
Thinking about this a bit, we could use authorization resources to configure the allowed resource identifiers for a client.
This can already be implemented quite easily in this PR: I just have to adjust the new org.keycloak.protocol.oauth2.ResourceIndicators#getSupportedResourceIndicators(..) method to fetch the resource URIs from authorization services instead of the protocol mapper configuration.

We then would also need a way to let clients "opt-in" to the resource identifier support somehow, perhaps with an "advanced setting" in the client configuration: Resource Identifier Support Enabled: on/off default off.

I refactored this the resource indicator support a bit:

• Introduced OAuth2ResourceIndicatorResolver SPI to allow users to specify their own ways for validating resource identifiers (see O4) Add new dedicated SPI to validate allowed resource indicators R1 in Support for RFC 8707 OAuth2 Resource Indicators #35743)
• Removed the ability to configure supported resource indicators from the Resource Indicator Mapper

We could then add a default implementation that checks given resource identifiers based on something like a component config (config per client) etc.

I updated the PR with the a way to configure client specific resource indicators with the help of the authorization services:

User can now specify custom resources with the special type URI: urn:keycloak:oauth2:resource-indicator to denote a resource as resource indicator.

To apply the resource indicator semantics to the aud claim of a token, users need to configure a dedicated "resource-indicator-mapper",

Nice work 👏.
What happen during token exchange OIDC to OIDC client in aud claim if mapper exists and resource parameter exists as request parameter?

Thanks @cgeorgilakis for your feedback. The handling of the resource parameter is out of scope for this PR, as the resource handling for token exchange is covered by the Token Exchange rfc8693 Section 2.1 and should be covered by separate PR, e.g. #31553 or #36848.

The latest version of the PR uses authorization-services resources to describe the resource indicators that are available to a client.

Client photoz client

... with authorization enabled

Resources can be defined via Authorization / Resources in the client:

The custom type: urn:keycloak:oauth2:resource-indicator declares a resource indicator, the URI specifies the actual URI: https://api.acme.com/photos

Available resource indicators for a client can be seenin the resources tab:

A new Resource Indicators protocol mapper exposes the configured resources in the aud claim in addition to the existing linked clientIds.

Dedicated Protocol Mapper:

One can find an example realm and some http request examples with curl here: https://gist.github.com/thomasdarimont/0ccab1238d3824a84a37a16a086cf890

Unreported flaky test detected

If the flaky tests below are affected by the changes, please review and update the changes accordingly. Otherwise, a maintainer should report the flaky tests prior to merging the PR.

org.keycloak.testsuite.cluster.UserFederationInvalidationClusterTest#crudWithFailover

Keycloak CI - Clustering IT

java.lang.RuntimeException: java.lang.IllegalStateException: Keycloak unexpectedly died :(
	at org.keycloak.testsuite.arquillian.containers.KeycloakQuarkusServerDeployableContainer.start(KeycloakQuarkusServerDeployableContainer.java:71)
	at org.jboss.arquillian.container.impl.ContainerImpl.start(ContainerImpl.java:185)
	at org.jboss.arquillian.container.impl.client.container.ContainerLifecycleController$8.perform(ContainerLifecycleController.java:137)
	at org.jboss.arquillian.container.impl.client.container.ContainerLifecycleController$8.perform(ContainerLifecycleController.java:133)
...

Report flaky test

@thomasdarimont do you want to proceed with this PR or should I or someone else take over?

Thanks @stianst for picking this up again. I don't have time to work on this today / next few days. So if you want to work on this now feel free to adopt it.

Moving forward, instead of continuing this PR, we should close it and create a new one.
I think we can salvage some of the ideas from this PR and add this feature in a stepwise manner.

Some questions/thoughts regarding your proposal:

We could use something like the following:

1. Add an optional Resource URI attribute to clients
2. Get a list of all clients the client has a client role scope on
3. For each resource parameter check it matches the Resource URI of one of the clients from 2

Q1) How to configure the (primary) resource indicator for a client?
For 1. Would you like to use a new client attribute or a dedicated property for this?
I initially thought of a client attribute, but the (primary) resource indicator must be unique among all clients in a realm. I'm not sure if we already do this somewhere, but we may need to add a new field to the client JPA entity to store the resource indicator URI, making it easier to ensure uniqueness at the database level.
We can then expose this as a dedicated client property (more work, which might require admin API consumer updates) or pass it through the attributes (a hacky solution, but it would not break admin API consumers).

With this, we would only allow one (primary?) resource indicator per client for now, which can be used as an alias to target this specific client/resource server via the resource parameter.
However, later we may need to support additional (sub-resource) indicators per resource server (e.g., if those clients represent an API gateway or another collection of resource servers). Those additional resource indicators might come from another source, but we can add support for that later. In my PR, I introduced an OAuth2ResourceIndicatorResolver SPI for this.

Q2) Mechanism to select the eligible resource indicators for a given client
Do you mean to use the client role scope for selecting other related clients and derive the resource indicator from that?
Doesn't this require clients to specify at least one client role for selection?

To verify this:
Imagine we have a photos-app OIDC client that can obtain tokens and two APIs that the photos-app should be able to access: photos-api, accounts-api.
We create photos-api and accounts-api clients as a resource server (all flows disabled). For both, we specify resource indicators, such as https://accounts.acme.test and https://photos.acme.test.
We now want to express that a photos-app token should be able to access photoz-api and accounts-api via the resource parameter in the authorization / token request. With your method, I need to define at least one role in the photoz-api and accounts-api clients to be able to add them to the client role scope selection of the photoz-app. So I create a "dummy" role like access for photos-api, accounts-api, and add them to the client role scope of the photos-app.

Is this what you had in mind?

Q3) How to match a client via resource indicator to the requested resource parameter?

Using the client role scope to select clients and derive the eligible resource indicators is a simple solution. Still, it requires additional configuration (role definitions) and is also limited to just one indicator (which is fine for now). However, I wonder if we should make this pluggable from the start and use a new SPI to derive eligible resource indicators for a client with it (a default implementation could use the client role scope for this purpose).
I believe the clients selected need to have a resource indicator URI configured to be considered for matching the resource parameter. We could filter out clients without a resource indicator.

Q4) How do we specify whether a client supports the resource parameter or not?
Is this enabled for all clients automatically? In my PR, I added a dedicated ResourceIndicatorMapper OIDC protocol mapper that admins could add to their clients to explicitly enable the handling of resource parameters, which added eligible resource indicator values to the aud claim after some filtering.

Q5) When and where do we determine the eligible resource indicators?
In my PR, the set of eligible resource indicators was determined during authorization request handling and subsequently filtered based on the actual token request, allowing users to request a subset of the initially requested resources.

Thanks @stianst for picking this up again. I don't have time to work on this today / next few days. So if you want to work on this now feel free to adopt it.

I don't either right now, but want to make sure we get this sorted and included in 26.5. We can work together on this in some form :)

Moving forward, instead of continuing this PR, we should close it and create a new one. I think we can salvage some of the ideas from this PR and add this feature in a stepwise manner.

Some questions/thoughts regarding your proposal:

We could use something like the following:

1. Add an optional Resource URI attribute to clients
2. Get a list of all clients the client has a client role scope on
3. For each resource parameter check it matches the Resource URI of one of the clients from 2

Q1) How to configure the (primary) resource indicator for a client? For 1. Would you like to use a new client attribute or a dedicated property for this? I initially thought of a client attribute, but the (primary) resource indicator must be unique among all clients in a realm. I'm not sure if we already do this somewhere, but we may need to add a new field to the client JPA entity to store the resource indicator URI, making it easier to ensure uniqueness at the database level. We can then expose this as a dedicated client property (more work, which might require admin API consumer updates) or pass it through the attributes (a hacky solution, but it would not break admin API consumers).

With this, we would only allow one (primary?) resource indicator per client for now, which can be used as an alias to target this specific client/resource server via the resource parameter. However, later we may need to support additional (sub-resource) indicators per resource server (e.g., if those clients represent an API gateway or another collection of resource servers). Those additional resource indicators might come from another source, but we can add support for that later. In my PR, I introduced an OAuth2ResourceIndicatorResolver SPI for this.

I'm not actually convinced it has to be unique, or at least not enforced at the DB level. Only thing that would happen if two services are registered with the same resource URI is that a client would pick one; or if it only has a relationship with one then it will ignore the other.

If there is a duplicated; we don't know if it's the first or the second that is using the wrong resource URI; or maybe actually in fact there is two clients for a given service, and it uses them for different purposes.

With what I'm proposing below when clients and services are linked this also becomes less of an issue.

Q2) Mechanism to select the eligible resource indicators for a given client Do you mean to use the client role scope for selecting other related clients and derive the resource indicator from that? Doesn't this require clients to specify at least one client role for selection?

To verify this: Imagine we have a photos-app OIDC client that can obtain tokens and two APIs that the photos-app should be able to access: photos-api, accounts-api. We create photos-api and accounts-api clients as a resource server (all flows disabled). For both, we specify resource indicators, such as https://accounts.acme.test and https://photos.acme.test. We now want to express that a photos-app token should be able to access photoz-api and accounts-api via the resource parameter in the authorization / token request. With your method, I need to define at least one role in the photoz-api and accounts-api clients to be able to add them to the client role scope selection of the photoz-app. So I create a "dummy" role like access for photos-api, accounts-api, and add them to the client role scope of the photos-app.

Is this what you had in mind?

Something along those lines; let's continue the discussion around that in #43179

For resource indicators let's assume there is a way to list all clients a client can connect to, so that we have a limited set of clients to look for matching resource indicators.

Q3) How to match a client via resource indicator to the requested resource parameter?

Using the client role scope to select clients and derive the eligible resource indicators is a simple solution. Still, it requires additional configuration (role definitions) and is also limited to just one indicator (which is fine for now). However, I wonder if we should make this pluggable from the start and use a new SPI to derive eligible resource indicators for a client with it (a default implementation could use the client role scope for this purpose). I believe the clients selected need to have a resource indicator URI configured to be considered for matching the resource parameter. We could filter out clients without a resource indicator.

I'd start without it being pluggable - it's just less code and things to test; however, don't have any issues with a quick follow-up that makes it pluggable.

Q4) How do we specify whether a client supports the resource parameter or not? Is this enabled for all clients automatically? In my PR, I added a dedicated ResourceIndicatorMapper OIDC protocol mapper that admins could add to their clients to explicitly enable the handling of resource parameters, which added eligible resource indicator values to the aud claim after some filtering.

Don't think we need that if we have what I talk about above; it's basically supported as long as a client is connected to a different client that has a resource-uri configured

Q5) When and where do we determine the eligible resource indicators? In my PR, the set of eligible resource indicators was determined during authorization request handling and subsequently filtered based on the actual token request, allowing users to request a subset of the initially requested resources.

Not really following what you are saying here. What is an eligible resource indicator? How would a user request a subset? Are you talking about optional consents or something?

Yes let's do this together :) I can send a new PR with just the minimal bits to support a new "Root Resource URI" client attribute for clients. I guess this setting should be placed in the "Advanced Settings" somehow and be empty by default.