Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
003b1cf
Method for optional enforcement of resource attribute
PeterBolha Oct 11, 2023
a0f44f0
Replace wrapper with direct check in validator
PeterBolha Oct 24, 2023
c96e018
Add policy hook for client credentials grant
lionick Aug 12, 2024
c3f6d1a
Restructure and cleanup
c00kiemon5ter Sep 27, 2024
a9b63f0
Filter scopes for client credentials grant
c00kiemon5ter Sep 27, 2024
d18a8a4
Add denylist for redirect URI schemes
Oct 17, 2024
504d5ae
Support resource indicators (RFC 8707)
lionick Nov 16, 2026
e2f02fe
Add audience policies, fix tests broken by resource indicators/audien…
lionick Nov 16, 2026
2759f7a
Add client_id to the audience policy interface
c00kiemon5ter Apr 1, 2025
640c394
Handle explicit None values in add_claims configuration
lionick Nov 16, 2026
caeba8f
Keep client_id through id_token and introspection for audience enforc…
lionick Nov 16, 2026
7844584
Run the client_id presence check unconditionally in client authentica…
lionick Feb 11, 2025
d267dab
fix(client-credentials): default aud per RFC 9068 when no resource in…
lionick Nov 16, 2026
8abed1c
test(client-credentials): use consistent underscored client ids
lionick Nov 16, 2026
e3a0607
test(client-credentials): document config and expected outcome per test
lionick Nov 16, 2026
9e4fde5
fix(token-exchange): default aud per RFC 9068, and stop discarding it
lionick Nov 16, 2026
0e786a9
style: strip trailing whitespace in token exchange tests
lionick Nov 16, 2026
ab37e5e
doc: document and fix resource_indicators / audience_policies docs
lionick Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions doc/server/contents/clients.rst
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,46 @@ E.g.::
id_token: True, # Map the requested scopes to claims and add them to the id token
}

-------------------
resource_indicators
-------------------

Overrides, for this client only, the endpoint-level ``resource_indicators``
policy described in the server configuration documentation. It takes a
``policy`` dict directly - the same shape used for the endpoint-level
default::

endpoint_context.cdb["client_1"]["resource_indicators"] = {
"policy": {
"function": validate_resource_indicators_policy,
"kwargs": {"resource_servers_per_client": ["RESOURCE_1"]},
},
}

This entry alone has no effect: it is only consulted once resource
indicators are turned on for the endpoint in question, which is a
separate, server-wide setting - not something configured per client, and
not something this client (or its administrator) sets. The deployment
operator enables it once, in the OP's own endpoint configuration
(``enable_resource_indicators``, under that endpoint's ``kwargs`` - see
the server configuration documentation)::

"endpoint": {
"token": {
"path": "token",
"class": Token,
"kwargs": {
"enable_resource_indicators": True,
},
}
}

If this client requests no resource, or resource indicators aren't
enabled for the endpoint, the issued access token's ``aud`` still
defaults to this client's own ``client_id`` - this entry only changes
what the client may additionally be issued a token for, once resource
indicators are on.

-----------------
token_usage_rules
-----------------
Expand Down
217 changes: 169 additions & 48 deletions doc/server/contents/conf.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1017,66 +1017,187 @@ idpyoidc\.server\.configure module
:show-inheritance:


==============
====================
Resource Indicators
==============
There are two possible ways to configure Resource Indicators in OIDC-OP, globally and per-client.
For the first case the configuration is passed in the Authorization or Access Token endpoint arguments throught the
`resource_indicators` dictionary.

If present, the resource indicators configuration should contain a `policy` dictionary
that defines the behaviour of the specific endpoint. The policy
is mapped to a dictionary with the keys `callable` (mandatory), which must be a
python callable or a string that represents the path to a python callable, and
`kwargs` (optional), which must be a dict of key-value arguments that will be
passed to the callable.

The resource indicators configuration may also contain a `resource_servers_per_client`
dictionary that defines a mapping between oidc-op registered clients with key the equivalent `client id` and resources to whom this client
is eligible to request access.

"resource_indicators":{
"policy": {
"callable": validate_authorization_resource_indicators_policy,
"kwargs": {
"resource_servers_per_client": {
"CLIENT_1": ["RESOURCE_1"],
"CLIENT_2": ["RESOURCE_1", "RESOURCE_2"]
====================

There are two ways to configure resource indicators: per-endpoint (the
default for every client) and per-client (overriding that default for
one client). They apply to the authorization, token
(``authorization_code``, ``client_credentials``, ``token_exchange``) and
introspection endpoints.

---------------------------
enable_resource_indicators
---------------------------

Each endpoint's ``kwargs`` accepts an ``enable_resource_indicators``
boolean, default ``False``. Without it, any ``resource`` parameter a
client sends is ignored outright - never validated, never reflected in
the issued token - and the token's ``aud`` falls back to the default
described below, exactly as if the client had sent no ``resource`` at
all.

-------------------
resource_indicators
-------------------

The endpoint-level default policy, used for any client with no
``resource_indicators`` entry of its own. ``policy`` maps to a dict with
``function`` (mandatory - a callable, or an importable dotted-path
string) and ``kwargs`` (optional)::

"resource_indicators": {
"policy": {
"function": validate_resource_indicators_policy,
"kwargs": {
"resource_servers_per_client": {
"CLIENT_1": ["RESOURCE_1"],
"CLIENT_2": ["RESOURCE_1", "RESOURCE_2"],
},
},
},
},
},
}

For the per-client configuration a similar configuration scheme should be present in the client's
metadata under the `resource_indicators` key with slight difference. The `policy` mapping should be set a value for a
key `authorization_code` or `access_token` in order to indicate the endpoint that this resource indicators policy is reffered to.
In addition, the `resource_servers_per_client` value is a list of the permitted resources.
``resource_servers_per_client`` is either a flat list of resource
identifiers valid for every client, or a ``{client_id: [resource, ...]}``
mapping for per-client restriction. A client may always additionally
request itself as a resource, even without an explicit entry. If any
requested resource falls outside the permitted set, the entire request
is rejected with ``invalid_target`` - never narrowed to the valid subset.

For example::
--------------------
Per-client override
--------------------

"resource_indicators":{
"authorization_code": {
"policy": {
"callable": validate_authorization_resource_indicators_policy,
"kwargs": {
"resource_servers_per_client": ["RESOURCE_1"],
},
},
},
},
}
A client database entry may carry its own ``resource_indicators``,
overriding the endpoint-level default for that client only. It takes a
``policy`` dict directly, the same shape as the endpoint-level default
above::

The policy callable accepts a specific argument list and must return the altered token
request or raise an exception.
endpoint_context.cdb["client_1"]["resource_indicators"] = {
"policy": {
"function": validate_resource_indicators_policy,
"kwargs": {"resource_servers_per_client": ["RESOURCE_1"]},
},
}

For example::
--------------------
The policy function
--------------------

A policy function is called as ``fn(request, context, **kwargs)``:

- ``request`` - the parsed token or authorization request (a ``Message``
or dict), including whatever the client sent (``client_id``,
``resource``, ``scope``, ...). The function may read it, and may
mutate it in place - the engine uses this ``request`` object
afterwards, so changes (e.g. narrowing ``request["resource"]`` or
``request["scope"]``) take effect.
- ``context`` - the endpoint's ``EndpointContext``, giving access to
``context.cdb`` (the client database) and the rest of the server's
runtime state.
- ``**kwargs`` - whatever is in this policy's own ``kwargs`` dict from
configuration (``resource_servers_per_client`` above, or anything
else a custom function declares and expects to be configured with).

It must return either the (possibly modified) ``request`` to let
processing continue normally, or an error response
(``TokenErrorResponse``, or ``AuthorizationErrorResponse`` at the
authorization endpoint) to abort the request with that error::

def validate_resource_indicators_policy(request, context, **kwargs):
if some_condition in request:
return TokenErrorResponse(
error="invalid_request", error_description="Some error occured"
return TokenErrorResponse(
error="invalid_target", error_description="Some error occurred"
)

return request

-----------------
Default audience
-----------------

Every issued access token gets an ``aud`` claim regardless of
``enable_resource_indicators``. When the client doesn't request a
resource, or resource indicators aren't enabled for that request,
``aud`` defaults to the requesting client's own ``client_id`` - it is
never left empty (RFC 9068 Section 3 requires a default resource
indicator, not just permits one). A client-supplied ``resource`` is
also never trusted into ``aud`` unless validated by this policy.


==================
Audience Policies
==================

A second hook, run after resource-indicator validation and immediately
before a token is minted, for computing or restricting the final
``aud`` beyond what resource indicators alone determine.

-------------------------
enable_audience_policies
-------------------------

Same pattern: an endpoint's ``kwargs`` needs
``enable_audience_policies: True`` or ``audience_policies`` is never
consulted.

------------------
audience_policies
------------------

A mapping from ``client_id`` to a list of policy specs, with ``""`` as
the default for any client without an entry of its own::

"audience_policies": {
"client_1": [{"function": my_audience_policy, "kwargs": {...}}],
"": [{"function": default_audience_policy, "kwargs": {...}}],
}

----------------------------
The audience-policy function
----------------------------

A policy function is called as
``fn(request, context, client_id, client_info, audience, grant, **kwargs)``:

- ``request`` - the parsed token or authorization request. May be read and
mutated in place, same as for a resource-indicators policy function.
- ``context`` - the endpoint's ``EndpointContext``.
- ``client_id`` - the requesting client's id (also present in ``request``,
passed separately for convenience).
- ``client_info`` - that client's entry in ``context.cdb``.
- ``audience`` - read-only input: the intended audience of the token so
far. Contains ``request.get("resource")`` (or whatever
``resource_indicators`` narrowed it to, if that ran first) at the
authorization and client_credentials endpoints; the existing grant's or
token's own ``resources`` at the refresh and introspection endpoints,
since ``RefreshAccessTokenRequest``/``TokenIntrospectionRequest`` have no
``resource`` field to read in the first place. Reassigning or mutating it
has no effect - to change the audience, write to ``request`` or ``grant``
instead, as in the examples below.
- ``grant`` - the session grant the token is being minted from.
- ``**kwargs`` - this policy's own ``kwargs`` from configuration.

**Unlike a resource-indicators policy function, the return value is
ignored.** To abort the request, set ``request["error"]`` and
``request["error_description"]`` directly; anything else (returning
``None``, returning the request, returning nothing) just lets processing
continue::

def require_resource_present(request, context, client_id, client_info, audience, grant, **kwargs):
if not request.get("resource"):
request["error"] = "audience_policy_error"
request["error_description"] = "No resource in the request"
# no explicit return - continuing is the default when no error is set

That one only restricts. A function can just as well compute/extend the
audience instead, by mutating ``grant.resources`` in place - this one adds
the client's own id to whatever resources were already there::

def add_self_as_audience(request, context, client_id, client_info, audience, grant, **kwargs):
resources = grant.resources or []
if client_id not in resources:
resources.append(client_id)
grant.resources = resources

2 changes: 1 addition & 1 deletion requirements-dev.txt
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,4 @@ pytest-isort>=1.3.0
pytest-localserver>=0.5.0
flake8
bandit
setuptools
setuptools
1 change: 1 addition & 0 deletions src/idpyoidc/message/oauth2/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,7 @@ class AccessTokenRequest(Message):
"client_id": SINGLE_OPTIONAL_STRING,
"client_secret": SINGLE_OPTIONAL_STRING,
"state": SINGLE_OPTIONAL_STRING,
"resource": OPTIONAL_LIST_OF_STRINGS,
}
c_default = {"grant_type": "authorization_code"}

Expand Down
5 changes: 3 additions & 2 deletions src/idpyoidc/server/authz/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -76,9 +76,10 @@ def __call__(
else:
setattr(grant, key, val)

if resources is None:
# Grant.resources may already has value
if grant.resources is None and resources is None:
grant.resources = [_client_id]
else:
elif resources is not None:
grant.resources = resources

# Scope handling. If allowed scopes are defined for the client filter using that
Expand Down
9 changes: 4 additions & 5 deletions src/idpyoidc/server/endpoint.py
Original file line number Diff line number Diff line change
Expand Up @@ -275,11 +275,10 @@ def client_authentication(self, request: Message, http_info: Optional[dict] = No
authn_info = verify_client(request=request, http_info=http_info, **kwargs)

LOGGER.debug("authn_info: %s", authn_info)
if authn_info == {}:
if self.client_authn_method and len(self.client_authn_method):
LOGGER.debug("client_authn_method: %s", self.client_authn_method)
raise UnAuthorizedClient("Authorization failed")
elif "client_id" not in authn_info and authn_info.get("method") != "none":
if authn_info == {} and self.client_authn_method and len(self.client_authn_method):
LOGGER.debug("client_authn_method: %s", self.client_authn_method)
raise UnAuthorizedClient("Authorization failed")
if "client_id" not in authn_info and authn_info.get("method") != "none":
raise UnAuthorizedClient("Authorization failed")
return authn_info

Expand Down
Loading
Loading