<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC3986   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC6750   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6750.xml">
<!ENTITY RFC6749   PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6749.xml">
<!ENTITY I-D.ietf-oauth-json-web-token PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-oauth-json-web-token.xml">
<!ENTITY I-D.ietf-oauth-v2-http-mac PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-oauth-v2-http-mac.xml">
]>

<?rfc inline="yes"?>
<?rfc toc="yes" ?>
<?rfc tocdepth="2" ?> 
<?rfc symrefs="no" ?>
<?rfc iprnotified="no" ?>
<?rfc strict="no" ?>
<?rfc compact="no" ?>
<?rfc sortrefs="yes" ?>
<?rfc colonspace='yes' ?>


<rfc category='std' updates="6750" ipr='trust200902' docName='draft-tschofenig-oauth-audience-00.txt'>


  <front>
    <title>OAuth 2.0: Audience Information</title>

    <author role="editor" initials="H." surname="Tschofenig" fullname="Hannes Tschofenig">
      <organization>Nokia Siemens Networks</organization>
      <address>
        <postal>
          <street>Linnoitustie 6</street>
          <city>Espoo</city>
          <code>02600</code>
          <country>Finland</country>
        </postal>
        <phone>+358 (50) 4871445</phone>
        <email>Hannes.Tschofenig@gmx.net</email>
        <uri>http://www.tschofenig.priv.at</uri>
      </address>
    </author>
 
    <date year='2013'/>
    <area>Security</area>
    <workgroup>OAuth</workgroup>
    <keyword>Internet-Draft</keyword>

    <abstract>
      <t>
       The OAuth 2.0 Bearer Token specification allows any party in
   possession of a bearer token to get access to
   the associated resources (without demonstrating possession of a
   cryptographic key).  To prevent misuse, two important security assumptions must hold:  bearer tokens must be
   protected from disclosure in storage and in transport and the access token must only be valid for use with a specific 
   resource server (the audience) and with a specific scope. 
      </t>
      
      <t>This document defines a new header that is used by the client to indicate what resource server, as the intended recipient, 
	  it wants to access. This information is subsequently also communicated by the authorization server securely to the resource server, for example within the audience field of the access token.</t>
  </abstract>
  </front>
  <middle>
    
     <!-- *************************************************************************************************** --> 

  
    <section title='Introduction'>
	
	 <t>The OAuth 2.0 Bearer Token specification <xref target="RFC6750"/> allows any party in possession of a bearer token to get access to the associated resources (without demonstrating possession of a cryptographic key).  To prevent misuse, two important security assumptions must hold:  bearer tokens must be protected from disclosure in storage and in transport and the access token must only be valid for use with a specific resource server with a specific scope. 
      </t>
	  
    <t><xref target="RFC6750"/> describes this requirement in the following way:
	<list style="empty">
	<t>"To deal with token redirect, it is important for the authorization
   server to include the identity of the intended recipients (the
   audience), typically a single resource server (or a list of resource
   servers), in the token.  Restricting the use of the token to a
   specific scope is also RECOMMENDED."</t>
   </list> 
   </t>
   
    <t>In general, if there is an authorization restriction then the respective parties must be aware of this restriction.
	In our case, the respective parties are authorization server (who has a trust relationship with the resource owner to accept for reject requests for data sharing and creates the access token), the client (who initiates the access to the protected resource), and the resource server (who protects the access to the resource and grants only access to those clients who have been approved by the authorization server).</t>

	<t>Unfortunately, at the time of writing of <xref target="RFC6750"/> the access token format was still in early stages of the design and more details about how to communicate the audience information between the different parties was left unspecified. This document defines a new field
	for usage with OAuth 2.0. Note that it is not only useful for OAuth 2.0 bearer tokens but also for MAC tokens <xref target="I-D.ietf-oauth-v2-http-mac"/>: the authorization server needs to be told which resource server has to obtain the session key securely in order for the security properties to hold.</t>
	
	<t>Restricting the usage of access tokens is important for several reasons: First, a stolen access token cannot be used with resource servers it has not been created for. Second, if the scope is included it cannot be used for requesting access to resources that exceed the indicated permissions. A resource server, who obtains an access token legitimately, cannot access resources on behalf of the resource owner at other resource servers.</t>
	
    </section>
	
	   <!-- *************************************************************************************************** --> 

	   
    <section title="Terminology" anchor="terminology">
        <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
        "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
        document are to be interpreted as described in <xref target="RFC2119">RFC 2119</xref>.</t>
    </section>
   <!-- *************************************************************************************************** --> 

    <section title='Audience Parameter'>
	
	<t>When the client interacts with the resource server it constructs the access token request to the token endpoint by adding the audience parameter using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP
   request entity-body.</t>
	
	<t>The audience URI MUST be an absolute URI as defined by Section 4.3 of <xref target="RFC3986"/>. It MAY include an
   "application/x-www-form-urlencoded" formatted query component (Section 3.4 of <xref target="RFC3986"/> ). The URI MUST NOT include a
   fragment component.</t>
   
   <t>The ABNF syntax is defined as follows where by the "URI-reference" definition is taken from <xref target="RFC3986"/>:</t>
   
   <t>audience      = URI-reference</t>

        
   <t><list style="empty"><t>[QUESTION: Is it OK to just assume a URI here as the audience identifier?]</t>
   </list></t>
   </section>
   
   <!-- *************************************************************************************************** --> 
   
   <section title="Processing Instructions">

    <t><list style="empty">
	 
     <t>Step (0): As an initial step the client typically determines the resource server it wants to interact with, for example, as part of a discovery procedure. <list style="empty"><t>[QUESTION: Should we talk about WebFinger or SWD to be more specific?]</t>
   </list></t>
	 
	<t>Step (1): The client starts the OAuth 2.0 protocol interaction based on the selected grant type. </t>
	  
	 <t>Step (2): When the client interacts with the token endpoint to obtain an access token it MUST populate the newly defined 'audience' parameter with the information obtained in step (0).</t>
     
     <t>Step (2): The resource server who obtains the request needs to parse it to determine whether the provided audience value matches any of the authorized resource servers it has a relationship with. If the authorization server fails to parse the provided value it MUST reject the request using an error response with the error code "invalid_request". If the authorization server does not consider the resource server acceptable then it MUST return an error response with the error code "access_denied". In both cases additional error information may be provided via the error_description, and the error_uri parameters. If the request has, however, been verified successfully then the authorization server MUST include the audience claim into the access token with the value copied from the audience field provided by the client. In case the access token is encoded using the JSON Web Token format <xref target="I-D.ietf-oauth-json-web-token"/> the "aud" claim MUST be used. The access token MUST be protected against modification by protecting it with either a digital signature or a keyed message digest. The authorization server returns the access token to the client, as specified in <xref target="RFC6749"/>.<list style="empty"><t> [QUESTION: Should we just focus on a JSON-based encoding of the access token since it is the only specified format?]</t>
   </list></t>
	 
	 <t>Step (3): The client follows the OAuth 2.0 specification <xref target="RFC6749"/> and the specification relevant for the selected token type (e.g., the bearer token specification) to interact with the resource server to make a request to the protected resource with the attached access token.</t>
	 <t>Step (4): When the resource server receives the access token it verifies it according to chosen access token encoding. For example, in case the JSON Web Token format is used then it must adhere to the guidance in <xref target="I-D.ietf-oauth-json-web-token"/>. In any case, the resource server MUST verify whether the URI contained in the "aud" claim matches it's own.  If the comparison fails the resource server MUST return an error to the client. <list style="empty"><t>[NOTE: More guidance is required in <xref target="I-D.ietf-oauth-json-web-token"/> regarding the matching procedure.]</t>
   </list></t>
	 </list>
	 </t>
	 
   </section> 


    <section title='Security Considerations' anchor='Security'>
      <t>The sole purpose of this document is to extend the OAuth 2.0 protocol to improve security.</t>
    </section>

	   <!-- *************************************************************************************************** --> 

    <section title='IANA Considerations' anchor='IANA'>
	 <t>This document requires IANA to add a new value to the OAuth parameters registry:
<list style="symbols">
<t>Parameter name: audience</t>
<t>Parameter usage location: token request</t>
<t>Change controller: IETF</t>
<t>Specification document(s): [[This document.]</t>
</list> 
</t>
    </section>

       <!-- *************************************************************************************************** --> 

    <section title='Acknowledgments'>
      <t>
       The author would like to thank Leif Johansson, and Eve Maler for their feedback.
      </t>
    </section>

	   <!-- *************************************************************************************************** --> 

  </middle>

  <back>

    <references title='Normative References'>
   &RFC2119; 
   &RFC3986;
   &RFC6750;
   &RFC6749;

    </references>

    <references title='Informative References'>
    &I-D.ietf-oauth-v2-http-mac;
	&I-D.ietf-oauth-json-web-token;
	
    </references>
  </back>

</rfc>
