minor edits, add link to github issues

aaronpk · aaronpk · commit b6b8d60624dd · 2025-04-22T16:07:37.000-07:00
diff --git a/draft-parecki-oauth-identity-assertion-authz-grant.md b/draft-parecki-oauth-identity-assertion-authz-grant.md
@@ -465,16 +465,16 @@ AI agents, including those based on large language models (LLMs), are designed t
 ### Preconditions
 
 * The LLM Agent has a registered OAuth 2.0 Client (`com.example.ai-agent`) with the Enterprise IdP (`cyberdyne.idp.example`)
-* The LLM Agent has a registered OAuth 2.0 Client (`com.example.ai-agent`) with the External Tool Application (`saas.example.com`)
+* The LLM Agent has a registered OAuth 2.0 Client (`4960880b83dc9`) with the External Tool Application (`saas.example.net`)
 * Enterprise has established a trust relationship between their IdP and the LLM Agent for SSO
 * Enterprise has established a trust relationship between their IdP and the External Tool Application for SSO and Identity Assertion Authorization Grant
 * Enterprise has granted the LLM Agent permission to act on behalf of users for the External Tool Application with a specific set of scopes
 
-### LLM Agent establishes a User Identity with Enteprise IdP
+### LLM Agent establishes a User Identity with Enterprise IdP
 
 LLM Agent discovers the Enterprise IdP's OpenID Connect Provider configuration based on a configured `issuer` that was previously establshed.
 
-> Note: IdP discovery where an agent discovers which IdP the agent should use to authenticate a given user is out-of-scope of this specification.
+> Note: IdP discovery where an agent discovers which IdP the agent should use to authenticate a given user is out of scope of this specification.
 
     GET /.well-known/openid-configuration
     Host: cyberdyne.idp.example
@@ -504,11 +504,11 @@ LLM Agent discovers the Enterprise IdP's OpenID Connect Provider configuration b
 
 LLM Agent discovers all necessary endpoints for authentication as well as support for the Token Exchange grant type `urn:ietf:params:oauth:grant-type:token-exchange`
 
-> Note: Unfortunately Token Exchange {{RFC8693}} doesn't define an authorization server metadata parameter for `requested_token_types_supported` to discover if `urn:ietf:params:oauth:token-type:id-jag` is specifically supported so the LLM Agent needs to first attempt Token Exchange to learn if the specific Enterprise IdP supports issuing an Identity Assertion Grant.
+> Note: Token Exchange {{RFC8693}} doesn't define an authorization server metadata parameter for `requested_token_types_supported` to discover if `urn:ietf:params:oauth:token-type:id-jag` is specifically supported. Currently, the LLM Agent needs to first attempt Token Exchange to learn if the specific Enterprise IdP supports issuing an Identity Assertion Grant. This specification could define an Authorization Server Metadata {{RFC8414}} parameter to enable the agent to discover if this request is supported. See [issue #16](https://github.com/aaronpk/draft-parecki-oauth-identity-assertion-authz-grant/issues/16).
 
 ### IdP Authorization Request (with PKCE)
 
-LLM Agent generates a `code_verifier` and a `code_challenge` (usually a SHA256 hash of the verifier, base64url-encoded) and redirects the end-user to the Enterprise IdP with an authorization request
+LLM Agent generates a PKCE `code_verifier` and a `code_challenge` (usually a SHA256 hash of the verifier, base64url-encoded) and redirects the end-user to the Enterprise IdP with an authorization request
 
     GET /authorize?
       response_type=code
@@ -526,7 +526,7 @@ Enterprise IdP authenticates the end-user and redirects back to the LLM Agent's
 
     https://ai-agent.example.com/oauth2/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=xyzABC123
 
-LLM Agent exchanges the `code` with PKCE `code_verifier` to obtain an ID Token and Access Token for the IdP's UserInfo endpoint
+LLM Agent exchanges the `code` and PKCE `code_verifier` to obtain an ID Token and Access Token for the IdP's UserInfo endpoint
 
     POST /oauth2/token
     Host: cyberdyne.idp.example
@@ -566,40 +566,38 @@ LLM Agent now has an identity binding for context
 
 ### LLM Agent calls Enterprise External Tool
 
-LLM Agent tool calls an external tool provided by an Enterprise SaaS Application(Resource Server) without a valid access token and is issued an authentication challenge using {{I-D.ietf-oauth-resource-metadata}}
+LLM Agent tool calls an external tool provided by an Enterprise SaaS Application (Resource Server) without a valid access token and is issued an authentication challenge using {{I-D.ietf-oauth-resource-metadata}}
 
-> Note:  How agents discover available tools is out-of-scope of this specification
+> Note: How agents discover available tools is out of scope of this specification
 
     GET /tools
-    Host: saas.example.com
+    Host: saas.example.net
     Accept: application/json
 
-    HTTP/1.1 400 Bad Request
-    WWW-Authenticate: Bearer error="invalid_request",
-      error_description="No access token was provided in this request",
-      resource_metadata=
-      "https://saas.example.com/tools/.well-known/oauth-protected-resource"
+    HTTP/1.1 401 Unauthorized
+    WWW-Authenticate: Bearer resource_metadata=
+      "https://saas.example.net/.well-known/oauth-protected-resource"
 
 LLM Agent fetches the external tool resource's `OAuth 2.0 Protected Resource Metadata` per {{I-D.ietf-oauth-resource-metadata}} to dynamically discover an authorization server that can issue an access token for the resource.
 
-    GET /tools/.well-known/oauth-protected-resource
-    Host: saas.example.com
+    GET /.well-known/oauth-protected-resource
+    Host: saas.example.net
     Accept: application/json
 
     HTTP/1.1 200 Ok
     Content-Type: application/json
 
     {
        "resource":
-         "https://saas.example.com/tools",
+         "https://saas.example.net/",
        "authorization_servers":
          [ "https://authorization-server.saas.com" ],
        "bearer_methods_supported":
          ["header", "body"],
        "scopes_supported":
          ["agent.tools.read", "agent.tools.write"],
        "resource_documentation":
-         "https://saas.example.com/tools/resource_documentation.html"
+         "https://saas.example.net/tools/resource_documentation.html"
      }
 
 LLM Agent discovers the Authorization Server configuration per {{RFC8414}}
@@ -633,6 +631,8 @@ LLM Agent has learned all necessary endpoints and supported capabilites to obtai
 
 If the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant type is supported the LLM can first attempt to silently obtain an access token using an Identity Assertion Authorization Grant from the Enterprise's IdP otherwise it can fallback to interactively obtaining a standard `authorization_code` from the SaaS Application's Authorization Server
 
+> Note: This would benefit from an Authorization Server Metadata {{RFC8414}} property to indicate whether the Identity Assertion Authorization Grant form of `jwt-bearer` would be accepted by this authorization server. There are other uses of `jwt-bearer` that may be supported by the authorization server as well, and is not necessarily a reliable indication that the Identity Assertion Authorization Grant would be supported. See [issue #16](https://github.com/aaronpk/draft-parecki-oauth-identity-assertion-authz-grant/issues/16).
+
 ### LLM Agent obtains an Identity Assertion Grant for Enterprise External Tool from the Enterprise IdP
 
 LLM Agent makes an Identity Assertion Grant Token Exchange {{RFC8693}} request for the external tool's resource from the user's Enterprise IdP using the ID Token the LLM Agent obtained when establishing an identity binding context along with scopes and the resource identifier for the external tool that was returned in the tool's `OAuth 2.0 Protected Resource Metadata`
@@ -643,7 +643,7 @@ LLM Agent makes an Identity Assertion Grant Token Exchange {{RFC8693}} request f
 
     grant_type=urn:ietf:params:oauth:grant-type:token-exchange
     &requested_token_type=urn:ietf:params:oauth:token-type:id-jag
-    &resource=https://saas.example.com/tools"
+    &resource=https://saas.example.net/
     &scope=agent.read+agent.write
     &subject_token=eyJraWQiOiJzMTZ0cVNtODhwREo4VGZCXzdrSEtQ...
     &subject_token_type=urn:ietf:params:oauth:token-type:id_token
@@ -665,7 +665,7 @@ If access is granted, the Enterprise IdP creates a signed Identity Assertion Aut
       "expires_in": 300
     }
 
-Identity Assertion Authorization Grant
+Identity Assertion Authorization Grant JWT claims:
 
     {
       "alg": "ES256",
@@ -687,11 +687,11 @@ Identity Assertion Authorization Grant
 
 ### LLM Agent obtains an Access Token for Enterprise External Tool
 
-LLM Agent makes a token request to the previously discovered external tool's  Authorization Server token endpoint using the Identity Assertion Authorization Grant obtained from the Enterprise IdP as a JWT Assertion as defined by {{RFC7523}}.
+LLM Agent makes a token request to the previously discovered external tool's Authorization Server token endpoint using the Identity Assertion Authorization Grant obtained from the Enterprise IdP as a JWT Assertion as defined by {{RFC7523}}.
 
-The LLM Agent authenticates with it's client credentials that were registered with the SaaS Authorization Server
+The LLM Agent authenticates with its client credentials that were registered with the SaaS Authorization Server
 
-> Note: How the LLM Agent registers with the Authorization Server (e.g static or dynamic client registration) is out-of-scope of this specification
+> Note: How the LLM Agent registers with the Authorization Server (e.g static or dynamic client registration), and whether or not it has credentials, is out-of-scope of this specification
 
     POST /oauth2/token HTTP/1.1
     Host: authorization-server.saas.com
@@ -720,7 +720,7 @@ SaaS Authorization Server validates the Identity Assertion Authorization Grant u
 LLM Agent tool calls an external tool provided by the Enterprise SaaS Application (Resource Server) with a valid access token
 
     GET /tools
-    Host: saas.example.com
+    Host: saas.example.net
     Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA"
     Accept: application/json
 
