Skip to content

Commit abb3f49

Browse files
committed
docs: use the issuer identifier as ID-JAG audience and fix broken links
1 parent 1bd2a31 commit abb3f49

2 files changed

Lines changed: 21 additions & 15 deletions

File tree

‎authlib/oauth2/drafts/id_jag.py‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -106,14 +106,15 @@ def sign(
106106
107107
:param key: signing key (private key or shared secret)
108108
:param issuer: ``iss`` claim - identifies the IdP
109-
:param audience: ``aud`` claim - the resource AS token endpoint
109+
:param audience: ``aud`` claim - the resource AS issuer identifier
110110
:param subject: ``sub`` claim - the end user (required)
111-
:param client_id: ``client_id`` claim - the application
111+
:param client_id: ``client_id`` claim - the client identifier at the
112+
resource AS
112113
:param jti: ``jti`` claim (auto-generated when *None*)
113114
:param issued_at: ``iat`` claim (defaults to now)
114115
:param expires_at: ``exp`` claim
115116
:param claims: additional claims dict
116-
:param kwargs: forwarded to :func:`sign_jwt_bearer_assertion`
117+
:param kwargs: forwarded to ``sign_jwt_bearer_assertion``
117118
(e.g. ``alg="RS256"``)
118119
:return: compact-serialised JWT string
119120
"""
@@ -285,8 +286,8 @@ def _verify_claims(self, claims: jwt.Claims):
285286
def get_audiences(self) -> list:
286287
"""Return the list of valid ``aud`` values for this AS.
287288
288-
Typically the token endpoint URL and/or the AS issuer identifier.
289-
The returned list must be non-empty; ``aud`` validation is
289+
Per the ID-JAG draft, ``aud`` is the issuer identifier of the
290+
Resource Authorization Server. The returned list must be non-empty; ``aud`` validation is
290291
mandatory for ID-JAG assertions.
291292
"""
292293
raise NotImplementedError()

‎docs/oauth2/specs/id-jag.rst‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -78,21 +78,24 @@ The full flow:
7878
``IDJAGGrant`` implements steps 3 and 4. The ``/token`` and ``/api`` paths
7979
are examples.
8080

81-
The key differences from standard RFC 7523:
81+
The key differences from :class:`~authlib.oauth2.rfc7523.JWTBearerGrant`:
8282

8383
* The ``iss`` claim identifies the **IdP**, not the client.
84-
* A separate ``client_id`` claim identifies the **application** and must match
85-
the authenticated client redeeming the assertion.
84+
* A separate ``client_id`` claim identifies the **client**, by its identifier
85+
at the Resource Authorization Server. It must match the authenticated client
86+
redeeming the assertion.
87+
* The ``aud`` claim is the issuer identifier of the Resource Authorization
88+
Server.
8689
* The JWT ``typ`` header is ``oauth-id-jag+jwt`` to prevent type confusion.
87-
* ``sub``, ``jti``, and ``iat`` are **required** (optional in base RFC 7523).
90+
* ``sub``, ``jti``, and ``iat`` are **required**. ``JWTBearerGrant`` does not
91+
require them.
8892

8993

9094
Using IDJAGGrant
9195
----------------
9296

9397
``IDJAGGrant`` is a standalone grant — it inherits directly from
94-
:class:`~authlib.oauth2.rfc6749.BaseGrant` and
95-
:class:`~authlib.oauth2.rfc6749.TokenEndpointMixin`, **not** from
98+
``BaseGrant`` and ``TokenEndpointMixin``, **not** from
9699
:class:`~authlib.oauth2.rfc7523.JWTBearerGrant`. The two grants share
97100
only the ``grant_type`` URI; the ID-JAG three-party model has different
98101
hooks (issuer-keyed key resolution, user authorization, and ``jti`` replay
@@ -108,7 +111,8 @@ after subclassing it to implement all required hooks::
108111

109112
class IDJAGGrant(_IDJAGGrant):
110113
def get_audiences(self):
111-
return ["https://example.com/oauth/token"]
114+
# The issuer identifier of this authorization server
115+
return ["https://example.com"]
112116

113117
def resolve_issuer_key(self, issuer, headers):
114118
"""Fetch IdP public keys by issuer URL.
@@ -177,13 +181,13 @@ client implementations::
177181
assertion = IDJAGGrant.sign(
178182
key=private_key,
179183
issuer="https://idp.example.com",
180-
audience="https://resource-as.example.com/token",
184+
audience="https://resource-as.example.com",
181185
subject="user-123",
182186
client_id="app-456",
183187
alg="RS256",
184188
)
185189

186-
Unlike :meth:`JWTBearerGrant.sign`, ``subject`` and ``client_id`` are
190+
Unlike ``JWTBearerGrant.sign()``, ``subject`` and ``client_id`` are
187191
**required** parameters. The ``typ`` header is always set to
188192
``oauth-id-jag+jwt`` and a ``jti`` is auto-generated if not provided.
189193

@@ -224,7 +228,8 @@ Required Hooks
224228
* - Hook
225229
- Purpose
226230
* - ``get_audiences()``
227-
- Return list of valid audience identifiers for this authorization server.
231+
- Return the list of valid ``aud`` values: the issuer identifier of this
232+
authorization server.
228233
* - ``resolve_issuer_key(issuer, headers)``
229234
- Fetch the IdP's public key(s) by issuer identifier. ``headers``
230235
contains the JWT headers (including ``kid``) for key selection.

0 commit comments

Comments
 (0)