One document matched: draft-wmills-oauth-lrdd-01.xml

<?xml version="1.0"?>

<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc compact="no" ?>
<?rfc sortrefs="yes" ?>
<?rfc strict="yes" ?>
<?rfc linkmailto="yes" ?>


<rfc ipr="trust200902" docName="draft-wmills-oauth-lrdd-01.txt" category="info">

  <front>
    <title abbrev="A SASL/GSS-API Mechanism for OAuth">Link Type Registry for OAuth 2</title>
    <author fullname="William Mills" initials="W." surname="Mills">
      <organization>Yahoo! Inc.</organization>
      <address>
        <postal>
          <street/>
          <city/>
          <code/>
          <region/>
          <country/>
        </postal>
        <phone/>
        <email>wmills_92105@yahoo.com </email>
      </address>
    </author>

    <date year="2012"/>
    <workgroup>Individual</workgroup>

    <abstract>
      <t>
	Defines link type registrations for the OAuth 2 
	authentication framework.
      </t>
    </abstract>
  </front>

  <middle>

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

    <section title="Introduction">

<t>This document defines the link type <xref target="RFC5988"/> registrations for the 
   OAuth 2 <xref target="I-D.ietf-oauth-v2"/> authentication framework.  It 
   also defines link type registrations for OAuth 1.0a <xref target="RFC5849"/>.  
   These link types are used during the endpoint discovery process using Web Host Metadata 
   <xref target="RFC6415"/> and Webfinger <xref target="I-D.jones-appsawg-webfinger"/>
   by clients needing to discover the authorization, token, and initiation endpoints for a service or site.  
   </t> 
          

    </section>

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

    <section anchor="terminology" title="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"/>.</t>
      <t>The reader is assumed to be familiar with the terms used in the OAuth 2.0 specification <xref
          target="I-D.ietf-oauth-v2"/>.</t>
      <t>In examples, "C:" and "S:" indicate lines sent by the client and server respectively. Line
        breaks have been inserted for readability.</t>
      <t>Note that the IMAP SASL specification requires base64 encoding message, not this memo.</t>
    </section>

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


    <section title="Security Considerations">
      <t> This document is informational, defining values in existing registries, and as such
	  has no security properties to discuss.
	</t>

    </section>

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

    <section title="IANA Considerations">
     <section title="Link Type Registration">
      <t> Pursuant to <xref target="RFC5988"/> The following link type registrations 
      [[will be]] registered by mail to link-relations@ietf.org.
      </t>

      <section title="OAuth 2 Authorization Endpoint">
      <t>
      <list style='symbols'>
          <t>
	      Relation Name: oauth2-authorize
          </t>
          <t>
	      Description: An OAuth 2.0 authorization endpoint. 
          </t>
          <t>
	      Reference: <xref target="I-D.ietf-oauth-v2"/>
          </t>
          <t>
	      Notes: This link type indicates an OAuth 2.0 authorization endpoint
	      that can be used for user authentication/authorization for the endpoint
	      providing the link.
          </t>
          <t>
	      Application Data: [optional]
          </t>
	</list>
        </t>
      </section>
      <section title="OAuth 2 Token Endpoint">
      <t>
        <list style='symbols'>
          <t>Relation Name: oauth2-token</t>
          <t>
	      Description: The OAuth token endpoint used to get tokens for access.
          </t>
          <t>
	      Reference: <xref target="I-D.ietf-oauth-v2"/>
          </t>
          <t>
	      Notes: The OAuth 2.0 token endpoint to be used for obtaining tokens
	      to access the endpoint providing the link.
          </t>
          <t>
	      Application Data: This link type has two link-extensions:

		<list style="hanging">
		  <t hangText="grant-types:">A space separated list of OAuth 2.0 grant 
			types (see section 4 of <xref target="I-D.ietf-oauth-v2"/>) that can be used at the token endpoint
	      		to obtain a token.  This is not an exclusive list, it provides a hint
	      		to the application of what SHOULD be valid.  A token endpoint MAY support
	      		additional grant types not advertised by a discovery service.  The client 
			MAY use this to determine if the client supports the grant types avaiable.
		  </t>
		  <t hangText="token-types:">A space separated list of OAuth 2.0 token types 
			(see section 7.1 of <xref target="I-D.ietf-oauth-v2"/>)
			that may be issued by the token endpoint.  It is possible for an token endpoint
			to issue multiple tokens, and types may vary based on scope or other factors.
	      		This is not an exclusive list, it provides a hint
	      		to the application of what SHOULD be valid, and it MAY be used by a client 
			to determine if the client supports the token type(s) available.
		  </t>
		</list>

          </t>
	</list>
      </t>
      </section>
      <section title="OAuth 1.0a Request Initiation Endpoint">
      <t>
        <list style='symbols'>
          <t>Relation Name: oauth-initiate</t>
          <t>
	      Description: The OAuth 1.0a request initiation endpoint used to get an access request.
          </t>
          <t>Reference: <xref target="RFC5849"/></t>
          <t>
	      Notes: The OAuth 1.0a  endpoint used to initiate the sequence, this temporary
	      request is what the user approves to grant access to the resource.
          </t>
          <t>Application Data: </t>
	</list>
      </t>
      </section>
      <section title="OAuth 1.0a Authorization Endpoint">
      <t>
        <list style='symbols'>
          <t>Relation Name: oauth-authorize</t>
          <t>
	      Description: The OAuth 1.0a authorization endpoint used to approve an access request.
          </t>
          <t>Reference: <xref target="RFC5849"/></t>
          <t>
	      Notes: 
          </t>
          <t>Application Data: </t>
	</list>
      </t>
      </section>
      <section title="OAuth 1.0a Token Endpoint">
      <t>
        <list style='symbols'>
          <t>Relation Name: oauth-token</t>
          <t>
	      Description: The OAuth 1.0a token endpoint used to exchange an approved access request for a token.
          </t>
          <t>Reference: <xref target="RFC5849"/></t>
          <t>
	      Notes: 
          </t>
          <t>Application Data: </t>
	</list>
      </t>
      </section>
     </section>

    </section>



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

<section title="Examples">

      <t>Below we have an example of a server advertizing the OAuth 2 endpoints as a 
	result of a query against "acct:carol@example.com".
      </t>
      <t>
        <figure anchor="wfexample" title="Example of a WebFinger type query result">
          <artwork><![CDATA[
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8

{
  "subject" : "acct:carol@example.com",
  "links" :
  [
    {
      "rel" : "oauth2-athorize",
      "href" : "http://login.example.com/oauth2/authorize"
    },
    {
      "rel" : "oauth2-token",
      "href" : "https://login.example.com/oauth2/token"
      "grant-types" : "code password"
      "token-types" : "bearer"
    }
  ]
}
]]></artwork>
        </figure>
      </t>

      <t>In the case of a failed authorizationto access an HTTP based service, the example below shows
	an extremely minimal HTTP response. (Long lines wrapped for readability.)
      </t>
      <t>
        <figure anchor="linkexample" title="Example of LINK headers as a result of a failed HTTP authorization">
          <artwork><![CDATA[
HTTP/1.1 401 Unauthorized
WWW-Authenticate: BEARER realm="example.com"
Link: <https://login.example.com/oauth> rel="oauth2-authorize"
Link: <https://login.example.com/oauth> rel="oauth2-token" 
      grant-types="code password" token-types="bearer"
]]></artwork>
        </figure>
      </t>

    </section>

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

  </middle>

  <back>

    <references title="Normative References">
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5849.xml' ?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml' ?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-oauth-v2.xml' ?>
    </references>

    <references title="Informative References">
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.6415.xml' ?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.jones-appsawg-webfinger.xml' ?>          
    </references>

    <section  title='Document History'>
      <t>
        [[ to be removed by RFC editor before publication as an RFC ]]
      </t>

      <t>
        -01
      </t>
      <t>
        <list style='symbols'>
          <t>
            Editorial changes, corrected authenticatre to authrorize is most places, and added examples.
          </t>
        </list>
      </t>

      <t>
        -00
      </t>
      <t>
        <list style='symbols'>
          <t>
            Initial revision
          </t>
        </list>
      </t>
    </section>

  </back>
</rfc>