draft-lodderstedt-oauth-jwt-introspection-response.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!--
		This template is for creating an Internet Draft using xml2rfc, which
		is available here: http://xml.resource.org.
	-->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
     There has to be one entity for each item to be referenced. 
     An alternate method (rfc include) is described in the references. -->
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY I-D.narten-iana-considerations-rfc2434bis SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.narten-iana-considerations-rfc2434bis.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!--
		For a complete list and description of processing instructions (PIs),
		please see http://xml.resource.org/authoring/README.html.
	-->
<!--
		Below are generally applicable Processing Instructions (PIs) that most
		I-Ds might want to use. (Here they are set differently than their
		defaults in xml2rfc v1.32)
	-->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="4"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!--
		control vertical white space (using these PIs as follows is
		recommended by the RFC Editor)
	-->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="std" docName="draft-lodderstedt-oauth-jwt-introspection-response-01"
     ipr="trust200902">
  <!--
		category values: std, bcp, info, exp, and historic ipr values:
		full3667, noModification3667, noDerivatives3667 you can add the
		attributes updates="NNNN" and obsoletes="NNNN" they will automatically
		be output with "(if approved)"
	-->

  <!-- ***** FRONT MATTER ***** -->

  <front>
    <!--
			The abbreviated title is used in the page header - it is only
			necessary if the full title is longer than 39 characters
		-->

    <title abbrev="JWT Response">JWT Response for OAuth Token Introspection</title>

    <author fullname="Torsten Lodderstedt" initials="T." role="editor"
            surname="Lodderstedt">
      <organization>YES.com AG</organization>

      <address>
        <email>torsten@lodderstedt.net</email>

        <!-- uri and facsimile elements may also be added -->
      </address>
      </author>
          
    <author fullname="Vladimir Dzhuvinov" initials="V." 
            surname="Dzhuvinov">
      <organization>Connect2id Ltd.</organization>

      <address>
        <email>vladimir@connect2id.com</email>

        <!-- uri and facsimile elements may also be added -->
      </address>
    </author>

    <date day="28" month="May" year="2018" />

    <!-- Meta-data Declarations -->

    <area>Security Area</area>

    <workgroup>Open Authentication Protocol</workgroup>

    <!--
			WG name at the upperleft corner of the doc, IETF is fine for
			individual submissions. If this element is not present, the default
			is "Network Working Group", which is used by the RFC Editor as a nod
			to the history of the IETF.
		-->

    <keyword>token introspection</keyword>
    
    <keyword>JWT</keyword>

    <keyword>oauth2</keyword>

    <!--
			Keywords will be incorporated into HTML output files in a meta tag
			but they have no effect on text or nroff output. If you submit your
			draft to the RFC Editor, the keywords will be used for the search
			engine.
		-->

    <abstract>
      <t>This draft proposes an additional JSON Web Token (JWT) based response 
      for OAuth 2.0 Token Introspection.</t>
    </abstract>
  </front>

  <middle>
    <section anchor="Introduction" title="Introduction">
      <t><xref target="RFC7662">OAuth 2.0 Token Introspection</xref> specifies a 
      method for a protected resource to query an OAuth 2.0 authorization server 
      to determine the state of an access token and obtain data associated with
      the access token.
      This allows deployments to implement identifier-based access tokens 
      in an interoperable way.</t>
      <t>The introspection response as specified in <xref target="RFC7662">OAuth 
      2.0 Token Introspection</xref> is a plain JSON object.
      However, there are use cases where the resource server requires stronger
      assurance that the authorisation server issued the access token,
      including cases where the authorisation server assumes liability for the
      token's content. An example is a resource server using verified person
      data to create qualified electronic signatures.</t>
      <t>In such use cases, it would be useful to return a signed JWT as the
      introspection response. This specification extends the Token
      Introspection endpoint with the capability to return responses as
      JWTs.</t>
    </section>

	<section anchor="jwt_request" title="Requesting a JWT Response">
	<t>A resource server requests to receive a JWT introspection response by
        including an Accept header with content type "application/jwt" in the
        introspection request.</t>

      <t>The following is a non-normative example request:</t>
	  <t>
	  	<figure>
          <artwork><![CDATA[POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/jwt
Content-Type: application/x-www-form-urlencoded

token=2YotnFZFEjr1zCsicMWpAA]]></artwork>
        </figure>
	  </t>
	</section>
	
    <section anchor="jwt_response" title="JWT Response">
      <t>The introspection endpoint responds with a JWT, setting the
          Content-Type header to "application/jwt".</t>
      <t>This JWT MUST contain the claims 
	  <spanx style="verb">iss</spanx> and <spanx style="verb">aud</spanx> in order to 
	  prevent misuse of the JWT as ID or access token 
	  (see <xref target="Cross-JWT_Confusion"/>).</t>
      <t>This JWT may furthermore contain all other claims described in Section 2.2. of
      <xref target="RFC7662"/>.</t>
      <t>The following is a non-normative example response 
      (with line breaks for display purposes only):</t>
	  <t>
	  	<figure>
          <artwork><![CDATA[HTTP/1.1 200 OK
Content-Type: application/jwt

eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJaNU8zdXBQQzg4UXJBa
ngwMGRpcyIsImF1ZCI6Imh0dHBzOlwvXC9wcm90ZWN0ZWQuZXhhbXBsZS5uZXRcL
3Jlc291cmNlIiwiZXh0ZW5zaW9uX2ZpZWxkIjoidHdlbnR5LXNldmVuIiwic2Nvc
GUiOiJyZWFkIHdyaXRlIGRvbHBoaW4iLCJpc3MiOiJodHRwczpcL1wvc2VydmVyL
mV4YW1wbGUuY29tXC8iLCJhY3RpdmUiOnRydWUsImV4cCI6MTQxOTM1NjIzOCwia
WF0IjoxNDE5MzUwMjM4LCJjbGllbnRfaWQiOiJsMjM4ajMyM2RzLTIzaWo0Iiwid
XNlcm5hbWUiOiJqZG9lIn0.HEQHf05vqVvWVnWuEjbzUnPz6JDQVR69QkxgzBNq5
kk-sK54ieg1STazXGsdFAT8nUhiiV1f_Z4HOKNnBs8TLKaFXokhA0MqNBOYI--2u
nVHDqI_RPmC3p0NmP02Xmv4hzxFmTmpgjSy3vpKQDihOjhwNBh7G81JNaJqjJQTR
v_1dHUPJotQjMK3k8_5FyiO2p64Y2VyxyQn1VWVlgOHlJwhj6BaGHk4Qf5F8DHQZ
1WCPg2p_-hwfINfXh1_buSjxyDRF4oe9pKy6ZB3ejh9qIMm-WrwltuU1uWMXxN6e
S6tUtpKo8UCHBwLWCHmJN7KU6ZojmaISspdS23lELAlyw]]></artwork>
        </figure>	
        </t>
        <t>
        The example response contains the following JSON document:
        </t>
        <t>
        <figure>
          <artwork><![CDATA[{
  "sub": "Z5O3upPC88QrAjx00dis",
  "aud": "https://protected.example.net/resource",
  "scope": "read write dolphin",
  "iss": "https://server.example.com/",
  "active": true,
  "exp": 1419356238,
  "iat": 1419350238,
  "client_id": "l238j323ds-23ij4",
  "given_name": "John",
  "family_name":"Doe",
  "birthdate":"1982-02-01"
}]]></artwork>
        </figure>

	  </t>  
    </section>
    
    <section anchor="client_metadata" title="Client Metadata">
      <t>The authorization server determines what algorithm to employ to
      secure the JWT for a particular introspection response. This decision can
      be based on registered metadata parameters for the resource server,
      supplied via dynamic client registration with the resource server posing
      as the client.</t>
      <t>The parameter names follow the pattern established by
      <xref target="OpenID.Registration">OpenID Connect
      Dynamic Client Registration</xref> for configuring signing and encryption
      algorithms for JWT responses at the UserInfo endpoint.</t>
      <t>The following client metadata parameters are introduced by this
      specification:
		<list hangIndent="8" style="hanging">
      	  <t hangText="introspection_signed_response_alg"><xref target="RFC7515">JWS</xref> 
      	  <spanx style="verb">alg</spanx> algorithm 
      	  <xref target="RFC7518">JWA</xref> REQUIRED for signing introspection responses. If
      	  this is specified, the response will be <xref target="RFC7519">JWT</xref>
      	  serialized, and signed using JWS. The default,
      	  if omitted, is for the introspection response to return the Claims as a
      	  UTF-8 encoded JSON object using the "application/json" content type,
      	  as defined in <xref target="RFC7662"/>.</t>
          <t hangText="introspection_encrypted_response_alg"> 
          <xref target="RFC7516">JWE</xref> <spanx style="verb">alg</spanx> algorithm 
          <xref target="RFC7518">JWA</xref> 
          REQUIRED for encrypting introspection responses.
          If both signing and encryption are requested, the response will be 
          signed then encrypted, with the result being a Nested JWT, as defined in 
          <xref target="RFC7519">JWT</xref>. The default, if omitted, is that no 
          encryption is performed.</t>
          <t hangText="introspection_encrypted_response_enc"><xref target="RFC7516">JWE</xref>
          <spanx style="verb">enc</spanx> algorithm <xref target="RFC7518">JWA</xref> REQUIRED for encrypting 
          introspection responses. If 
          <spanx style="verb">introspection_encrypted_response_alg</spanx> is specified, the default 
          for this value is A128CBC-HS256. When 
          <spanx style="verb">introspection_encrypted_response_enc</spanx> is included, 
          <spanx style="verb">introspection_encrypted_response_alg</spanx> MUST also be provided.</t>
        </list>
      </t>
     <t>Resource servers may register their public encryption keys 
      using the <spanx style="verb">jwks_uri</spanx> or <spanx style="verb">jwks</spanx> 
      metadata parameters.</t>
    </section>    
    
    <section anchor="server_metadata" title="Authorization Server Metadata">
      <t>Authorization servers SHOULD publish the supported algorithms for
      signing and encrypting the JWT of an introspection response by utilizing
      OAuth Authorization Server Metadata parameters.</t>
     <t>The following parameters are introduced by this specification: 
		<list hangIndent="8" style="hanging">
				
		<t hangText="introspection_signing_alg_values_supported">
		OPTIONAL. JSON array containing a list of the <xref target="RFC7515">JWS</xref> signing 
		algorithms (<spanx style="verb">alg</spanx> values) 
		<xref target="RFC7518">JWA</xref> supported by the Introspection 
		Endpoint to sign the response.</t> 

		<t hangText="introspection_encryption_alg_values_supported">
		OPTIONAL. JSON array containing a list of the <xref target="RFC7516">JWE</xref> 
		encryption algorithms (<spanx style="verb">alg</spanx> values) 
		<xref target="RFC7518">JWA</xref> supported by the 
		Introspection Endpoint to encrypt the response.</t>

		<t hangText="introspection_encryption_enc_values_supported">
		OPTIONAL. JSON array containing a list of the <xref target="RFC7516">JWE</xref> encryption 
		algorithms (<spanx style="verb">enc</spanx> values) 
		<xref target="RFC7518">JWA</xref> supported by the Introspection 
		Endpoint to encrypt the response.</t>		

        </list>
      </t>
    </section>
    
    <section anchor="Acknowledgements" title="Acknowledgements">
      <t>We would like to thank Petteri Stenius and Neil Madden 
      for their valuable feedback.</t>
    </section>

    <!-- Possibly a 'Contributors' section ... -->

    <section anchor="IANA" title="IANA Considerations">  
      
      <section anchor="DynRegReg" title="OAuth Dynamic Client Registration Metadata Registration">
        <t>
          This specification requests registration of the following client metadata definitions
          in the IANA "OAuth Dynamic Client Registration Metadata" registry
          <xref target="IANA.OAuth.Parameters"/>
          established by <xref target="RFC7591"/>:
        </t>

        <section anchor="DynRegContents" title="Registry Contents">
          <t>
            <list style="symbols">
              <t>
                Client Metadata Name: <spanx style="verb">introspection_signed_response_alg</spanx>
              </t>
              <t>
                Client Metadata Description:
                String value indicating the client's desired introspection response 
                signing algorithm.
              </t>
              <t>
                Change Controller: IESG
              </t>
              <t>
                Specification Document(s): <xref target="client_metadata"/> of [[ this specification ]]
              </t>
            </list>
          </t>
          <t>
            <list style="symbols">
              <t>
                Client Metadata Name: <spanx style="verb">introspection_encrypted_response_alg</spanx>
              </t>
              <t>
                Client Metadata Description:
                String value specifying the desired introspection response 
                encryption algorithm (alg value).
              </t>
              <t>
                Change Controller: IESG
              </t>
              <t>
                Specification Document(s): <xref target="client_metadata"/> of [[ this specification ]]
              </t>
            </list>
          </t>
          <t>
            <list style="symbols">
              <t>
                Client Metadata Name: <spanx style="verb">introspection_encrypted_response_enc</spanx>
              </t>
              <t>
                Client Metadata Description:
                    String value specifying the desired introspection response 
                encryption algorithm (enc value).
              </t>
              <t>
                Change Controller: IESG
              </t>
              <t>
                Specification Document(s): <xref target="client_metadata"/> of [[ this specification ]]
              </t>
            </list>
          </t>

        </section>
      </section>
      
      <section anchor="ietf-oauth-discoveryIANA" title="OAuth Authorization Server Metadata Registration">
      <t>
        This specification requests registration of the following value
        in the IANA "OAuth Authorization Server Metadata" registry
        <xref target="IANA.OAuth.Parameters"/> established by <xref target="I-D.ietf-oauth-discovery"/>.
      </t>
        <section title="Registry Contents">
          <t>
            <list style='symbols'>
              <t>Metadata Name: <spanx style="verb">introspection_signing_alg_values_supported</spanx></t>
              <t>Metadata Description: JSON array containing a list of algorithms supported 
              by the authorization server for introspection response signing.</t>
              <t>Change Controller: IESG</t>
              <t>Specification Document(s): <xref target="server_metadata"/> of [[ this specification ]]</t>             
            </list>
          </t>
          <t>
            <list style='symbols'>
              <t>Metadata Name: <spanx style="verb">introspection_encryption_alg_values_supported</spanx></t>
              <t>Metadata Description: JSON array containing a list of algorithms supported 
              by the authorization server for introspection response encryption (alg value).</t>
              <t>Change Controller: IESG</t>
              <t>Specification Document(s): <xref target="server_metadata"/> of [[ this specification ]]</t>             
            </list>
          </t>
          <t>
            <list style='symbols'>
              <t>Metadata Name: <spanx style="verb">introspection_encryption_enc_values_supported</spanx></t>
              <t>Metadata Description: JSON array containing a list of algorithms supported 
              by the authorization server for introspection response encryption (enc value).</t>
              <t>Change Controller: IESG</t>
              <t>Specification Document(s): <xref target="server_metadata"/> of [[ this specification ]]</t>             
            </list>
          </t>
        </section>
      </section>     
      
    <section anchor="ietf-oauth-introspectionIANA" title="OAuth Token Introspection Response">
      <t>
        TBD: add all OpenID Connect standard claims. 
      </t>
      </section>     


    </section>

    <section anchor="Security" title="Security Considerations">
     <section anchor="Cross-JWT_Confusion" title="Cross-JWT Confusion">
      <t>JWT introspection responses and OpenID Connect ID Tokens are 
      syntactically more or less equivalent. An attacker could therefore
      try to misuse an JWT obtained from an introspection response
      to impersonate the user whose claims are included in this JWT
      at a OpenID Connect RP. 
      
      Such an attack is treated and prevented like any other token substitution 
      attack. The AS MUST include the claims <spanx style="verb">iss</spanx> and 
      <spanx style="verb">aud</spanx> into every JWT introspection response. This 
      allows every well behaving OpenID Connect RP to detect substitution by 
      checking the <spanx style="verb">iss</spanx> and 
      <spanx style="verb">aud</spanx> claims as described in Section 3.1.3.7. of 
      <xref target="OpenID.Core"/>. RPs should also use and check the 
      <spanx style="verb">nonce</spanx> parameter and claim to prevent 
      token and code replay.</t>
      
      <t>Resource servers utilizing JWTs to represent structured access 
      tokens could be susceptible to replay attacks as well. Resource servers
      should therefore apply proper counter measures against replay as 
      described in <xref target="I-D.ietf-oauth-security-topics"/>, 
      section 2.2.</t>
      <t>JWT Confusion and other attacks on JWTs are discussed in detail 
      in <xref target="I-D.ietf-oauth-jwt-bcp"/>.</t>
     </section>
    </section>
    
  </middle>

  <!--  *****BACK MATTER ***** -->

  <back>
    <references title="Normative References">
      <?rfc include="reference.RFC.2119"?>

      <?rfc include="reference.RFC.2246"?>
      
      <?rfc include="reference.RFC.7519"?>
      
      <?rfc include="reference.RFC.7591"?>

      <?rfc include="reference.RFC.7662"?>
      
      <?rfc include="reference.RFC.7518"?>
      
      <?rfc include="reference.RFC.7515"?>
      <?rfc include="reference.RFC.7516"?>
      <?rfc include="http://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-discovery-10.xml"?>
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-jwt-bcp-03.xml'?>
      <?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-security-topics-06.xml'?>
      
       <reference anchor="OpenID.Registration" target="https://openid.net/specs/openid-connect-registration-1_0.html">
        <front>
          <title>OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1</title>

		  <author fullname="Nat Sakimura">
            <organization>NRI</organization>
          </author>
          <author fullname="John Bradley">
            <organization>Ping Identity</organization>
          </author>
          <author fullname="Mike Jones">
            <organization>Microsoft</organization>
          </author>
          <date day="8" month="Nov" year="2014"/>
        </front>
      </reference>
      
       <reference anchor="OpenID.Core" target="http://openid.net/specs/openid-connect-core-1_0.html">
        <front>
          <title>OpenID Connect Core 1.0 incorporating errata set 1</title>

		  <author fullname="Nat Sakimura">
            <organization>NRI</organization>
          </author>
          <author fullname="John Bradley">
            <organization>Ping Identity</organization>
          </author>
          <author fullname="Mike Jones">
            <organization>Microsoft</organization>
          </author>
          <author fullname="Breno de Medeiros">
            <organization>Google</organization>
          </author>
          <author fullname="Chuck Mortimore">
            <organization>Salesforce</organization>
          </author>
          <date day="8" month="Nov" year="2014"/>
        </front>
      </reference>

    </references>

    <references title="Informative References">
          <reference anchor="IANA.OAuth.Parameters" target="http://www.iana.org/assignments/oauth-parameters">
        <front>
          <title>OAuth Parameters</title>
          <author>
            <organization>IANA</organization>
          </author>
          <date/>
        </front>
      </reference>
    </references> 
    
    <section anchor="History" title="Document History">
      <t>[[ To be removed from the final specification ]]</t>
      <t>-01<list style="symbols">
      	  <t>fixed typos in client meta data field names</t>
      	  <t>added OAuth Server Metadata parameters to publish algorithms supported 
      	  for signing and encrypting the introspection response</t>
      	  <t>added registration of new parameters for OAuth Server Metadata
      	  and Client Registration</t>
      	  <t>added explicit request for JWT introspection response</t>
      	  <t>made iss and aud claims mandatory in introspection response</t>
      	  <t>Stylistic and clarifying edits, updates references</t>
        </list></t> 
      <t>-00<list style="symbols">
          <t>initial version</t>
        </list></t>  
        
    </section>	
  </back>
</rfc>