diff options
| -rw-r--r-- | doc/specs/draft-hardt-oauth-01.htm | 2313 | ||||
| -rw-r--r-- | doc/specs/draft-ietf-oauth.html | 3419 | ||||
| -rw-r--r-- | src/DotNetOpenAuth.sln | 3 |
3 files changed, 3420 insertions, 2315 deletions
diff --git a/doc/specs/draft-hardt-oauth-01.htm b/doc/specs/draft-hardt-oauth-01.htm deleted file mode 100644 index e13cdf0..0000000 --- a/doc/specs/draft-hardt-oauth-01.htm +++ /dev/null @@ -1,2313 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<!-- saved from url=(0137)https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor34 --> -<HTML><HEAD><META http-equiv="Content-Type" content="text/html; charset=UTF-8"></HEAD><BODY> - - - - - - - -<DIV> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<TABLE summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><TBODY><TR><TD><TABLE summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1"> -<TBODY><TR><TD>Internet Engineering Task Force</TD><TD>D. Hardt, Ed.</TD></TR> -<TR><TD>Internet-Draft</TD><TD>Microsoft</TD></TR> -<TR><TD>Intended status: Informational</TD><TD>A. Tom</TD></TR> -<TR><TD>Expires: July 19, 2010</TD><TD>Yahoo!</TD></TR> -<TR><TD> </TD><TD>B. Eaton</TD></TR> -<TR><TD> </TD><TD>Google</TD></TR> -<TR><TD> </TD><TD>Y. Goland</TD></TR> -<TR><TD> </TD><TD>Microsoft</TD></TR> -<TR><TD> </TD><TD>January 15, 2010</TD></TR> -</TBODY></TABLE></TD></TR></TBODY></TABLE> -<H1><BR>OAuth Web Resource Authorization - Profiles<BR>draft-hardt-oauth-01</H1> - -<H3>Abstract</H3> - -<P>The OAuth Web Resource Authorization Profiles (OAuth WRAP) allow a - server hosting a Protected Resource to delegate authorization to one or - more authorities. An application (Client) accesses the Protected - Resource by presenting a short lived, opaque, bearer token (Access - Token) obtained from an authority (Authorization Server). There are - Profiles for how a Client may obtain an Access Token when acting - autonomously or on behalf of a User. -</P> -<H3>Status of this Memo</H3> -<P> -This Internet-Draft is submitted to IETF in full -conformance with the provisions of BCP 78 and BCP 79.</P> -<P> -Internet-Drafts are working documents of the Internet Engineering -Task Force (IETF), its areas, and its working groups. -Note that other groups may also distribute working documents as -Internet-Drafts.</P> -<P> -Internet-Drafts are draft documents valid for a maximum of six months -and may be updated, replaced, or obsoleted by other documents at any time. -It is inappropriate to use Internet-Drafts as reference material or to cite -them other than as “work in progress.”</P> -<P> -The list of current Internet-Drafts can be accessed at -<A href="http://www.ietf.org/ietf/1id-abstracts.txt" target="_blank">http://www.ietf.org/ietf/1id-<WBR>abstracts.txt</A>.</P> -<P> -The list of Internet-Draft Shadow Directories can be accessed at -<A href="http://www.ietf.org/shadow.html" target="_blank">http://www.ietf.org/shadow.<WBR>html</A>.</P> -<P> -This Internet-Draft will expire on July 19, 2010.</P> - -<H3>Copyright Notice</H3> -<P> -Copyright (c) 2010 IETF Trust and the persons identified as the -document authors. All rights reserved.</P> -<P> -This document is subject to BCP 78 and the IETF Trust's Legal -Provisions Relating to IETF Documents in effect on the date of -publication of this document (<A href="http://trustee.ietf.org/license-info" target="_blank">http://trustee.ietf.org/<WBR>license-info</A>). -Please review these documents carefully, as they describe your -rights and restrictions with respect to this document.</P> -<A name="0.2_toc"></A><BR><HR> -<H3>Table of Contents</H3> -<P> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor1">1.</A> -Overview<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor2">1.1.</A> -Accessing a Protected Resource<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor3">1.2.</A> -Autonomous Client Profiles<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor4">1.3.</A> -User Delegation Profiles<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor5">2.</A> -Requirements Language<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor6">3.</A> -Definitions<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor7">3.1.</A> -URLs<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ProtectedResource">4.</A> -Accessing a Protected Resource<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor8">4.1.</A> -Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor9">4.2.</A> -Acquiring an Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor10">4.3.</A> -Client Calls Protected Resource Using HTTP Header<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor11">4.4.</A> -Client Calls Protected Resource Using URL Query Parameter<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor12">4.5.</A> -Client Calls Protected Resource Using Post Parameter<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_autonomous.profiles">5.</A> -Acquiring an Access Token: Autonomous Client Profiles<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p1">5.1.</A> -Client Account and Password Profile<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor13">5.1.1.</A> -Provisioning<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p1request">5.1.2.</A> -Client Requests Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor14">5.1.3.</A> -Successful Access Token Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor15">5.1.4.</A> -Unsuccessful Access Token Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor16">5.1.5.</A> -Client Refreshes Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p2">5.2.</A> -Assertion Profile<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor17">5.2.1.</A> -Provisioning<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p2.assertion">5.2.2.</A> -Client Obtains Assertion<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p2.request">5.2.3.</A> -Client Requests Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor18">5.2.4.</A> -Successful Access Token Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor19">5.2.5.</A> -Unsuccessful Access Token Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor20">5.2.6.</A> -Client Refreshes Access Token<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_user.profiles">6.</A> -Acquiring an Access Token: User Delegation Profiles<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3">6.1.</A> -Username and Password Profile<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor21">6.1.1.</A> -Provisioning<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3.password">6.1.2.</A> -Client Obtains Username and Password<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3.request">6.1.3.</A> -Client Requests Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor22">6.1.4.</A> -Successful Access Token Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor23">6.1.5.</A> -Unsuccessful Access Token Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor24">6.1.6.</A> -Verification URL Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor25">6.1.7.</A> -CAPTCHA Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor26">6.1.8.</A> -Client Refreshes Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor27">6.1.9.</A> -Successful Access Token Refresh<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor28">6.1.10.</A> -Unsuccessful Access Token Refresh<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4">6.2.</A> -Web App Profile<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor29">6.2.1.</A> -Provisioning<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4.authorization">6.2.2.</A> -Client Directs the User to the Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor30">6.2.3.</A> -Authorization Server Confirms Authorization Request with User<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor31">6.2.4.</A> -Authorization Server Directs User back to the Client<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4.request">6.2.5.</A> -Client Requests Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor32">6.2.6.</A> -Successful Access Token Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor33">6.2.7.</A> -Unsuccessful Access Token Response from Authorization Server<BR> - <A href="./draft-hardt-oauth-01_files/draft-hardt-oauth-01.htm">6.2.8.</A> -Client Refreshes Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor35">6.2.9.</A> -Successful Access Token Refresh<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor36">6.2.10.</A> -Unsuccessful Access Token Refresh<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5">6.3.</A> -Rich App Profile<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor37">6.3.1.</A> -Provisioning<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5.authorization">6.3.2.</A> -Client Directs the User to the Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor38">6.3.3.</A> -Authorization Server Confirms Authorization Request with User<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5.request">6.3.4.</A> -Client Requests Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5.verification">6.3.5.</A> -Successful Access Token Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor41">6.3.6.</A> -Unsuccessful Access Token Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor42">6.3.7.</A> -Client Refreshes Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor43">6.3.8.</A> -Successful Access Token Refresh<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor44">6.3.9.</A> -Unsuccessful Access Token Refresh<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ParamCon">7.</A> -Parameter Considerations<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor45">7.1.</A> -Authorization Server Request / Response Parameter Encoding<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor46">7.2.</A> -Parameter Size<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor47">7.3.</A> -Access Token Format<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor48">7.4.</A> -Refresh Token Format<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor49">7.5.</A> -Additional Authorization Server Parameters<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor50">7.6.</A> -Parameter Names and Order<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_IANA">8.</A> -IANA Considerations<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_Security">9.</A> -Security Considerations<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_rfc.references1">10.</A> -References<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_rfc.references1">10.1.</A> -Normative References<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_rfc.references2">10.2.</A> -Informative References<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor53">Appendix A.</A> -Client Account and Password Profile Example<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor54">A.1.</A> -Provisioning<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor55">A.2.</A> -Client Requests Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor56">A.3.</A> -Successful Access Token Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor57">A.4.</A> -Client Calls Protected Resource<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor58">Appendix B.</A> -Web App Profile Example<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor59">B.1.</A> -Provisioning<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor60">B.2.</A> -Client Directs the User to the Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor61">B.3.</A> -Authorization Server Confirms Delegation Request with User<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor62">B.4.</A> -Server Directs User back to the Client<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor63">B.5.</A> -Client Requests Access Token<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor64">B.6.</A> -Successful Access Token Response from Authorization Server<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor65">B.7.</A> -Client Calls Protected Resource<BR> - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_anchor66">B.8.</A> -Client Refreshes Access Token<BR> -<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_rfc.authors">§</A> -Authors' Addresses<BR> -</P> -<BR clear="all"> - -<A name="0.2_anchor1"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.1"></A><H3>1. -Overview</H3> - -<P>As the internet has evolved, there is a growing trend for a variety - of applications (Clients) to access resources through an API over HTTP - or other protocols. Often these resources require authorization for - access and are Protected Resources. The systems that are trusted to make - authorization decisions may be independent from the Protected Resources - for scale and security reasons. The OAuth Web Resource Authorization - Profiles (OAuth WRAP) enable a Protected Resource to delegate the - authorization to access a Protected Resource to one or more trusted - authorities. -</P> -<P>Clients that wish to access a Protected Resource first obtain - authorization from a trusted authority (Authorization Server). Different - credentials and profiles can be used to obtain this authorization, but - once authorized, the Client is provided an Access Token, and possible a - Refresh Token to obtain new Access Tokens. The Authorization Server - typically includes authorization information in the Access Token and - digitally signs the Access Token. Protected Resource can verify that an - Access Token received from a Client was issued by a trusted - Authorization Server and is valid. The Protected Resource can then - examine the contents of the Access Token to determine the authorization - that has been granted to the Client. -</P> -<A name="0.2_anchor2"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.1.1"></A><H3>1.1. -Accessing a Protected Resource</H3> - -<P>The Access Token is opaque to the Client, and can be any format - agreed to between the Authorization Server and the Protected Resource - enabling existing systems to reuse suitable tokens, or use a standard - token format such as a Simple Web Token or JSON Web Token. Since the - Access Token provides the Client authorization to the Protected - Resource for the life of the Access Token, the Authorization Server - should issue Access Tokens that expire within an appropriate time. - When an Access Token expires, the Client requests a new Access Token - from the Authorization Server, which once again computes the Client's - authorization, and issues a new Access Token. <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_fig1">Figure 1</A> below shows the flow between the Client and - Authorization Server (A,B); and then between the Client and Protected - Resource (C,D): -</P><BR><HR> -<A name="0.2_fig1"></A> -<DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> +---+ +---------------+ - | C |--(A)------ credentials --------->| Authorization | - | l |<-(B)------ Access Token ---------| Server | - | i | +---------------+ - | e | - | n | Access Token +-----------+ - | t |--(C)----- in HTTP header ------->| Protected | - | |<-(D)------ API response ---------| Resource | - +---+ +-----------+ -</PRE></DIV><TABLE border="0" cellpadding="0" cellspacing="2" align="center"><TBODY><TR><TD align="center"><FONT face="monaco, MS Sans Serif" size="1"><B> Figure 1 </B></FONT><BR></TD></TR></TBODY></TABLE><HR> - -<P>In step A, the Client presents credentials to the Authorization - Server in exchange for an Access Token. -</P> -<P> A Profile specifies the credentials to be provided in step A, and - how the Client obtains them. This specification defines a number of - Profiles; additional Profiles may be defined to support additional - scenarios. The Profiles in this specification are separated into two - groups: autonomous profiles where the Client as acting for itself, and - user delegation profiles where the Client is acting on behalf of a - User. -</P> -<A name="0.2_anchor3"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.1.2"></A><H3>1.2. -Autonomous Client Profiles</H3> - -<P>The following two Profiles (see <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_autonomous.profiles">Section 5<SPAN> (</SPAN><SPAN>Acquiring an Access Token: Autonomous Client Profiles</SPAN><SPAN>)</SPAN></A>) are recommended for scenarios - involving a Client acting autonomously. -</P> -<P>Client Account and Password Profile (<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p1">Section 5.1<SPAN> (</SPAN><SPAN>Client Account and Password Profile</SPAN><SPAN>)</SPAN></A>): This - is the simplest Profile. The Client is provisioned with an account name - and corresponding password by the Authorization Server. The Client - presents the account name and password to the Access Token URL at the - Authorization Server in exchange for an Access Token. This Profile is - not intended for a Client acting on behalf of a User. See the User - Delegation Profiles. -</P> -<P>Assertion Profile (<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p2">Section 5.2<SPAN> (</SPAN><SPAN>Assertion Profile</SPAN><SPAN>)</SPAN></A>): This profile enables a - Client with a <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_OASIS.saml-core-2.0-os">SAML<SPAN> (</SPAN><SPAN>Cantor, S., Kemp, J., Philpott, R., and E. Maler, “Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.</SPAN><SPAN>)</SPAN></A> [OASIS.saml‑core‑2.0‑os] or other - assertion recognized by the Authorization Server. The Client presents - the assertion to the Access Token URL at the Authorization Server in - exchange for an Access Token. How the Client obtains the assertion is - out of scope of OAuth WRAP. -</P> -<P>Access Tokens are short lived bearer tokens. When the Protected - Resource is presented with an expired Access Token by the Client, the - Protected Resource returns an error. The Client presents the assertion - once again to the Authorization Server to obtain a new Access - Token. -</P> -<A name="0.2_anchor4"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.1.3"></A><H3>1.3. -User Delegation Profiles</H3> - -<P>Common scenarios involve the User delegating to a Client to act on - the User's behalf, adding another party (the User) to the protocol. In - these Profiles (see <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_user.profiles">Section 6<SPAN> (</SPAN><SPAN>Acquiring an Access Token: User Delegation Profiles</SPAN><SPAN>)</SPAN></A>), the Client - receives a Refresh Token when it acquires the first Access Token. When - an Access Token expires, the Client presents the Refresh Token to - acquire a new Access Token. Refresh Tokens are sensitive as they - represent long-lived permissions to access a Protected Resource and - are always transmitted using HTTPS. -</P> -<P>Username and Password Profile (<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3">Section 6.1<SPAN> (</SPAN><SPAN>Username and Password Profile</SPAN><SPAN>)</SPAN></A>): While - the User may use a username and password to authenticate to the - Authorization Server, it is undesirable for the Client to store the - User's username and password. In this profile the User provides their - username and password to an application (Client) they have installed - on their device. The Client presents a Client Identifier, the username - and password (credentials) to the Access Token URL at the - Authorization Server in exchange for an Access Token and a Refresh - Token as depicted in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_fig2">Figure 2</A> below. -</P><BR><HR> -<A name="0.2_fig2"></A> -<DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> +---+ +---------------+ - | C |--(A)------ credentials --------->| Authorization | - | l |<-(B)------ Access Token ---------| Server | - | i | Refresh Token +---------------+ - | e | - | n | Access Token +-----------+ - | t |--(C)----- in HTTP header ------->| Protected | - | |<-(D)------ API response ---------| Resource | - +---+ +-----------+ - -</PRE></DIV><TABLE border="0" cellpadding="0" cellspacing="2" align="center"><TBODY><TR><TD align="center"><FONT face="monaco, MS Sans Serif" size="1"><B> Figure 2 </B></FONT><BR></TD></TR></TBODY></TABLE><HR> - -<P>When the Access Token expires, the Client presents the Refresh - Token to the Refresh Token URL at the Authorization Server in exchange - for a new Access Token (<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_fig3">Figure 3</A>, steps A and B). - The Client then uses the new Access Token to access the Protected - Resource (<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_fig3">Figure 3</A>, steps C and D). -</P><BR><HR> -<A name="0.2_fig3"></A> -<DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> +---+ +---------------+ - | C |--(A)----- Refresh Token -------->| Authorization | - | l |<-(B)------ Access Token ---------| Server | - | i | +---------------+ - | e | - | n | Access Token +-----------+ - | t |--(C)----- in HTTP header ------->| Protected | - | |<-(D)------ API response ---------| Resource | - +---+ +-----------+ - -</PRE></DIV><TABLE border="0" cellpadding="0" cellspacing="2" align="center"><TBODY><TR><TD align="center"><FONT face="monaco, MS Sans Serif" size="1"><B> Figure 3 </B></FONT><BR></TD></TR></TBODY></TABLE><HR> - -<P>Web App Profile (<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4">Section 6.2<SPAN> (</SPAN><SPAN>Web App Profile</SPAN><SPAN>)</SPAN></A>): It is undesirable for - a User to provide their Authorization Server username and password to - web applications. Additionally, the User may authenticate to the - Authorization Server using other mechanisms than a username and - password. In this profile, a web application (Client) has been - provisioned with a Client Identifier and Client Secret and may have - registered a Callback URL. <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_fig4">Figure 4</A> below - illustrates the protocol. (A) The Client initiates the protocol by - redirecting the User to the User Authorization URL at the - Authorization Server passing the Client Identifier and the Callback - URL. (B) The Authorization Server authenticates the User, confirms the - User would like to authorize the Client to access the Protected - Resource, and generates a Verification Code. (C) The Authorization - Server then redirects the User to the Callback URL at the Client - passing along the Verification Code. -</P><BR><HR> -<A name="0.2_fig4"></A> -<DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> +---------+ - | Web App | - | Client | - +---------+ - v ^ - | | - (A) (C) - | | - \ \ - +---------+ +---------------+ - | |\---(C)-- Verification Code ----<| | - | User | | Authorization | - | at |<---(B)-- User authenticates --->| Server | - | Browser | | | - | |\---(A)-- Client Identifier ---->| | - +---------+ +---------------+ -</PRE></DIV><TABLE border="0" cellpadding="0" cellspacing="2" align="center"><TBODY><TR><TD align="center"><FONT face="monaco, MS Sans Serif" size="1"><B> Figure 4 </B></FONT><BR></TD></TR></TBODY></TABLE><HR> - -<P>Similar to step A in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_fig2">Figure 2</A>, the Client then - presents the Client Identifier, Client Secret, Callback URL and - Verification code (credentials) to the Access Token URL at the - Authorization Server for an Access Token and a Refresh Token. -</P> -<P>Rich App Profile (<A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5">Section 6.3<SPAN> (</SPAN><SPAN>Rich App Profile</SPAN><SPAN>)</SPAN></A>): This profile is - suitable when the Client is an application the User has installed on - their device and a web browser is available, but it is undesirable for - the User to provide their username and password to an application, or - the user may not be using a username and password to authenticate to - the Authorization Server. -</P> -<P>The Client initiates the protocol by directing the User's browser - to the Authorization URL at the Authorization Server passing the - Client Identifier and potentially a Callback URL. The Authorization - Server authenticates the User, confirms the User would like to - authorize the Client to access the Protected Resource, and generates a - Verification Code. The Verification Code may be communicated back to - the Client in a number of ways: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>a.</DT> -<DD>the Authorization Server presents the Verification Code to the - User, who is instructed to enter the Verification Code directly in - the Client; -</DD> -<DT>b.</DT> -<DD>the Client reads the Verification Code from the title of the - web page presented by the Authorization Server; -</DD> -<DT>c.</DT> -<DD>the Authorization Server redirects the User to the Callback URL - that presents Client specific language for the User to enter the - Verification Code into the Client; or -</DD> -<DT>d.</DT> -<DD>the Client has registered a custom scheme and the Authorization - Server redirects the browser to the custom scheme that causes the - User's browser to load the Client application with the - Verification Code as a parameter. -</DD> -</DL></BLOCKQUOTE> - -<P>Similar to step A in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_fig2">Figure 2</A>, the Client then - presents the Client Identifier, Callback URL (if provided) and - Verification code (credentials) to the Access Token URL at the - Authorization Server for an Access Token and a Refresh Token. -</P> -<A name="0.2_anchor5"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.2"></A><H3>2. -Requirements Language</H3> - -<P>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 <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_RFC2119">[RFC2119]<SPAN> (</SPAN><SPAN>Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.</SPAN><SPAN>)</SPAN></A>. Domain name examples use <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_RFC2606">[RFC2606]<SPAN> (</SPAN><SPAN>Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,” June 1999.</SPAN><SPAN>)</SPAN></A>. -</P> -<A name="0.2_anchor6"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.3"></A><H3>3. -Definitions</H3> - -<P></P> -<BLOCKQUOTE><DL> -<DT>Access Token:</DT> -<DD>a short lived bearer token issued by the - Authorization Server to the Client. The Access Token is presented by - the Client to the Protected Resource to access protected - resources. -</DD> -<DT>Authorization Server:</DT> -<DD>an authorization resource that - issues Access Tokens to Clients after successful authorization. May - be the same entity as the Protected Resource. -</DD> -<DT>Client:</DT> -<DD>an application that would like access to a - Protected Resource. Client Identifier:"> a value used by a Client - to identify itself to the Authorization Server. This may be a human - readable string or an opaque identifier. -</DD> -<DT>Client Secret:</DT> -<DD>a secret used by a web application - Client to establish ownership of the Client Identifier. -</DD> -<DT>Profile:</DT> -<DD>a mechanism for a Client to obtain an Access - Token from an Authorization Server. -</DD> -<DT>Protected Resource:</DT> -<DD>a protected API that allows access - via OAuth WRAP. May be the same entity as the Authorization Server. - Refresh Token:"> a long lived bearer token used by a Client to - acquire an Access Token from an Authorization Server. -</DD> -<DT>User:</DT> -<DD>an individual who has an account with the - Authorization Server. -</DD> -<DT>Verification Code:</DT> -<DD>a code used by a Client to verify - the User has authorized the Client to have specific access to a - Protected Resource. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor7"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.3.1"></A><H3>3.1. -URLs</H3> - -<P></P> -<BLOCKQUOTE><DL> -<DT>Access Token URL:</DT> -<DD>the Authorization Server URL at - which an Access Token is requested by the Client. The URL may - accept a variety of parameters depending on the Profile. A Refresh - Token may also be returned to the Client. This URL MUST be an - HTTPS URL and MUST always be called with POST. -</DD> -<DT>Callback URL:</DT> -<DD>the Client URL where the User will be - redirected after an authorization request to the Authorization - Server. -</DD> -<DT>Refresh Token URL:</DT> -<DD>the Authorization Server URL at - which a Refresh Token is presented in exchange for a new Access - Token is requested. This URL MUST be an HTTPS URL and MUST always - be called with POST. -</DD> -<DT>User Authorization URL:</DT> -<DD>the Authorization Server URL - where the Client redirects the User to make an authorization - request. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_ProtectedResource"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.4"></A><H3>4. -Accessing a Protected Resource</H3> - -<P>Clients always present an Access Token to access a Protected - Resource. Use of the Authorization header is RECOMMENDED, since HTTP - implementations are aware that Authorization headers have special - security properties and may require special treatment in caches and - logs. Protected Resources SHOULD take precautions to insure that Access - Tokens are not inadvertently logged or captured. In addition to the - methods presented here, the Protected Resource MAY allow the Client to - present the Access Token using any scheme agreed on by the Client and - Protected Resource. -</P> -<A name="0.2_anchor8"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.4.1"></A><H3>4.1. -Access Token</H3> - -<P>The exact format of the Access Token is opaque to Clients and is - out of scope of this specification. However, Protected Resources MUST - be able to verify that the Access Token was issued by a trusted - Authorization Server and is still valid. Access Tokens SHOULD - periodically expire. The expiry time of Access Tokens is determined as - an appropriate balance between excessive resource utilization if too - short and unauthorized access if too long. -</P> -<A name="0.2_anchor9"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.4.2"></A><H3>4.2. -Acquiring an Access Token</H3> - -<P>An Authorization Server may support one or more protocol profiles - that enable a Client to obtain an Access Token that can be used to - access a Protected Resource. -</P> -<P>Client developers only need to implement the profile(s) that align - with how their application will be deployed and are supported by the - Authorization Server. -</P> -<P>Authorization Server developers only need to implement the - profile(s) that are appropriate for them. -</P> -<P>Protected Resource developers do not implement a profile as the - Client always interacts with the Protected Resource by presenting an - Access Token. -</P> -<P><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ParamCon">Section 7<SPAN> (</SPAN><SPAN>Parameter Considerations</SPAN><SPAN>)</SPAN></A> has general information about - parameters passed to and from the Authorization Server. -</P> -<P>See <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_autonomous.profiles">Section 5<SPAN> (</SPAN><SPAN>Acquiring an Access Token: Autonomous Client Profiles</SPAN><SPAN>)</SPAN></A> for how the Client - acquires an Access Token when acting autonomously, and <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_user.profiles">Section 6<SPAN> (</SPAN><SPAN>Acquiring an Access Token: User Delegation Profiles</SPAN><SPAN>)</SPAN></A> for how the Client acquires an Access - Token when acting acting on behalf of a User. -</P> -<A name="0.2_anchor10"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.4.3"></A><H3>4.3. -Client Calls Protected Resource Using HTTP Header</H3> - -<P>The Protected Resource SHOULD enable Clients to access the - Protected Resource by including the Access Token in the HTTP - Authorization header using the OAuth WRAP scheme with the following - parameter: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>access_token</DT> -<DD> REQUIRED. The value of the - Access Token -</DD> -</DL></BLOCKQUOTE> - -<P>For example, if the Access Token is the string 123456789, the HTTP - header would be: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> Authorization: WRAP access_token="123456789" -</PRE></DIV> -<P>Note that per section 1.2 of <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_RFC2617">[RFC2617]<SPAN> (</SPAN><SPAN>Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</SPAN><SPAN>)</SPAN></A> that - the following header is also valid: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> Authorization: WRAP access_token = 123456789 -</PRE></DIV> -<P>If the Access Token has expired or is invalid, the Protected - Resource MUST return: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> WWW-Authenticate: WRAP -</PRE></DIV> -<A name="0.2_anchor11"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.4.4"></A><H3>4.4. -Client Calls Protected Resource Using URL Query Parameter</H3> - -<P>The Protected Resource MAY allow the Client to access protected - resources at the Protected Resource by including the following HTTP - URL query parameter in the URL: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>access_token</DT> -<DD> REQUIRED. The value of the - Access Token -</DD> -</DL></BLOCKQUOTE> - -<P>If the Access Token has expired or is invalid, the Protected - Resource MUST return: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> WWW-Authenticate: WRAP -</PRE></DIV> -<A name="0.2_anchor12"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.4.5"></A><H3>4.5. -Client Calls Protected Resource Using Post Parameter</H3> - -<P>The Protected Resource MAY allow the Client to access protected - resources at the Protected Resource by including the following - parameter in the body of a HTTP post message formatted as - application/x-www-form-<WBR>urlencoded per <A href="http://www.w3.org/TR/1999/REC-W3C.REC-html40-19980424-19991224/interact/forms.html#h-17.13.4.1" target="_blank">17.13.4</A> - of <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_W3C.REC-html40-19980424">HTML 4.01<SPAN> (</SPAN><SPAN>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</SPAN><SPAN>)</SPAN></A> [W3C.REC‑html40‑19980424]: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>access_token</DT> -<DD> REQUIRED. The value of the - Access Token -</DD> -</DL></BLOCKQUOTE> - -<P>If the Access Token has expired or is invalid, the Protected - Resource MUST return: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> WWW-Authenticate: WRAP -</PRE></DIV> -<A name="0.2_autonomous.profiles"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5"></A><H3>5. -Acquiring an Access Token: Autonomous Client Profiles</H3> - -<P>These are the profiles the Client uses when acting autonomously. -</P> -<A name="0.2_p1"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.1"></A><H3>5.1. -Client Account and Password Profile</H3> - -<P>This profile is suitable when the Client is an application calling - the Protected Resource on behalf of an organization and the - Authorization Server accepts account passwords for authentication. - This enables the Authorization Server to use an existing - authentication mechanism. This profile SHOULD NOT be used when the - Client is acting on behalf of a user. Profiles <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3">6.1<SPAN> (</SPAN><SPAN>Username and Password Profile</SPAN><SPAN>)</SPAN></A>, <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4">6.2<SPAN> (</SPAN><SPAN>Web App Profile</SPAN><SPAN>)</SPAN></A> or - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5">6.3<SPAN> (</SPAN><SPAN>Rich App Profile</SPAN><SPAN>)</SPAN></A> are RECOMMENDED when a - Client is acting on behalf of a User. -</P> -<A name="0.2_anchor13"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.1.1"></A><H3>5.1.1. -Provisioning</H3> - -<P>Prior to initiating this protocol profile, the Client MUST have - obtained an account name and account password from the Authorization - Server. -</P> -<A name="0.2_p1request"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.1.2"></A><H3>5.1.2. -Client Requests Access Token</H3> - -<P>The Client makes an HTTPS request to the Authorization Server's - Access Token URL using POST. The request contains the following - parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_name</DT> -<DD> REQUIRED. The account - name. -</DD> -<DT>wrap_password</DT> -<DD> REQUIRED. The account - password. -</DD> -<DT>wrap_scope</DT> -<DD> OPTIONAL. The Authorization - Server MAY define authorization scope values for the Client to - include. -</DD> -<DT>Additional parameters</DT> -<DD>Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor14"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.1.3"></A><H3>5.1.3. -Successful Access Token Response from Authorization Server</H3> - -<P>If successful, the Authorization Server returns: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 200 OK -</PRE></DIV> -<P>with the Refresh Token and an Access Token in the response body. - The response body contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_refresh_token</DT> -<DD> REQUIRED. The - Refresh Token. -</DD> -<DT>wrap_access_token</DT> -<DD> REQUIRED. The Access - Token. -</DD> -<DT>wrap_access_token_expires_in</DT> -<DD> OPTIONAL. - The lifetime of the Access Token in seconds. For example, 3600 - represents one hour. -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<P>The Client may now use the Access Token to access the Protected - Resource per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ProtectedResource">Section 4<SPAN> (</SPAN><SPAN>Accessing a Protected Resource</SPAN><SPAN>)</SPAN></A> -</P> -<A name="0.2_anchor15"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.1.4"></A><H3>5.1.4. -Unsuccessful Access Token Response from Authorization Server</H3> - -<P>If the Client account name and password are invalid, the - Authorization Server MUST respond with: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> WWW-Authenticate: WRAP -</PRE></DIV> -<P>The Client MUST obtain a valid account name and password before - retrying the request. -</P> -<A name="0.2_anchor16"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.1.5"></A><H3>5.1.5. -Client Refreshes Access Token</H3> - -<P>Authorization Servers SHOULD issue Access Tokens that expire and - require Clients to refresh them. Upon receiving the HTTP 401 - response when accessing protected resources per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ProtectedResource">Section 4<SPAN> (</SPAN><SPAN>Accessing a Protected Resource</SPAN><SPAN>)</SPAN></A>, the Client should request a new - Access Token by repeating <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p1request">Section 5.1.2<SPAN> (</SPAN><SPAN>Client Requests Access Token</SPAN><SPAN>)</SPAN></A> -</P> -<A name="0.2_p2"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.2"></A><H3>5.2. -Assertion Profile</H3> - -<A name="0.2_anchor17"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.2.1"></A><H3>5.2.1. -Provisioning</H3> - -<P>Prior to initiating this protocol profile, the Client MUST have a - mechanism for obtained an assertion from an assertion issuer that - can be presented to the Authorization Server for access to the - Protected Resource. -</P> -<A name="0.2_p2.assertion"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.2.2"></A><H3>5.2.2. -Client Obtains Assertion</H3> - -<P>The Client obtains an assertion. The process for obtaining the - assertion is defined by the assertion issuer and the Authorization - Server, and is out of scope of this specification. -</P> -<A name="0.2_p2.request"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.2.3"></A><H3>5.2.3. -Client Requests Access Token</H3> - -<P>The Client makes an HTTPS request to the Authorization Server's - Access Token URL using POST. The request contains the following - parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_assertion_format</DT> -<DD> REQUIRED. The - format of the assertion as defined by the Authorization - Server. -</DD> -<DT>wrap_assertion</DT> -<DD> REQUIRED. The - assertion. -</DD> -<DT>wrap_scope</DT> -<DD> OPTIONAL. The Authorization - Server MAY define authorization scope values for the Client to - include -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor18"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.2.4"></A><H3>5.2.4. -Successful Access Token Response from Authorization Server</H3> - -<P>If successful, the Authorization Server returns: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 200 OK -</PRE></DIV> -<P>with the Access Token in the response body. The response body - contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_access_token</DT> -<DD> REQUIRED. The Access - Token. -</DD> -<DT>wrap_access_token_expires_in</DT> -<DD> OPTIONAL. - The lifetime of the Access Token in seconds. For example, 3600 - represents one hour. -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<P>The Client may now use the Access Token to access the Protected - Resource per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ProtectedResource">Section 4<SPAN> (</SPAN><SPAN>Accessing a Protected Resource</SPAN><SPAN>)</SPAN></A>. -</P> -<A name="0.2_anchor19"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.2.5"></A><H3>5.2.5. -Unsuccessful Access Token Response from Authorization Server</H3> - -<P>If the assertion is not valid, the Authorization Server MUST - respond with: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> WWW-Authenticate: WRAP -</PRE></DIV> -<P>The Client MUST obtain a valid assertion by repeating <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p2.assertion">Section 5.2.2<SPAN> (</SPAN><SPAN>Client Obtains Assertion</SPAN><SPAN>)</SPAN></A> before retrying the request. -</P> -<A name="0.2_anchor20"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.5.2.6"></A><H3>5.2.6. -Client Refreshes Access Token</H3> - -<P>Authorization Servers SHOULD issue Access Tokens that expire and - require Clients to refresh them. Upon receiving the HTTP 401 - response when accessing protected resources per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ProtectedResource">Section 4<SPAN> (</SPAN><SPAN>Accessing a Protected Resource</SPAN><SPAN>)</SPAN></A>, the Client should request a new - Access Token by repeating <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p2.request">Section 5.2.3<SPAN> (</SPAN><SPAN>Client Requests Access Token</SPAN><SPAN>)</SPAN></A> if the - assertion is still valid, otherwise the Client MUST obtain a new, - valid assertion by repeating <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p2.assertion">Section 5.2.2<SPAN> (</SPAN><SPAN>Client Obtains Assertion</SPAN><SPAN>)</SPAN></A>. -</P> -<A name="0.2_user.profiles"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6"></A><H3>6. -Acquiring an Access Token: User Delegation Profiles</H3> - -<P>These are the profiles the Client uses when acting on behalf of a - User. -</P> -<A name="0.2_p3"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.1"></A><H3>6.1. -Username and Password Profile</H3> - -<P>This profile is suitable where the Client is an application the - User has installed on their computer and the User uses a username and - password to authenticate to the Authorization Server. This profile - enables a Client to act on behalf of the User without having to - permanently store the User's username and password. -</P> -<A name="0.2_anchor21"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.1.1"></A><H3>6.1.1. -Provisioning</H3> - -<P>Prior to initiating this protocol profile, the Authorization - Server MAY have required the Client to have obtained a Client - Identifier from the Authorization Server. -</P> -<A name="0.2_p3.password"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.1.2"></A><H3>6.1.2. -Client Obtains Username and Password</H3> - -<P>The Client obtains the User's username and password from the - user. The Client MUST discard the username and password once an - Access Token has been obtained. -</P> -<A name="0.2_p3.request"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.1.3"></A><H3>6.1.3. -Client Requests Access Token</H3> - -<P>The Client makes an HTTPS request to the Authorization Server's - Access Token URL using POST. The request contains the following - parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_client_id</DT> -<DD> REQUIRED. The Client - Identifier. -</DD> -<DT>wrap_username</DT> -<DD> REQUIRED. The User's - username. -</DD> -<DT>wrap_password</DT> -<DD> REQUIRED. The User's - password. -</DD> -<DT>wrap_scope</DT> -<DD> OPTIONAL. The Authorization - Server MAY define authorization scope values for the Client to - include. -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor22"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.1.4"></A><H3>6.1.4. -Successful Access Token Response from Authorization Server</H3> - -<P>If successful, the Authorization Server returns: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 200 OK -</PRE></DIV> -<P>with the Access Token in the response body. The response body - contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_access_token</DT> -<DD> REQUIRED. The Access - Token. -</DD> -<DT>wrap_access_token_expires_in</DT> -<DD> OPTIONAL. - The lifetime of the Access Token in seconds. For example, 3600 - represents one hour. -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<P>The Client MUST discard the User's username and password. The - Client securely stores the Refresh Token for later use. The Client - may now use the Access Token to access the Protected Resource per - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ProtectedResource">Section 4<SPAN> (</SPAN><SPAN>Accessing a Protected Resource</SPAN><SPAN>)</SPAN></A>. -</P> -<A name="0.2_anchor23"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.1.5"></A><H3>6.1.5. -Unsuccessful Access Token Response from Authorization Server</H3> - -<P>The Authorization Server MUST verify User's username and - password. If the verification fails, the Authorization Server MUST - respond with: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> WWW-Authenticate: WRAP -</PRE></DIV> -<P>The Client needs to obtain a valid username and password from the - User per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3.password">Section 6.1.2<SPAN> (</SPAN><SPAN>Client Obtains Username and Password</SPAN><SPAN>)</SPAN></A> before retrying the - request. -</P> -<A name="0.2_anchor24"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.1.6"></A><H3>6.1.6. -Verification URL Response from Authorization Server</H3> - -<P>If the Authorization Server determines that the Client may be - malicious, the Authorization Server MAY require the Client to - instruct the User to visit a Verification URL. The Authorization - Server communicates its requirement by responding to the Client's - Access Token request with the following: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 400 Bad Request -</PRE></DIV> -<P>and the body of the Authorization Server response contains the - following parameter: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_verification_url</DT> -<DD>REQUIRED. The - verification URL that the Client MUST either load in the User's - browser, or display for the User to enter into a browser. -</DD> -</DL></BLOCKQUOTE> - -<P>The Client MUST then wait for the User to indicate they have - successfully completed the verification process at the Authorization - Server and attempt to obtain an Access Token Refresh Token per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3.request">Section 6.1.3<SPAN> (</SPAN><SPAN>Client Requests Access Token</SPAN><SPAN>)</SPAN></A> again. -</P> -<A name="0.2_anchor25"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.1.7"></A><H3>6.1.7. -CAPTCHA Response from Authorization Server</H3> - -<P>If the Authorization Server determines that the Client may be - malicious, the Authorization Server MAY require the Client to have - the User solve a CAPTCHA Puzzle. The Authorization Server - communicates its requirement by responding to the Client's Access - Token request with the following: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 400 Bad Request -</PRE></DIV> -<P>and the body of the Authorization Server response contains the - following parameter: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_captcha_url</DT> -<DD>REQUIRED. The URL to - the CAPTCHA puzzle image. -</DD> -</DL></BLOCKQUOTE> - -<P>The Client MUST present the User with the CAPTCHA puzzle and - prompt for a solution. The Client then MAY attempt to obtain an - Access Token per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3.request">Section 6.1.3<SPAN> (</SPAN><SPAN>Client Requests Access Token</SPAN><SPAN>)</SPAN></A> again, including - the following additional parameter: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_captcha_url</DT> -<DD>REQUIRED. The URL to - the CAPTCHA puzzle received from the Authorization Server. -</DD> -<DT>wrap_captcha_solution</DT> -<DD>REQUIRED. The - solution string to the CAPTCHA puzzle as defined by the - Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor26"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.1.8"></A><H3>6.1.8. -Client Refreshes Access Token</H3> - -<P>Refreshing an Access Token is the same in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3">Section 6.1<SPAN> (</SPAN><SPAN>Username and Password Profile</SPAN><SPAN>)</SPAN></A>, <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4">Section 6.2<SPAN> (</SPAN><SPAN>Web App Profile</SPAN><SPAN>)</SPAN></A>, and <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5">Section 6.3<SPAN> (</SPAN><SPAN>Rich App Profile</SPAN><SPAN>)</SPAN></A>. Authorization Servers SHOULD issue Access - Tokens that expire and require Clients to refresh them. Upon - receiving the HTTP 401 response when accessing protected resources - per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ProtectedResource">Section 4<SPAN> (</SPAN><SPAN>Accessing a Protected Resource</SPAN><SPAN>)</SPAN></A>, the Client makes an - HTTPS request to the Authorization Server's Refresh Token URL using - POST. The request contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_refresh_token</DT> -<DD>REQUIRED. The Refresh - Token that was received in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3.request">Section 6.1.3<SPAN> (</SPAN><SPAN>Client Requests Access Token</SPAN><SPAN>)</SPAN></A> -</DD> -<DT>Additional parameters:</DT> -<DD>Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor27"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.1.9"></A><H3>6.1.9. -Successful Access Token Refresh</H3> - -<P>If successful, the Authorization Server returns: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 200 OK -</PRE></DIV> -<P>with the Access Token in the response body. The response body - contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_access_token</DT> -<DD> REQUIRED. The Access - Token. -</DD> -<DT>wrap_access_token_expires_in</DT> -<DD> OPTIONAL. - The lifetime of the Access Token in seconds. For example, 3600 - represents one hour. -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor28"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.1.10"></A><H3>6.1.10. -Unsuccessful Access Token Refresh</H3> - -<P>The Authorization Server MUST verify the Refresh Token. If the - verification fails, the Authorization Server MUST respond with -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> WWW-Authenticate: WRAP -</PRE></DIV> -<P>The Client MUST again request authorization from the User by - prompting for the User's username and password per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3.password">Section 6.1.2<SPAN> (</SPAN><SPAN>Client Obtains Username and Password</SPAN><SPAN>)</SPAN></A> before retrying the request. -</P> -<A name="0.2_p4"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.2"></A><H3>6.2. -Web App Profile</H3> - -<P>This profile is suitable when the Client is a web application - calling the Protected Resource on behalf of a User. This profile - enables a Client to act on behalf of the User without acquiring a - User's credentials. -</P> -<A name="0.2_anchor29"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.2.1"></A><H3>6.2.1. -Provisioning</H3> - -<P>Prior to initiating this protocol profile, the Client MUST have - obtained a Client Identifier and Client Secret from the - Authorization Server. The Authorization Server MAY have also - required the Client to register the Callback URL. -</P> -<A name="0.2_p4.authorization"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.2.2"></A><H3>6.2.2. -Client Directs the User to the Authorization Server</H3> - -<P>The Client initiates an authorization request by redirecting the - User's browser to the Authorization Server's User Authorization URL, - with the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_client_id</DT> -<DD> REQUIRED. The Client - Identifier. -</DD> -<DT>wrap_callback </DT> -<DD> REQUIRED. The - Callback URL. An absolute URL to which the Authorization Server - will redirect the User back after the User has approved the - authorization request. Authorization Servers MAY require that - the wrap_callback URL match the previously registered value for - the Client Identifier. -</DD> -<DT>wrap_client_state</DT> -<DD>OPTIONAL. An opaque - value that Clients can use to maintain state associated with - this request. If this value is present, the Authorization Server - MUST return it to the Client's Callback URL. -</DD> -<DT>wrap_scope</DT> -<DD> OPTIONAL. The Authorization - Server MAY define authorization scope values for the Client to - include. -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor30"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.2.3"></A><H3>6.2.3. -Authorization Server Confirms Authorization Request with User</H3> - -<P>Upon receiving an authorization request from the Client by a - redirection of the User's browser, the Authorization Server - authenticates the user, presents the User with the Protected - Resource access that will be granted to the Client, and prompts the - User to confirm the request. -</P> -<P>If the User denies the request, the Authorization Server MAY - allow the User to return to the Client Callback URL with the - following parameters added: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_error_reason</DT> -<DD> REQUIRED. Value is - user_denied -</DD> -<DT>wrap_client_state</DT> -<DD> REQUIRED if the - Client sent the value in the authorization request in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4.authorization">Section 6.2.2<SPAN> (</SPAN><SPAN>Client Directs the User to the Authorization Server</SPAN><SPAN>)</SPAN></A> -</DD> -</DL></BLOCKQUOTE> - -<P>If the User approves the request, the Authorization Server - generates a Verification Code and associates it with the Client - Identifier and Callback URL. -</P> -<A name="0.2_anchor31"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.2.4"></A><H3>6.2.4. -Authorization Server Directs User back to the Client</H3> - -<P>If the User approved the request, the Authorization Server MUST - redirect the User back to the Callback URL, with the following - parameters added: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_verification_code</DT> -<DD> REQUIRED. The - Verification Code. -</DD> -<DT>wrap_client_state</DT> -<DD> REQUIRED if the - Client sent the value in the authorization request in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4.authorization">Section 6.2.2<SPAN> (</SPAN><SPAN>Client Directs the User to the Authorization Server</SPAN><SPAN>)</SPAN></A> -</DD> -<DT>Additional parameters:</DT> -<DD>Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_p4.request"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.2.5"></A><H3>6.2.5. -Client Requests Access Token</H3> - -<P>The Client makes an HTTPS request to the Authorization Server's - Access Token URL, using POST. The request contains the following - parameters in the body of the request: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_client_id</DT> -<DD> REQUIRED. The Client - Identifier -</DD> -<DT>wrap_client_secret</DT> -<DD>REQUIRED. The Client - Secret -</DD> -<DT>wrap_verification_code</DT> -<DD> REQUIRED. The - Verification Code. -</DD> -<DT>wrap_callback</DT> -<DD> REQUIRED. The Callback - URL used to obtain the Verification Code. -</DD> -<DT>Additional parameters:</DT> -<DD>Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor32"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.2.6"></A><H3>6.2.6. -Successful Access Token Response from Authorization Server</H3> - -<P>After receiving the Access Token request, the Authorization - Server verifies the request as follows: -</P> -<P></P> -<BLOCKQUOTE> -<P>the Client Secret MUST match the Client Identifer -</P> -<P>the Client Identifier MUST match the Client Identifier from - the authorization redirect -</P> -<P>the Verification Code MUST match the Client Identifier from - the authorization redirect -</P> -<P>the Callback URL MUST match the Callback URL from the - authorization redirect -</P> -<P>if the Callback URL or Callback URL pattern was registered - with the Authorization Server, the Callback URL MUST match the - Callback URL or Callback URL pattern as defined by the - Authorization Server -</P> -<P>the Verification Code MUST not have expired -</P> -</BLOCKQUOTE> - -<P>The Authorization Server MAY also require that a Verification - Code is not reused. -</P> -<P>If verification is successful, the Authorization Server - returns: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 200 OK -</PRE></DIV> -<P>with the Refresh Token and the Access Token in the response body. - The response body contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_refresh_token</DT> -<DD> REQUIRED. The - Refresh Token. -</DD> -<DT>wrap_access_token</DT> -<DD> REQUIRED. The Access - Token. -</DD> -<DT>wrap_access_token_expires_in</DT> -<DD> OPTIONAL. - The lifetime of the Access Token in seconds. For example, 3600 - represents one hour. -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<P>The Client securely stores the Refresh Token for later use. The - Client may now use the Access Token to access the Protected Resource - per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ProtectedResource">Section 4<SPAN> (</SPAN><SPAN>Accessing a Protected Resource</SPAN><SPAN>)</SPAN></A>. -</P> -<A name="0.2_anchor33"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.2.7"></A><H3>6.2.7. -Unsuccessful Access Token Response from Authorization Server</H3> - -<P>The Authorization Server MUST first verify the Client Identifier - and Client Secret. If they are invalid, the Authorization Server - MUST respond with: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> WWW-Authenticate: WRAP -</PRE></DIV> -<P>The Client MUST obtain a valid Client Identifier and Client - Secret before retrying the request. -</P> -<P>The Authorization Server MUST then verify that the Callback URL - and Verification Code are associated with the Client Identifier. If - the verification fails, the Authorization Server MUST respond - with: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 400 Bad Request -</PRE></DIV> -<P>and the body of the Authorization Server response contains the - following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_error_reason</DT> -<DD>OPTIONAL. If all the - parameters are valid except that the Verification Code has - expired or been revoked, then it is RECOMMENDED that this - parameter be included and if so, then the value MUST be: -</DD> -<DT> -<DD><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> expired_verification_code -</PRE></DIV> -</DD> -<DT> -<DD>This enables the Client to detect it needs a new Verification - Code and to direct the User to the Authorization Server per - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4.authorization">Section 6.2.2<SPAN> (</SPAN><SPAN>Client Directs the User to the Authorization Server</SPAN><SPAN>)</SPAN></A> -</DD> -<DT> -<DD>If the Callback URL is invalid, the value MUST be: -</DD> -<DT> -<DD><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> invalid_callback -</PRE></DIV> -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor34"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.2.8"></A><H3>6.2.8. -Client Refreshes Access Token</H3> - -<P>Refreshing an Access Token is the same in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3">Section 6.1<SPAN> (</SPAN><SPAN>Username and Password Profile</SPAN><SPAN>)</SPAN></A>, <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4">Section 6.2<SPAN> (</SPAN><SPAN>Web App Profile</SPAN><SPAN>)</SPAN></A>, and <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5">Section 6.3<SPAN> (</SPAN><SPAN>Rich App Profile</SPAN><SPAN>)</SPAN></A>. Authorization Servers SHOULD issue Access - Tokens that expire and require Clients to refresh them. Upon - receiving the HTTP 401 response when accessing protected resources - per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ProtectedResource">Section 4<SPAN> (</SPAN><SPAN>Accessing a Protected Resource</SPAN><SPAN>)</SPAN></A>, the Client makes an - HTTPS request to the Authorization Server's Refresh Token URL using - POST. The request contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_refresh_token</DT> -<DD>REQUIRED. The Refresh - Token that was received in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4.request">Section 6.2.5<SPAN> (</SPAN><SPAN>Client Requests Access Token</SPAN><SPAN>)</SPAN></A> -</DD> -<DT>Additional parameters:</DT> -<DD>Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor35"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.2.9"></A><H3>6.2.9. -Successful Access Token Refresh</H3> - -<P>If successful, the Authorization Server returns: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 200 OK -</PRE></DIV> -<P>with the Access Token in the response body. The response body - contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_access_token</DT> -<DD> REQUIRED. The Access - Token. -</DD> -<DT>wrap_access_token_expires_in</DT> -<DD> OPTIONAL. - The lifetime of the Access Token in seconds. For example, 3600 - represents one hour. -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor36"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.2.10"></A><H3>6.2.10. -Unsuccessful Access Token Refresh</H3> - -<P>The Authorization Server MUST verify the Refresh Token. If the - verification fails, the Authorization Server MUST respond with -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> WWW-Authenticate: WRAP -</PRE></DIV> -<P>The Client MUST again request authorization from the User per - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4.authorization">Section 6.2.2<SPAN> (</SPAN><SPAN>Client Directs the User to the Authorization Server</SPAN><SPAN>)</SPAN></A>. -</P> -<A name="0.2_p5"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3"></A><H3>6.3. -Rich App Profile</H3> - -<P>This profile is suitable where the Client is an application the - User has installed on their computer and there is a browser available - for the Client to launch. This profile enables a Client to act on - behalf of the User regardless of how the User authenticates to the - Server and without access to the User's credentials. -</P> -<A name="0.2_anchor37"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3.1"></A><H3>6.3.1. -Provisioning</H3> - -<P>Prior to initiating this protocol profile, the Client MAY be - required to register the Client Identifier and/or the Callback URL - with the Server. -</P> -<A name="0.2_p5.authorization"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3.2"></A><H3>6.3.2. -Client Directs the User to the Authorization Server</H3> - -<P>The Client initiates an authorization request by opening the - User's browser with the Server's User Authorization URL, and - including the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_client_id</DT> -<DD> REQUIRED. The Client - Identifier. -</DD> -<DT>wrap_callback </DT> -<DD> OPTIONAL. A Callback - URL where the Authorization Server MAY redirect the User's - browser after the User responds to the authorization - request. -</DD> -<DT>wrap_client_state</DT> -<DD>OPTIONAL. An opaque - value that Clients can use to maintain state associated with - this request. If this value is present, the Authorization Server - MUST return it to the Client's Callback URL. -</DD> -<DT>wrap_scope</DT> -<DD> OPTIONAL. The Authorization - Server MAY define authorization scope values for the Client to - include. -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor38"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3.3"></A><H3>6.3.3. -Authorization Server Confirms Authorization Request with User</H3> - -<P>Upon receiving an authorization request from the Client by way of - the User's browser, the Authorization Server authenticates the user, - presents the User with the Protected Resource access that will be - granted to the Client, and prompts the User to confirm the request. - If the User approves the request, the Authorization Server generates - a Verification Code. If the User denied access, the Authorization - Server MAY set the Verification Code to the reserved value: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> user_denied -</PRE></DIV> -<P>It is RECOMMENDED the Verification Code be single use, and expire - within minutes of issue. There are a number of mechanisms for the - Authorization Server to transmit the Verification Code to the - Client, specified below. -</P> -<P>Rich Application interaction with the User and the Authorization - Server is an area of active research and development. If the Rich - Application is able to retrieve the verifier directly from the - callback URL returned by the Authorization Server, an improved user - experience is possible. However, not all applications are able to - interact with the Authorization Server in this manner. -</P> -<A name="0.2_anchor39"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3.3.1"></A><H3>6.3.3.1. -Applications with Callback URLs</H3> - -<P>Rich Applications may be able to receive callback URLs in any - of several ways. For example, the Rich Application may register a - custom protocol handler with the application platform so that the - application will be invoked when the browser is redirected to the - callback URL. Alternatively, the callback URL may point to a web - site with which the Rich Application has a trust relationship. The - web site can then pass the Callback URL down to the Rich - Application for processing. Finally, the Callback URL may point to - a web site that will display the Callback URL to the screen along - with instructions for the user to enter the Verification Code into - the application. -</P> -<P>For Rich Applications with a Callback URL, the Authorization - Server MUST redirect the User back to the Callback URL, with the - following parameters added: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_verification_code</DT> -<DD> REQUIRED. The - Verification Code -</DD> -<DT>wrap_client_state</DT> -<DD> REQUIRED if the - Client sent the value in the authorization request in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5.authorization">Section 6.3.2<SPAN> (</SPAN><SPAN>Client Directs the User to the Authorization Server</SPAN><SPAN>)</SPAN></A> -</DD> -<DT>Additional parameters</DT> -<DD> Any - additional parameters, as defined by the Authorization - Server. -</DD> -</DL></BLOCKQUOTE> - -<P>If the User denied access, the Server MAY redirect the User's - browser to the Callback URL with the Verification Code set to the - reserved value: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> user_denied -</PRE></DIV> -<A name="0.2_anchor40"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3.3.2"></A><H3>6.3.3.2. -Applications without Callback URLs</H3> - -<P>Rich Applications without Callback URLs need to receive the - verification code in other ways. For Rich Applications without a - Callback URL, the Authorization Server MUST present the - Verification Code on the web page and instruct the user to enter - it into the Client. -</P> -<P>The Server MAY also append the Verification Code to the title - of the HTML page so that Clients that have access to the title of - the browser's current page can obtain the Verification Code - without requiring the User enter the Verification Code into the - Client. The Client can parse the title looking for "code=" and - then the rest of the title is the Verification Code. If adding the - Verification Code to the title of the HTML page, the Server MUST - also include the wrap_client_state parameter if sent from the - Client as the "state=" parameter. -</P> -<P>Eg. For <A href="http://example.com/" target="_blank">example.com</A> where the Verification Code = WF34F7HG and - Client State = NMMGFJJ, the Server would set the title of the page - to something like: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> <title>Successful delegation, code=WF34F7HG -state=NMMGFJJ</title></PRE></DIV> -<P>If the User denied access, the Server MAY append - code=user_denied to the title of the HTML page so that the Client - can detect that the User has denied access. -</P> -<A name="0.2_p5.request"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3.4"></A><H3>6.3.4. -Client Requests Access Token</H3> - -<P>The Client makes an HTTPS request to the Server's Access Token - URL using POST. The request contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_client_id</DT> -<DD> REQUIRED. The Client - Identifier -</DD> -<DT>wrap_verification_code</DT> -<DD> REQUIRED. The - Verification Code. -</DD> -<DT>Additional parameters:</DT> -<DD>Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_p5.verification"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3.5"></A><H3>6.3.5. -Successful Access Token Response from Authorization Server</H3> - -<P>The Server checks the Verification Code was previously issued to - the same Client Identifier, has not expired and has not been used. - If these conditions are met, the Server marks the Verification Code - as being used and returns: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 200 OK -</PRE></DIV> -<P>with the Refresh Token and an Access Token in the response body. - The response body contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_refresh_token</DT> -<DD> REQUIRED. The - Refresh Token. -</DD> -<DT>wrap_access_token</DT> -<DD> REQUIRED. The Access - Token. -</DD> -<DT>wrap_access_token_expires_in</DT> -<DD> OPTIONAL. - The lifetime of the Access Token in seconds. For example, 3600 - represents one hour. -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<P>The Client securely stores the Refresh Token for later use. The - Client may now use the Access Token to access the Protected Resource - per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ProtectedResource">Section 4<SPAN> (</SPAN><SPAN>Accessing a Protected Resource</SPAN><SPAN>)</SPAN></A>. -</P> -<A name="0.2_anchor41"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3.6"></A><H3>6.3.6. -Unsuccessful Access Token Response from Authorization Server</H3> - -<P>The Authorization Server MUST first verify the Client Identifier - and Client Secret per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5.verification">Section 6.3.5<SPAN> (</SPAN><SPAN>Successful Access Token Response from Authorization Server</SPAN><SPAN>)</SPAN></A>. If - they are invalid, the Authorization Server MUST respond with: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> WWW-Authenticate: WRAP -</PRE></DIV> -<P>The Client needs to obtain a new Verification Code per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5.authorization">Section 6.3.2<SPAN> (</SPAN><SPAN>Client Directs the User to the Authorization Server</SPAN><SPAN>)</SPAN></A>. -</P> -<A name="0.2_anchor42"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3.7"></A><H3>6.3.7. -Client Refreshes Access Token</H3> - -<P>Refreshing an Access Token is the same in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p3">Section 6.1<SPAN> (</SPAN><SPAN>Username and Password Profile</SPAN><SPAN>)</SPAN></A>, <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p4">Section 6.2<SPAN> (</SPAN><SPAN>Web App Profile</SPAN><SPAN>)</SPAN></A>, and <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5">Section 6.3<SPAN> (</SPAN><SPAN>Rich App Profile</SPAN><SPAN>)</SPAN></A>. Authorization Servers SHOULD issue Access - Tokens that expire and require Clients to refresh them. Upon - receiving the HTTP 401 response when accessing protected resources - per <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_ProtectedResource">Section 4<SPAN> (</SPAN><SPAN>Accessing a Protected Resource</SPAN><SPAN>)</SPAN></A>, the Client makes an - HTTPS request to the Authorization Server's Refresh Token URL using - POST. The request contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_refresh_token</DT> -<DD>REQUIRED. The Refresh - Token that was received in <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5.request">Section 6.3.4<SPAN> (</SPAN><SPAN>Client Requests Access Token</SPAN><SPAN>)</SPAN></A> -</DD> -<DT>Additional parameters:</DT> -<DD>Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor43"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3.8"></A><H3>6.3.8. -Successful Access Token Refresh</H3> - -<P>If successful, the Authorization Server returns: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 200 OK -</PRE></DIV> -<P>with the Access Token in the response body. The response body - contains the following parameters: -</P> -<P></P> -<BLOCKQUOTE><DL> -<DT>wrap_access_token</DT> -<DD> REQUIRED. The Access - Token. -</DD> -<DT>wrap_access_token_expires_in</DT> -<DD> OPTIONAL. - The lifetime of the Access Token in seconds. For example, 3600 - represents one hour. -</DD> -<DT>Additional parameters</DT> -<DD> Any additional - parameters, as defined by the Authorization Server. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor44"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.6.3.9"></A><H3>6.3.9. -Unsuccessful Access Token Refresh</H3> - -<P>The Authorization Server MUST verify the Refresh Token. If the - verification fails, the Authorization Server MUST respond with -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> WWW-Authenticate: WRAP -</PRE></DIV> -<P>The Client MUST again request authorization from the User per - <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_p5.authorization">Section 6.3.2<SPAN> (</SPAN><SPAN>Client Directs the User to the Authorization Server</SPAN><SPAN>)</SPAN></A>. -</P> -<A name="0.2_ParamCon"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.7"></A><H3>7. -Parameter Considerations</H3> - -<A name="0.2_anchor45"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.7.1"></A><H3>7.1. -Authorization Server Request / Response Parameter Encoding</H3> - -<P>All requests made directly to the Authorization Server use the HTTP - POST method and the parameters MUST be in the body of the message and - formatted as application/x-www-form-<WBR>urlencoded per <A href="http://www.w3.org/TR/1999/REC-W3C.REC-html40-19980424-19991224/interact/forms.html#h-17.13.4.1" target="_blank">17.13.4</A> - of <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_W3C.REC-html40-19980424">HTML 4.01<SPAN> (</SPAN><SPAN>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</SPAN><SPAN>)</SPAN></A> [W3C.REC‑html40‑19980424]. -</P> -<P>Any parameters in the response from the Authorization Server MUST - be in the body of the message and formatted as - application/x-www-form-<WBR>urlencoded per <A href="http://www.w3.org/TR/1999/REC-W3C.REC-html40-19980424-19991224/interact/forms.html#h-17.13.4.1" target="_blank">17.13.4</A> - of <A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_W3C.REC-html40-19980424">HTML 4.01<SPAN> (</SPAN><SPAN>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</SPAN><SPAN>)</SPAN></A> [W3C.REC‑html40‑19980424]. -</P> -<A name="0.2_anchor46"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.7.2"></A><H3>7.2. -Parameter Size</H3> - -<P></P> -<BLOCKQUOTE><DL> -<DT>HTTP Headers</DT> -<DD> Web servers often impose a - maximum on the combined size of all HTTP headers ranging from 8KB - to 16KB. The size of the Access Token should be small enough to - ensure the total size of the HTTP headers does not exceed the - limits of web servers. -</DD> -<DT>URLs</DT> -<DD> Web servers and browsers often - impose a maximum on the total length of the URL of as low as 2083 - bytes. The length of URLs exposed by the Authorization Server and - the length of parameters passed on a URL should be minimized so - that the total length does not exceed this limit. -</DD> -</DL></BLOCKQUOTE> - -<A name="0.2_anchor47"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.7.3"></A><H3>7.3. -Access Token Format</H3> - -<P>OAuth WRAP does not specify the format of the Access Token. The - format is mutually agreed to by the Authorization Server and the - Protected Resource and is opaque to the Client. The Access Token - format MUST consist of legal characters in an HTTP header per - [Reference needed] -</P> -<P>The Simple Web Token (SWT) and JSON Web Token (JWT) are possible - Access Token formats. -</P> -<P>[TBD: entropy recommendations for Access Token so that it remains - secure during its lifetime] -</P> -<A name="0.2_anchor48"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.7.4"></A><H3>7.4. -Refresh Token Format</H3> - -<P>OAuth WRAP does not specify the format of the Refresh Token. The - Refresh Token is both generated and consumed by the Authorization - Server and is opaque to the Client and never exposed to the Protected - Resource. The Refresh Token is a long lived credential, and should - contain enough entropy that it cannot be guessed. The size limitations - of the Access Token are not applicable to the Refresh Token as the - Refresh Token is always in the body of an HTTP message. -</P> -<A name="0.2_anchor49"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.7.5"></A><H3>7.5. -Additional Authorization Server Parameters</H3> - -<P>The Authorization Server may define additional parameters to be - included in are returned from calls to the Access Token URL or User - Authorization URL. Parameters that start with wrap_ are reserved and - may not be used. -</P> -<A name="0.2_anchor50"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.7.6"></A><H3>7.6. -Parameter Names and Order</H3> - -<P>All parameter names are case sensitive. The parameters my appear in - any order. Unrecognized parameters are allowed, but MUST be - ignored. -</P> -<A name="0.2_IANA"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.8"></A><H3>8. -IANA Considerations</H3> - -<P>This memo includes no request to IANA. -</P> -<A name="0.2_Security"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.9"></A><H3>9. -Security Considerations</H3> - -<P>TBD: need to put in all the security considerations for - implementors. -</P> -<A name="0.2_rfc.references"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.10"></A><H3>10. -References</H3> - -<A name="0.2_rfc.references1"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<H3>10.1. Normative References</H3> -<TABLE width="99%" border="0"> -<TBODY><TR><TD valign="top"><A name="0.2_RFC2119">[RFC2119]</A></TD> -<TD><A href="mailto:sob@harvard.edu" target="_blank">Bradner, S.</A>, “<A href="http://tools.ietf.org/html/rfc2119" target="_blank">Key words for use in RFCs to Indicate Requirement Levels</A>,” BCP 14, RFC 2119, March 1997 (<A href="ftp://ftp.isi.edu/in-notes/rfc2119.txt" target="_blank">TXT</A>, <A href="http://xml.resource.org/public/rfc/html/rfc2119.html" target="_blank">HTML</A>, <A href="http://xml.resource.org/public/rfc/xml/rfc2119.xml" target="_blank">XML</A>).</TD></TR> -<TR><TD valign="top"><A name="0.2_RFC2606">[RFC2606]</A></TD> -<TD><A href="mailto:dee3@us.ibm.com" target="_blank">Eastlake, D.</A> and <A href="mailto:buglady@fuschia.net" target="_blank">A. Panitz</A>, “<A href="http://tools.ietf.org/html/rfc2606" target="_blank">Reserved Top Level DNS Names</A>,” BCP 32, RFC 2606, June 1999 (<A href="ftp://ftp.isi.edu/in-notes/rfc2606.txt" target="_blank">TXT</A>).</TD></TR> -<TR><TD valign="top"><A name="0.2_RFC2617">[RFC2617]</A></TD> -<TD><A href="mailto:john@math.nwu.edu" target="_blank">Franks, J.</A>, <A href="mailto:pbaker@verisign.com" target="_blank">Hallam-Baker, P.</A>, <A href="mailto:jeff@AbiSource.com" target="_blank">Hostetler, J.</A>, <A href="mailto:lawrence@agranat.com" target="_blank">Lawrence, S.</A>, <A href="mailto:paulle@microsoft.com" target="_blank">Leach, P.</A>, Luotonen, A., and <A href="mailto:stewart@OpenMarket.com" target="_blank">L. Stewart</A>, “<A href="http://tools.ietf.org/html/rfc2617" target="_blank">HTTP Authentication: Basic and Digest Access Authentication</A>,” RFC 2617, June 1999 (<A href="ftp://ftp.isi.edu/in-notes/rfc2617.txt" target="_blank">TXT</A>, <A href="http://xml.resource.org/public/rfc/html/rfc2617.html" target="_blank">HTML</A>, <A href="http://xml.resource.org/public/rfc/xml/rfc2617.xml" target="_blank">XML</A>).</TD></TR> -<TR><TD valign="top"><A name="0.2_W3C.REC-html40-19980424">[W3C.REC-html40-19980424]</A></TD> -<TD>Hors, A., Jacobs, I., and D. Raggett, “<A href="http://www.w3.org/TR/1998/REC-html40-19980424" target="_blank">HTML 4.0 Specification</A>,” World Wide Web Consortium Recommendation REC-html40-<WBR>19980424, April 1998 (<A href="http://www.w3.org/TR/1998/REC-html40-19980424" target="_blank">HTML</A>).</TD></TR> -</TBODY></TABLE> - -<A name="0.2_rfc.references2"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<H3>10.2. Informative References</H3> -<TABLE width="99%" border="0"> -<TBODY><TR><TD valign="top"><A name="0.2_I-D.narten-iana-considerations-rfc2434bis">[I-D.narten-iana-<WBR>considerations-rfc2434bis]</A></TD> -<TD>Narten, T. and H. Alvestrand, “<A href="http://www.ietf.org/internet-drafts/draft-narten-iana-considerations-rfc2434bis-09.txt" target="_blank">Guidelines for Writing an IANA Considerations Section in RFCs</A>,” draft-narten-iana-<WBR>considerations-rfc2434bis-09 (work in progress), March 2008 (<A href="http://www.ietf.org/internet-drafts/draft-narten-iana-considerations-rfc2434bis-09.txt" target="_blank">TXT</A>).</TD></TR> -<TR><TD valign="top"><A name="0.2_OASIS.saml-core-2.0-os">[OASIS.saml-core-2.0-os]</A></TD> -<TD><A href="mailto:cantor.2@osu.edu" target="_blank">Cantor, S.</A>, <A href="mailto:John.Kemp@nokia.com" target="_blank">Kemp, J.</A>, <A href="mailto:rphilpott@rsasecurity.com" target="_blank">Philpott, R.</A>, and <A href="mailto:eve.maler@sun.com" target="_blank">E. Maler</A>, “<A href="http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf" target="_blank">Assertions and Protocol for the OASIS Security Assertion Markup Language - (SAML) V2.0</A>,” OASIS Standard saml-core-2.0-os, March 2005.</TD></TR> -<TR><TD valign="top"><A name="0.2_OAuth Core 1.0">[OAuth Core 1.0]</A></TD> -<TD>Hammer-Lahav, E., “<A href="http://tools.ietf.org/html/draft-hammer-oauth-08" target="_blank">OAuth Core 1.0 Protocol</A>.”</TD></TR> -</TBODY></TABLE> - -<A name="0.2_anchor53"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.A"></A><H3>Appendix A. -Client Account and Password Profile Example</H3> - -<P>In this example, <A href="http://crm.example.com/" target="_blank">crm.example.com</A> is an application server that has a - Protected Resource at <A href="https://crm.example.com/data" target="_blank">https://crm.example.com/data</A>. DataDumper is an - application acting as a Client that periodically calls - <A href="https://crm.example.com/data" target="_blank">https://crm.example.com/data</A>. The Protected Resource trusts the - Authorization Server <A href="http://auth.example.net/" target="_blank">auth.example.net</A> to determine if a Client has - access. -</P> -<A name="0.2_anchor54"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.A.1"></A><H3>A.1. -Provisioning</H3> - -<P>The Authorization Server documentation defines the Access Token URL - as: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> <A href="https://auth.example.net/access_token" target="_blank">https://auth.example.net/<WBR>access_token</A> -</PRE></DIV> -<P>The Authorization Server has defined that the parameter Audience be - included in calls to the Access Token URL. -</P> -<P>The Client has been provisioned with the following: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> Client Account: datadumper Client Password: j2hw7GPsl0 -</PRE></DIV> -<P>The Protected Resource and the Authorization Server have agreed to - use a Simple Web Token (SWT) for the Access Token with the reserved - attributes Issuer, Audience, ExpiresOn and the public attribute - net.example.auth.account and have exchanged the following HMAC key - value (expressed in base 64): -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>3iK5ZYAoBQuOqSgF/<WBR>YqlDw70HKRmbyXkrl5f4SJ4Toc= -</PRE></DIV> -<A name="0.2_anchor55"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.A.2"></A><H3>A.2. -Client Requests Access Token</H3> - -<P>The Client makes an HTTPS POST to: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE><A href="https://auth.example.net/access_token" target="_blank">https://auth.example.net/<WBR>access_token</A> -</PRE></DIV> -<P>With the following message body: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>wrap_name=datadumper&wrap_<WBR>password=j2hw7GPsl0&Audience=<A href="http://crm.example.com/" target="_blank">c<WBR>rm.example.com</A> -</PRE></DIV> -<A name="0.2_anchor56"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.A.3"></A><H3>A.3. -Successful Access Token Response from Authorization Server</H3> - -<P>The Authorization Server checks that the Client Password j2hw7GPsl0 - is associated with the Client Name datadumper and that the Client is - authorized to access <A href="http://crm.example.com/" target="_blank">crm.example.com</A>. The Authorization Server notes - the time is 2010-02-03T04:05:06Z, which is 1265198706 seconds since - 1970-01-01T0:0:0Z. The Authorization Server would like the Access - Token to expire in an hour, so 3600 is added to the current time. The - Authorization Server then uses the values: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>net.example.auth.account: -datadumper ExpiresOn: 1265202306 (1265198706 + 3600) -Audience: <A href="http://crm.example.com/" target="_blank">crm.example.com</A> -Issuer: <A href="http://auth.example.net/" target="_blank">auth.example.net</A> -</PRE></DIV> -<P>and the agreed HMAC key to generate the following SWT: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>net.example.auth.account=<WBR>datadumper&ExpiresOn=<WBR>1265202306&Audience=crm. -<A href="http://example.com/" target="_blank">example.com</A>&Issuer=<A href="http://auth.example.net/" target="_blank">auth.<WBR>example.net</A>&HMACSHA256=N9%2F%<WBR>2F0tSos78Me36%2Bi -oBH0sFKfd7eCsURlEIheoUbCJk%3D -</PRE></DIV> -<P>The Authorization Server then responds to the Clients HTTPS request - with: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>HTTP 200 OK -</PRE></DIV> -<P>and the Access Token and lifetime of the Access Token as - application/x-www-form-<WBR>urlencoded data in the body of the message as - such: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>wrap_access_token=net.example.<WBR>auth.account%3Ddatadumper%<WBR>26ExpiresOn%3D -1265202306%26Audience%<A href="http://3dcrm.example.com/" target="_blank">3Dcrm.<WBR>example.com</A>%26Issuer%<A href="http://3dauth.example.net/" target="_blank">3Dauth.<WBR>example.net</A>%26 -HMACSHA256%3DN9%252F%<WBR>252F0tSos78Me36%<WBR>252BioBH0sFKfd7eCsURlEIheoUbCJ<WBR>k%2 -53D&wrap_access_token_expires_<WBR>in=3600</PRE></DIV> -<A name="0.2_anchor57"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.A.4"></A><H3>A.4. -Client Calls Protected Resource</H3> - -<P>The Client now has an Access Token valid for an hour. The Client - makes an API call to: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE><A href="https://crm.example.com/data" target="_blank">https://crm.example.com/data</A> -</PRE></DIV> -<P>including the following HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>Authorization: WRAP access_token="net.example.<WBR>auth.account=datadumper& -ExpiresOn=1265202306&Audience=<A href="http://crm.example.com/" target="_blank"><WBR>crm.example.com</A>&Issuer=<A href="http://auth.example.net/" target="_blank">auth.<WBR>example.net</A>& -HMACSHA256=N9%2F%<WBR>2F0tSos78Me36%<WBR>2BioBH0sFKfd7eCsURlEIheoUbCJk%<WBR>3D" -</PRE></DIV> -<P>The Protected Resources verifies the SWT and performs the Client's - request per the authorization attributes in the SWT. -</P> -<A name="0.2_anchor58"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.B"></A><H3>Appendix B. -Web App Profile Example</H3> - -<P>In this example, Jane, the User, listens to music from - <A href="http://music.example.com/" target="_blank">music.example.com</A> and updates her status at <A href="http://status.example.com/" target="_blank">status.example.com</A>. When - listening to music, Jane would like her status to be updated at the - start of each song. From an OAuth WRAP perspective, the Client is - <A href="http://music.example.com/" target="_blank">music.example.com</A>, the Protected Resource is - <A href="https://status.example.com/update" target="_blank">https://status.example.com/<WBR>update</A>, and <A href="http://auth.example.com/" target="_blank">auth.example.com</A> is the - Authorization Server trusted by <A href="http://status.example.com/" target="_blank">status.example.com</A>. -</P> -<A name="0.2_anchor59"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.B.1"></A><H3>B.1. -Provisioning</H3> - -<P>The Authorization Server documentation defines the following - URLs: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE> User Authorization URL: <A href="https://auth.example.com/user_authorization" target="_blank">https://auth.example.com/user_<WBR>authorization</A> - Access Token URL: <A href="https://auth.example.com/access_token" target="_blank">https://auth.example.com/<WBR>access_token</A> - Refresh Token URL: <A href="https://auth.example.com/refresh_token" target="_blank">https://auth.example.com/<WBR>refresh_token</A> -</PRE></DIV> -<P>The Authorization Server has defined that if the Client wants - authorization to update a User's status, that the Client include the - wrap_scope parameter with the value status_update when requesting - authorization. -</P> -<P>The Client has been provisioned with: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>Client Identifier: <A href="http://music.example.com/" target="_blank">music.example.com</A> -Client Secret: 7F2986DF2342914A -</PRE></DIV> -<P>The Client has registered the Callback URL: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE><A href="https://music.example.com/auth_callback" target="_blank">https://music.example.com/<WBR>auth_callback</A> -</PRE></DIV> -<P>The Protected Resource and the Authorization Server have agreed to - use a Simple Web Token (SWT) for the Access Token with the reserved - attributes Issuer, Audience, ExpiresOn and the public attributes - com.example.auth.account, com.example.auth.client and - com.example.auth.scope. They have exchanged the following HMAC key - value (expressed in base 64): -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>Zt9JlL1QvPYRSCK9PgSjrxRUBWe7lb<WBR>EYsZCdM+sJCF4= -</PRE></DIV> -<A name="0.2_anchor60"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.B.2"></A><H3>B.2. -Client Directs the User to the Server</H3> - -<P>Jane informs <A href="http://music.example.com/" target="_blank">music.example.com</A> that she would like her status at - <A href="http://status.example.com/" target="_blank">status.example.com</A> to be updated when a new song starts playing. The - <A href="http://music.example.com/" target="_blank">music.example.com</A> website maintains user sessions with a URL parameter - named session which has the value Vn3IG2FRALSEQX2Nxr at this time for - Jane. The Client will use wrap_client_state to maintain the session - value. The Client redirects Jane's browser to the Authorization - Server's User Authorization URL appending parameters for the Client - Identifier, Callback URL, Client state and authorization scope. -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE><A href="https://auth.example.com/user_authorization?wrap_client_id=music.example.com&wrap_callback=http%3A%2F%2Fmusic.example.com%2Fauth_callback&wrap_client_state=Vn3IG2FRALSEQX2Nxr&wrap_scope=status_update" target="_blank">https://auth.example.com/user_<WBR>authorization?wrap_client_id=<WBR>music.examp -le.com&wrap_callback=http%3A%<WBR>2F%2Fmusic.example.com%2Fauth_<WBR>callback&wr -ap_client_state=<WBR>Vn3IG2FRALSEQX2Nxr&wrap_scope=<WBR>status_update</A> -</PRE></DIV> -<A name="0.2_anchor61"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.B.3"></A><H3>B.3. -Authorization Server Confirms Delegation Request with User</H3> - -<P>The Authorization Server verifies the supplied Client Identifier - <A href="http://music.example.com/" target="_blank">music.example.com</A> has been registered and has the Callback URL - <A href="https://music.example.com/auth_callback" target="_blank">https://music.example.com/<WBR>auth_callback</A>. The Authorization Server - authenticates that the User it is dealing with is Jane, and then asks - Jane to authorize <A href="http://music.example.com/" target="_blank">music.example.com</A> to update Jane's status at - <A href="http://status.example.com/" target="_blank">status.example.com</A>. Jane approves the request and the Authorization - Server generates a Verification Code with the value 46YEXQjVit6T3nQ8, - stores it with the Client Identifier, Callback URl and the current - time. -</P> -<A name="0.2_anchor62"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.B.4"></A><H3>B.4. -Server Directs User back to the Client</H3> - -<P>The Server redirects Jane back to the Client's Callback URL with - the Verification Code and Client State appended: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE><A href="https://music.example.com/auth_callback?wrap_verification_code=46YEXQjVit6T3nQ8&wrap_client_state=Vn3IG2FRALSEQX2Nxr" target="_blank">https://music.example.com/<WBR>auth_callback?wrap_<WBR>verification_code=46YEXQj -Vit6T3nQ8&wrap_client_state=<WBR>Vn3IG2FRALSEQX2Nxr</A> -</PRE></DIV> -<A name="0.2_anchor63"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.B.5"></A><H3>B.5. -Client Requests Access Token</H3> - -<P>The Client makes an HTTPS POST request to: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE><A href="https://auth.example.com/access_token" target="_blank">https://auth.example.com/<WBR>access_token</A> -</PRE></DIV> -<P>With the following message body: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>wrap_client_id=<A href="http://music.example.com/" target="_blank">music.example.<WBR>com</A>&wrap_client_secret=<WBR>7F2986DF2342914A&w -rap_verification_code=<WBR>46YEXQjVit6T3nQ8&wrap_<WBR>callback=http%3A%2F%2Fmusi -<A href="http://c.example.com/" target="_blank">c.example.com</A>%2Fauth_callback -</PRE></DIV> -<A name="0.2_anchor64"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.B.6"></A><H3>B.6. -Successful Access Token Response from Authorization Server</H3> - -<P>The Authorization Server verifies that the Verification Code is - still valid, has not been used, and is associated with the Client ID, - Client Secret and Callback URL Password. The Authorization Server then - generates a Refresh Token with the value: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>MfdWTc+v9MXhpc+d/<WBR>csrKFMPfj1RySm6CzIjmTBGN6w= -</PRE></DIV> -<P>The Authorization Server notes the time is 2010-01-02T03:04:05Z, - which is 1262430245 seconds since 1970-01-01T0:0:0Z. The Authorization - Server then uses the values: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>com.example.auth.scope: status_updatea -com.example.auth.account: Jane -com.example.auth.client: <A href="http://music.example.com/" target="_blank">music.example.com</A> -ExpiresOn: 1262433845 (1262430245 + 3600 seconds later) -Audience: <A href="http://status.example.com/" target="_blank">status.example.com</A> -Issuer: <A href="http://auth.example.com/" target="_blank">auth.example.com</A> -</PRE></DIV> -<P>and the agreed HMAC key to generate the following SWT: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>com.example.auth.scope=status_<WBR>update&com.example.auth.<WBR>account=Jane&com -.example.auth.client=<A href="http://music.example.com/" target="_blank">music.<WBR>example.com</A>&ExpiresOn=<WBR>1262433845&Audience=s -<A href="http://tatus.example.com/" target="_blank">tatus.example.com</A>&Issuer=<A href="http://auth.example.com/" target="_blank">auth.<WBR>example.com</A>&HMACSHA256=<WBR>3xZAYzJRtYCQgkAF3 -iqElp1DhyKkPhq947j04NcDocQ%3D -</PRE></DIV> -<P>The Authorization Server then responds to the Clients HTTPS request - with: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>HTTP 200 OK -</PRE></DIV> -<P>and the Refresh Token, Access Token and lifetime of the Access - Token as application/x-www-form-<WBR>urlencoded data in the body of the - message as such: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>wrap_refresh_token=MfdWTc%<WBR>2Bv9MXhpc%2Bd%<WBR>2FcsrKFMPfj1RySm6CzIjmTBGN6w%3 -D&wrap_access_token=com.<WBR>example.auth.scope%3Dstatus_<WBR>update%26com.examp -le.auth.account%3DJane%26com.<WBR>example.auth.client%<A href="http://3dmusic.example.com/" target="_blank">3Dmusic.<WBR>example.com</A>%2 -6ExpiresOn%3D1262433845%<WBR>26Audience%<A href="http://3dstatus.example.com/" target="_blank">3Dstatus.example.<WBR>com</A>%26Issuer%3Daut -<A href="http://h.example.com/" target="_blank">h.example.com</A>%26HMACSHA256%<WBR>3D3xZAYzJRtYCQgkAF3iqElp1DhyKk<WBR>Phq947j04NcDo -cQ%253D&wrap_access_token_<WBR>expires_in=3600 -</PRE></DIV> -<P>The Client now has a Refresh Token and Access Token valid for an - hour. The Client stores the Refresh Token for later use. -</P> -<A name="0.2_anchor65"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.B.7"></A><H3>B.7. -Client Calls Protected Resource</H3> - -<P>A few minutes later, <A href="http://music.example.com/" target="_blank">music.example.com</A> starts playing a new song - for Jane. The Client updates Jane's status at <A href="http://status.example.com/" target="_blank">status.example.com</A> by - making an API call to: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE><A href="https://status.example.com/update" target="_blank">https://status.example.com/<WBR>update</A> -</PRE></DIV> -<P>including the following HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>Authorization: WRAP access_token="com.example.<WBR>auth.scope=status_update -&com.example.auth.account=<WBR>Jane&com.example.auth.client=<WBR>music.example.c -om&ExpiresOn=1262433845&<WBR>Audience=<A href="http://status.example.com/" target="_blank">status.example.com</A>&<WBR>Issuer=auth.exampl -<A href="http://e.com/" target="_blank">e.com</A>&HMACSHA256=<WBR>3xZAYzJRtYCQgkAF3iqElp1DhyKkPh<WBR>q947j04NcDocQ%3D" -</PRE></DIV> -<P>The Protected Resources verifies the SWT, confirms the - authorization contained in the SWT, and updates Jane's status. -</P> -<A name="0.2_anchor66"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="0.2_rfc.section.B.8"></A><H3>B.8. -Client Refreshes Access Token</H3> - -<P>An hour passes by and <A href="http://music.example.com/" target="_blank">music.example.com</A> starts playing another new - song for Jane. The Client again makes an API call to - <A href="http://status.example.com/" target="_blank">status.example.com</A> including the same HTTP Authorization header. - Unlike previous calls where the status update was performed, the - Protected Resource returns the following error response: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>HTTP 401 Unauthorized -</PRE></DIV> -<P>and the HTTP header: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>WWW-Authenticate: WRAP -</PRE></DIV> -<P>The Client determines it probably needs a new Access Token, - retrieves the Refresh Token and makes an HTTPS POST to: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE><A href="https://auth.example.com/refresh_token" target="_blank">https://auth.example.com/<WBR>refresh_token</A> -</PRE></DIV> -<P>including the Client Identifier, Client Secret and Refresh Token in - the message body as: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>wrap_client_id=<A href="http://music.example.com/" target="_blank">music.example.<WBR>com</A>&wrap_client_secret=<WBR>7F2986DF2342914A&w -rap_refresh_token=MfdWTc%<WBR>2Bv9MXhpc%2Bd%<WBR>2FcsrKFMPfj1RySm6CzIjmTBGN6w%<WBR>3D -</PRE></DIV> -<P>The Authorization Server looks up the data associated with the - Refresh Token, determines <A href="http://music.example.com/" target="_blank">music.example.com</A> is still authorized to - update Jane's status, and determines it will generate a new Access - Token for the Client that expires in an hour. The time is now - 2010-01-02T04:15:23Z, which results in an Access Token expiry time of - 1262438123 seconds since 1970-01-01T0:0:0Z. The Authorization Server - generates a new Access Token and returns it in the body of the message - as: -</P><DIV style="display:table;width:0;margin-left:3em;margin-right:auto"><PRE>wrap_access_token=com.example.<WBR>auth.scope=status_update&com.<WBR>example.aut -h.account=Jane&com.example.<WBR>auth.client=<A href="http://music.example.com/" target="_blank">music.example.com</A>&<WBR>ExpiresOn=126 -2438123&Audience=<A href="http://status.example.com/" target="_blank">status.<WBR>example.com</A>&Issuer=<A href="http://auth.example.com/" target="_blank">auth.<WBR>example.com</A>&HMACSHA256 -=<WBR>AT4TFChHgyylItEWAjK7MFRJuvUS3W<WBR>LVzO%2F68gvIRQI%3D&wrap_<WBR>access_token_ex -pires_in=3600 -</PRE></DIV> -<P>The Client takes the new Access Token and uses it to successfully - update Jane's status at <A href="http://status.example.com/" target="_blank">status.example.com</A>. -</P> -<A name="0.2_rfc.authors"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" align="right"><TBODY><TR><TD><A href="https://mail.google.com/mail/?ui=2&ik=c5d0d94d4a&view=att&th=12634202598d2cea&attid=0.2&disp=inline&realattid=f_g4hjnq761&zw#0.2_toc"> TOC </A></TD></TR></TBODY></TABLE> -<H3>Authors' Addresses</H3> -<TABLE width="99%" border="0" cellpadding="0" cellspacing="0"> -<TBODY><TR><TD> </TD> -<TD>Dick Hardt (editor)</TD></TR> -<TR><TD> </TD> -<TD>Microsoft</TD></TR> -<TR><TD align="right">Email: </TD> -<TD><A href="mailto:dick.hardt@gmail.com" target="_blank">dick.hardt@gmail.com</A></TD></TR> -<TR cellpadding="3"><TD> </TD><TD> </TD></TR> -<TR><TD> </TD> -<TD>Allen Tom</TD></TR> -<TR><TD> </TD> -<TD>Yahoo!</TD></TR> -<TR><TD align="right">Email: </TD> -<TD><A href="mailto:atom@yahoo-inc.com" target="_blank">atom@yahoo-inc.com</A></TD></TR> -<TR cellpadding="3"><TD> </TD><TD> </TD></TR> -<TR><TD> </TD> -<TD>Brian Eaton</TD></TR> -<TR><TD> </TD> -<TD>Google</TD></TR> -<TR><TD align="right">Email: </TD> -<TD><A href="mailto:beaton@google.com" target="_blank">beaton@google.com</A></TD></TR> -<TR cellpadding="3"><TD> </TD><TD> </TD></TR> -<TR><TD> </TD> -<TD>Yaron Goland</TD></TR> -<TR><TD> </TD> -<TD>Microsoft</TD></TR> -<TR><TD align="right">Email: </TD> -<TD><A href="mailto:yarong@microsoft.com" target="_blank">yarong@microsoft.com</A></TD></TR> -</TBODY></TABLE> -</DIV> - -</BODY></HTML>
\ No newline at end of file diff --git a/doc/specs/draft-ietf-oauth.html b/doc/specs/draft-ietf-oauth.html new file mode 100644 index 0000000..a594581 --- /dev/null +++ b/doc/specs/draft-ietf-oauth.html @@ -0,0 +1,3419 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html lang="en"><head><title>The OAuth 2.0 Protocol</title> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<meta name="description" content="The OAuth 2.0 Protocol"> +<meta name="generator" content="xml2rfc v1.35 (http://xml.resource.org/)"> +<style type='text/css'><!-- + body { + font-family: verdana, charcoal, helvetica, arial, sans-serif; + font-size: small; color: #000; background-color: #FFF; + margin: 2em; + } + h1, h2, h3, h4, h5, h6 { + font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif; + font-weight: bold; font-style: normal; + } + h1 { color: #900; background-color: transparent; text-align: right; } + h3 { color: #333; background-color: transparent; } + + td.RFCbug { + font-size: x-small; text-decoration: none; + width: 30px; height: 30px; padding-top: 2px; + text-align: justify; vertical-align: middle; + background-color: #000; + } + td.RFCbug span.RFC { + font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif; + font-weight: bold; color: #666; + } + td.RFCbug span.hotText { + font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif; + font-weight: normal; text-align: center; color: #FFF; + } + + table.TOCbug { width: 30px; height: 15px; } + td.TOCbug { + text-align: center; width: 30px; height: 15px; + color: #FFF; background-color: #900; + } + td.TOCbug a { + font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif; + font-weight: bold; font-size: x-small; text-decoration: none; + color: #FFF; background-color: transparent; + } + + td.header { + font-family: arial, helvetica, sans-serif; font-size: x-small; + vertical-align: top; width: 33%; + color: #FFF; background-color: #666; + } + td.author { font-weight: bold; font-size: x-small; margin-left: 4em; } + td.author-text { font-size: x-small; } + + /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */ + a.info { + /* This is the key. */ + position: relative; + z-index: 24; + text-decoration: none; + } + a.info:hover { + z-index: 25; + color: #FFF; background-color: #900; + } + a.info span { display: none; } + a.info:hover span.info { + /* The span will display just on :hover state. */ + display: block; + position: absolute; + font-size: smaller; + top: 2em; left: -5em; width: 15em; + padding: 2px; border: 1px solid #333; + color: #900; background-color: #EEE; + text-align: left; + } + + a { font-weight: bold; } + a:link { color: #900; background-color: transparent; } + a:visited { color: #633; background-color: transparent; } + a:active { color: #633; background-color: transparent; } + + p { margin-left: 2em; margin-right: 2em; } + p.copyright { font-size: x-small; } + p.toc { font-size: small; font-weight: bold; margin-left: 3em; } + table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; } + td.toc { font-size: small; font-weight: bold; vertical-align: text-top; } + + ol.text { margin-left: 2em; margin-right: 2em; } + ul.text { margin-left: 2em; margin-right: 2em; } + li { margin-left: 3em; } + + /* RFC-2629 <spanx>s and <artwork>s. */ + em { font-style: italic; } + strong { font-weight: bold; } + dfn { font-weight: bold; font-style: normal; } + cite { font-weight: normal; font-style: normal; } + tt { color: #036; } + tt, pre, pre dfn, pre em, pre cite, pre span { + font-family: "Courier New", Courier, monospace; font-size: small; + } + pre { + text-align: left; padding: 4px; + color: #000; background-color: #CCC; + } + pre dfn { color: #900; } + pre em { color: #66F; background-color: #FFC; font-weight: normal; } + pre .key { color: #33C; font-weight: bold; } + pre .id { color: #900; } + pre .str { color: #000; background-color: #CFF; } + pre .val { color: #066; } + pre .rep { color: #909; } + pre .oth { color: #000; background-color: #FCF; } + pre .err { background-color: #FCC; } + + /* RFC-2629 <texttable>s. */ + table.all, table.full, table.headers, table.none { + font-size: small; text-align: center; border-width: 2px; + vertical-align: top; border-collapse: collapse; + } + table.all, table.full { border-style: solid; border-color: black; } + table.headers, table.none { border-style: none; } + th { + font-weight: bold; border-color: black; + border-width: 2px 2px 3px 2px; + } + table.all th, table.full th { border-style: solid; } + table.headers th { border-style: none none solid none; } + table.none th { border-style: none; } + table.all td { + border-style: solid; border-color: #333; + border-width: 1px 2px; + } + table.full td, table.headers td, table.none td { border-style: none; } + + hr { height: 1px; } + hr.insert { + width: 80%; border-style: none; border-width: 0; + color: #CCC; background-color: #CCC; + } +--></style> +</head> +<body> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1"> +<tr><td class="header">Network Working Group</td><td class="header">E. Hammer-Lahav, Ed.</td></tr> +<tr><td class="header">Internet-Draft</td><td class="header">Yahoo!</td></tr> +<tr><td class="header">Intended status: Standards Track</td><td class="header">D. Recordon</td></tr> +<tr><td class="header">Expires: October 23, 2010</td><td class="header">Facebook</td></tr> +<tr><td class="header"> </td><td class="header">D. Hardt</td></tr> +<tr><td class="header"> </td><td class="header">April 21, 2010</td></tr> +</table></td></tr></table> +<h1><br />The OAuth 2.0 Protocol<br />draft-ietf-oauth-00</h1> + +<h3>Abstract</h3> + +<p> + This specification describes the OAuth 2.0 protocol. OAuth provides a method for making + authenticated HTTP requests using a token - an identifier used to denote an access grant + with specific scope, duration, and other attributes. Tokens are issued to third-party + clients by an authorization server with the approval of the resource owner. OAuth defines + multiple flows for obtaining a token to support a wide range of client types and user + experience. + +</p> +<h3>Status of this Memo</h3> +<p> +This Internet-Draft is submitted in full +conformance with the provisions of BCP 78 and BCP 79.</p> +<p> +Internet-Drafts are working documents of the Internet Engineering +Task Force (IETF). Note that other groups may also distribute +working documents as Internet-Drafts. The list of current +Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.</p> +<p> +Internet-Drafts are draft documents valid for a maximum of six months +and may be updated, replaced, or obsoleted by other documents at any time. +It is inappropriate to use Internet-Drafts as reference material or to cite +them other than as “work in progress.”</p> +<p> +This Internet-Draft will expire on October 23, 2010.</p> + +<h3>Copyright Notice</h3> +<p> +Copyright (c) 2010 IETF Trust and the persons identified as the +document authors. All rights reserved.</p> +<p> +This document is subject to BCP 78 and the IETF Trust's Legal +Provisions Relating to IETF Documents +(http://trustee.ietf.org/license-info) in effect on the date of +publication of this document. Please review these documents +carefully, as they describe your rights and restrictions with respect +to this document. Code Components extracted from this document must +include Simplified BSD License text as described in Section 4.e of +the Trust Legal Provisions and are provided without warranty as +described in the Simplified BSD License.</p> +<a name="toc"></a><br /><hr /> +<h3>Table of Contents</h3> +<p class="toc"> +<a href="#anchor1">1.</a> +Authors<br /> +<a href="#anchor2">2.</a> +Introduction<br /> + <a href="#anchor3">2.1.</a> +Terminology<br /> + <a href="#anchor4">2.2.</a> +Overview<br /> + <a href="#anchor5">2.3.</a> +Example<br /> + <a href="#anchor6">2.4.</a> +Notational Conventions<br /> + <a href="#anchor7">2.5.</a> +Conformance<br /> +<a href="#get_token">3.</a> +Obtaining an Access Token<br /> + <a href="#anchor8">3.1.</a> +Authorization Endpoint<br /> + <a href="#anchor9">3.2.</a> +Token Endpoint<br /> + <a href="#anchor10">3.3.</a> +Flow Parameters<br /> + <a href="#client_id">3.4.</a> +Client Credentials<br /> + <a href="#anchor11">3.5.</a> +User Delegation Flows<br /> + <a href="#user_agent_flow">3.5.1.</a> +User-Agent Flow<br /> + <a href="#web_server_flow">3.5.2.</a> +Web Server Flow<br /> + <a href="#device_flow">3.5.3.</a> +Device Flow<br /> + <a href="#anchor24">3.6.</a> +End User Credentials Flows<br /> + <a href="#username_password_flow">3.6.1.</a> +Username and Password Flow<br /> + <a href="#anchor26">3.7.</a> +Autonomous Client Flows<br /> + <a href="#client_credentials_flow">3.7.1.</a> +Client Credentials Flow<br /> + <a href="#assertion_flow">3.7.2.</a> +Assertion Flow<br /> +<a href="#token_refresh">4.</a> +Refreshing an Access Token<br /> +<a href="#access_resource">5.</a> +Accessing a Protected Resource<br /> + <a href="#authz_header">5.1.</a> +The Authorization Request Header<br /> + <a href="#bearer_token">5.2.</a> +Bearer Token Requests<br /> + <a href="#query_param">5.2.1.</a> +URI Query Parameter<br /> + <a href="#body_param">5.2.2.</a> +Form-Encoded Body Parameter<br /> + <a href="#crypto_token">5.3.</a> +Cryptographic Tokens Requests<br /> + <a href="#hmac-sha256">5.3.1.</a> +The 'hmac-sha256' Algorithm<br /> +<a href="#anchor29">6.</a> +Identifying a Protected Resource<br /> + <a href="#authn_header">6.1.</a> +The WWW-Authenticate Response Header<br /> + <a href="#anchor30">6.1.1.</a> +The 'realm' Attribute<br /> + <a href="#authz_uri_attribute">6.1.2.</a> +The 'authorization-uri' Attribute<br /> + <a href="#anchor31">6.1.3.</a> +The 'algorithms' Attribute<br /> + <a href="#anchor32">6.1.4.</a> +The 'error' Attribute<br /> +<a href="#anchor33">7.</a> +Security Considerations<br /> +<a href="#anchor34">8.</a> +IANA Considerations<br /> +<a href="#anchor35">9.</a> +Acknowledgements<br /> +<a href="#anchor36">Appendix A.</a> +Differences from OAuth 1.0a<br /> +<a href="#anchor37">Appendix B.</a> +Document History<br /> +<a href="#rfc.references1">10.</a> +References<br /> + <a href="#rfc.references1">10.1.</a> +Normative References<br /> + <a href="#rfc.references2">10.2.</a> +Informative References<br /> +<a href="#rfc.authors">§</a> +Authors' Addresses<br /> +</p> +<br clear="all" /> + +<a name="anchor1"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.1"></a><h3>1. +Authors</h3> + +<p> + This specification was authored with the participation and based on the work of + Allen Tom (Yahoo!), Brian Eaton (Google), Brent Goldman (Facebook), Luke Shepard + (Facebook), Raffi Krikorian (Twitter), and Yaron Goland (Microsoft). + +</p> +<a name="anchor2"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2"></a><h3>2. +Introduction</h3> + +<p> + With the increasing use of distributed web services and cloud computing, third-party + applications require access to server-hosted resources. These resources are usually + protected and require authentication using the resource owner's credentials (typically a + username and password). In the traditional client-server authentication model, a client + accessing a protected resource on a server presents the resource owner's credentials in + order to authenticate and gain access. + +</p> +<p> + Resource owners should not be required to share their credentials when granting third-party + applications access to their protected resources. They should also have the ability to + restrict access to a limited subset of the resources they control, to limit access + duration, or to limit access to the methods supported by these resources. + +</p> +<p> + OAuth provides a method for making authenticated HTTP requests using a token - an + identifier used to denote an access grant with specific scope, duration, and other + attributes. Tokens are issued to third-party clients by an authorization server with the + approval of the resource owner. Instead of sharing their credentials with the client, + resource owners grant access by authenticating directly with the authorization server which + in turn issues a token to the client. The client uses the token (and optional secret) to + authenticate with the resource server and gain access. + +</p> +<p> + For example, a web user (resource owner) can grant a printing service (client) access to + her protected photos stored at a photo sharing service (resource server), without sharing + her username and password with the printing service. Instead, she authenticates directly + with the photo sharing service (authorization server) which issues the printing service + delegation-specific credentials (token). + +</p> +<p> + The use of OAuth with any other transport protocol than <a class='info' href='#RFC2616'>HTTP<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.</span><span>)</span></a> [RFC2616] + (or HTTP over TLS 1.0 as defined by <a class='info' href='#RFC2818'>[RFC2818]<span> (</span><span class='info'>Rescorla, E., “HTTP Over TLS,” May 2000.</span><span>)</span></a> is undefined. + +</p> +<a name="anchor3"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2.1"></a><h3>2.1. +Terminology</h3> + +<p> + </p> +<blockquote class="text"><dl> +<dt>resource server</dt> +<dd> + + An <a class='info' href='#RFC2616'>HTTP<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.</span><span>)</span></a> [RFC2616] server capable of accepting authenticated + resource requests using the OAuth protocol. + +</dd> +<dt>protected resource</dt> +<dd> + + An access-restricted resource which can be obtained from a resource server using + an OAuth-authenticated request. + +</dd> +<dt>client</dt> +<dd> + + An HTTP client capable of making authenticated requests for protected resources using + the OAuth protocol. + +</dd> +<dt>resource owner</dt> +<dd> + + An entity capable of granting access to a protected resource. + +</dd> +<dt>end user</dt> +<dd> + + A human resource owner. + +</dd> +<dt>access token</dt> +<dd> + + A unique identifier used by the client to make authenticated requests on behalf of + the resource owner. Access tokens may have a matching secret. + +</dd> +<dt>authorization server</dt> +<dd> + + An HTTP server capable of issuing tokens after successfully authenticating the + resource owner and obtaining authorization. The authorization server may be the same + server as the resource server, or a separate entity. + +</dd> +<dt>authorization endpoint</dt> +<dd> + + The authorization server's HTTP endpoint capable of authenticating the resource + owner and obtaining authorization. + +</dd> +<dt>token endpoint</dt> +<dd> + + The authorization server's HTTP endpoint capable of issuing tokens and refreshing + expired tokens. + +</dd> +<dt>client identifier</dt> +<dd> + + An unique identifier issued to the client to identify itself to the authorization + server. Client identifiers may have a matching secret. + +</dd> +<dt>refresh token</dt> +<dd> + + A unique identifier used by the client to replace an expired access token with a new + access token without having to involve the resource owner. A refresh token is used + when the access token is valid for a shorter time period than the duration of the + access grant approved by the resource owner. + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor4"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2.2"></a><h3>2.2. +Overview</h3> + +<p> + Clients interact with a protected resource, first by requesting access (which is granted + in the form of an access token) from the authorization server, and then by authenticating + with the resource server by presenting the access token. <a class='info' href='#Figure 1'>Figure 1</a> + demonstrates the flow between the client and authorization server (A, B), and the flow + between the client and resource server (C, D), when the client is acting autonomously + (the client is also the resource owner). + +</p><br /><hr class="insert" /> +<a name="Figure 1"></a> +<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + +--------+ +---------------+ + | |--(A)------ Credentials --------->| Authorization | + | | | Server | + | |<-(B)------ Access Token ---------| | + | | (w/ Optional Refresh Token) +---------------+ + | Client | + | | HTTP Request +---------------+ + | |--(C)--- with Access Token ------>| Resource | + | | | Server | + | |<-(D)------ HTTP Response --------| | + +--------+ +---------------+ + +</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 1 </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + Access token strings can use any internal structure agreed upon between the authorization + server and the resource server, but their structure is opaque to the client. Since the + access token provides the client access to the protected resource for the life of the + access token (or until revoked), the authorization server should issue access tokens + which expire within an appropriate time, usually much shorter than the duration of the + access grant. + +</p> +<p> + When an access token expires, the client can request a new access token from the + authorization server by presenting its credentials again (<a class='info' href='#Figure 1'>Figure 1</a>), or + by using the refresh token (if issued with the access token) as shown in + <a class='info' href='#Figure 2'>Figure 2</a>. Once an expired access token has been replaced with a new + access token (A, B), the client uses the new access token as before (C, D). + +</p><br /><hr class="insert" /> +<a name="Figure 2"></a> +<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + +--------+ +---------------+ + | |--(A)------ Refresh Token ------->| Authorization | + | | | Server | + | |<-(B)------ Access Token ---------| | + | | (with Optional Secret) +---------------+ + | Client | + | | HTTP Request +---------------+ + | |--(C)--- with Access Token ------>| Resource | + | | | Server | + | |<-(D)----- HTTP Response ---------| | + +--------+ +---------------+ + +</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 2 </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + This specification defines a number of authorization flows to support different client + types and scenarios. These authorization flows can be separated into three groups: + user delegation flows where the client is acting on behalf of an end user, end user + credentials flows where the client uses the end user's credentials directly to obtain + authorization, and autonomous flows where the client is acting for itself (the client is + also the resource owner). + +</p> +<p> + Additional authorization flows may be defined by other specifications to cover different + scenarios and client types. + +</p> +<p> + The user delegation authorization flows defined by this specifications are: + + </p> +<ul class="text"> +<li> + User-Agent Flow - This flow is designed for clients running inside a user-agent + (typically a web browser), and therefore cannot receive incoming requests from the + authorization server. This flow is described in <a class='info' href='#user_agent_flow'>Section 3.5.1<span> (</span><span class='info'>User-Agent Flow</span><span>)</span></a>. + +</li> +<li> + Web Server Flow - This flow is optimized for cases where the client is capable of + receiving incoming HTTP requests (act as an HTTP server). This flow is described in + <a class='info' href='#web_server_flow'>Section 3.5.2<span> (</span><span class='info'>Web Server Flow</span><span>)</span></a>. + +</li> +<li> + Device Flow - This flow suitable for clients executing on limited devices, but where + the end user has separate access to a user-agent on another computer or device. This + flow is described in <a class='info' href='#device_flow'>Section 3.5.3<span> (</span><span class='info'>Device Flow</span><span>)</span></a>. + +</li> +</ul><p> + +</p> +<p> + The end user credentials flow defined by this specification is: + + </p> +<ul class="text"> +<li> + Username and Password Flow - This flow is used in cases where the end user trusts + the client to handle its credentials but it is still undesirable for the client to + store the end user's username and password. This flow is described in + <a class='info' href='#username_password_flow'>Section 3.6.1<span> (</span><span class='info'>Username and Password Flow</span><span>)</span></a>. + +</li> +</ul><p> + +</p> +<p> + The autonomous authorization flows defined by this specifications are: + + </p> +<ul class="text"> +<li> + Client Credentials Flow - The client uses its credentials to obtain an access token. + This flow is described in <a class='info' href='#client_credentials_flow'>Section 3.7.1<span> (</span><span class='info'>Client Credentials Flow</span><span>)</span></a>. + +</li> +<li> + Assertion Flow - The client presents an assertion such as a + <a class='info' href='#OASIS.saml-core-2.0-os'>SAML<span> (</span><span class='info'>Cantor, S., Kemp, J., Philpott, R., and E. Maler, “Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.</span><span>)</span></a> [OASIS.saml‑core‑2.0‑os] assertion to the authorization + server in exchange for an access token. This flow is described in + <a class='info' href='#assertion_flow'>Section 3.7.2<span> (</span><span class='info'>Assertion Flow</span><span>)</span></a>. + +</li> +</ul><p> + +</p> +<a name="anchor5"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2.3"></a><h3>2.3. +Example</h3> + +<p> + [[ Todo ]] + +</p> +<a name="anchor6"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2.4"></a><h3>2.4. +Notational Conventions</h3> + +<p> + 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 <a class='info' href='#RFC2119'>[RFC2119]<span> (</span><span class='info'>Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.</span><span>)</span></a>. + +</p> +<p> + This document uses the Augmented Backus-Naur Form (ABNF) notation of + <a class='info' href='#I-D.ietf-httpbis-p1-messaging'>[I‑D.ietf‑httpbis‑p1‑messaging]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, “HTTP/1.1, part 1: URIs, Connections, and Message Parsing,” March 2010.</span><span>)</span></a>. Additionally, the realm and auth-param + rules are included from <a class='info' href='#RFC2617'>[RFC2617]<span> (</span><span class='info'>Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</span><span>)</span></a>, and the URI-Reference rule from + <a class='info' href='#RFC3986'>[RFC3986]<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</span><span>)</span></a>. + +</p> +<a name="anchor7"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2.5"></a><h3>2.5. +Conformance</h3> + +<p> + An implementation is not compliant if it fails to satisfy one or more of the MUST or + REQUIRED level requirements for the flows it implements. An implementation that + satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its + flows is said to be "unconditionally compliant"; one that satisfies all the MUST + level requirements but not all the SHOULD level requirements for its flows is said to + be "conditionally compliant." + +</p> +<a name="get_token"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3"></a><h3>3. +Obtaining an Access Token</h3> + +<p> + The client obtains an access token by using one of the authorization flows supported by the + authorization server. The authorization flows all use the same authorization and token + endpoints, each with a different set of request parameters and values. + +</p> +<p> + When issuing an access token, the scope, duration, and other access attributes granted by + the resource owner must be retained and enforced by the resource server when receiving a + protected resource request and by the authorization server when receiving a token refresh + request made with the access token issued. + +</p> +<p> + In many cases it is desirable to issue access tokens with a shorter lifetime than the + duration of the authorization grant. However, it may be undesirable to require the resource + owner to authorize the request again. Instead, the authorization server issues a refresh + token in addition to the access token. When the access token expires, the client can + request a new access token without involving the resource owner as long as the + authorization grant is still valid. The token refresh method is described in + <a class='info' href='#token_refresh'>Section 4<span> (</span><span class='info'>Refreshing an Access Token</span><span>)</span></a>. + +</p> +<a name="anchor8"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.1"></a><h3>3.1. +Authorization Endpoint</h3> + +<p> + Clients direct the resource owner to the authorization endpoint to approve their access + request. Before granting access, the resource owner first authenticate with the + authorization server. The way in which the authorization server authenticates the end + user (e.g. username and password login, OpenID, session cookies) and in which the + authorization server obtains the end user's authorization, including whether it uses a + secure channel such as TLS/SSL, is beyond the scope of this specification. However, the + authorization server MUST first verify the identity of the end user. + +</p> +<p> + The URI of the authorization endpoint can be found in the service documentation, or can + be obtained by the client by making an unauthorized protected resource request (from the + <tt>WWW-Authenticate</tt> response header + <a class='info' href='#authz_uri_attribute'>auth-uri<span> (</span><span class='info'>The 'authorization-uri' Attribute</span><span>)</span></a> attribute). + +</p> +<p> + The authorization endpoint advertised by the resource server MAY include a query + components as defined by <a class='info' href='#RFC3986'>[RFC3986]<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</span><span>)</span></a> section 3. + +</p> +<p> + Since requests to the authorization endpoint result in user authentication and the + transmission of sensitive values, the authorization server SHOULD require the + use of a transport-layer mechanism such as TLS or SSL (or a secure channel with + equivalent protections) when sending requests to the authorization endpoints. + +</p> +<a name="anchor9"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.2"></a><h3>3.2. +Token Endpoint</h3> + +<p> + After obtaining authorization from the resource owner, clients request an access token + from the authorization server's token endpoint. + +</p> +<p> + The URI of the token endpoint can be found in the service documentation, or can be + obtained by the client by making an unauthorized protected resource request (from the + <tt>WWW-Authenticate</tt> response header + <a class='info' href='#authz_uri_attribute'>token-uri<span> (</span><span class='info'>The 'authorization-uri' Attribute</span><span>)</span></a> attribute). + +</p> +<p> + The token endpoint advertised by the resource server MAY include a query components as + defined by <a class='info' href='#RFC3986'>[RFC3986]<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</span><span>)</span></a> section 3. + +</p> +<p> + Since requests to the token endpoint result in the transmission of plain text + credentials in the HTTP request and response, the authorization server MUST require the + use of a transport-layer mechanism such as TLS or SSL (or a secure channel with + equivalent protections) when sending requests to the token endpoints. + +</p> +<p> + The authorization server MUST include the HTTP <tt>Cache-Control</tt> + response header field with a value of <tt>no-store</tt> in any + response containing tokens, secrets, or other sensitive information. + +</p> +<a name="anchor10"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.3"></a><h3>3.3. +Flow Parameters</h3> + +<p> + Clients should avoid making assumptions about the size of tokens and other values + received from the authorization server, which are left undefined by this specification. + Servers should document the expected size of any value they issue. + +</p> +<a name="client_id"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.4"></a><h3>3.4. +Client Credentials</h3> + +<p> + When requesting access from the authorization server, the client identifies itself using + its authorization-server-issued client credentials. The client credentials include a + client identifier and an OPTIONAL symmetric shared secret. The means through which the + client obtains these credentials are beyond the scope of this specification, but usually + involve registration with the authorization server. + +</p> +<p> + The client identifier is used by the authorization server to establish the identity of + the client for the purpose of presenting information to the resource owner prior to + granting access, as well as for providing different service levels to different clients. + They can also be used to block unauthorized clients from requesting access. + +</p> +<p> + Due to the nature of some clients, authorization servers SHOULD NOT make assumptions + about the confidentiality of client credentials without establishing trust with the + client operator. Authorization servers SHOULD NOT issue client secrets to the client + incapable or keeping their secrets confidential. + +</p> +<a name="anchor11"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5"></a><h3>3.5. +User Delegation Flows</h3> + +<p> + User delegation flows are used to grant client access to protected resources by the end + user without sharing the end user credentials (e.g. a username and password) with the + client. Instead, the end user authenticates directly with the authorization server, and + grants client access to its protected resources. + +</p> +<a name="user_agent_flow"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.1"></a><h3>3.5.1. +User-Agent Flow</h3> + +<p> + The user-agent flow is a user delegation flow suitable for client applications residing + in a user-agent, typically implemented in a browser using a scripting language such as + JavaScript. The client is capable of interacting with the end user's user-agent but is + incapable of receiving incoming requests from the authorization server (incapable of + acting as an HTTP server). + +</p> +<p> + Instead of receiving incoming requests, the client requests the authorization server to + redirect the user-agent to another web server or local resource accessible to the + browser which is capable of extracting the access token from the response and passing + it to the client. + +</p> +<p> + This user-agent flow does not utilize the client secret since the client executables + reside on the end user's computer or device which makes the client secret accessible + and exploitable. Because the client is incapable of receiving incoming requests, the + access token is encoded into the redirection URI which exposes it to the end user and + other applications residing on the computer or device. + +</p><br /><hr class="insert" /> +<a name="Figure 5"></a> +<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + +----------+ Client Identifier +----------------+ + | |>---(A)-- & Redirection URI --->| | + | | | | + End <--+ - - - +----(B)-- User authenticates -->| Authorization | + User | | | Server | + | |<---(C)-- Redirect URI --------<| | + | Client | with Access Token | | + | in | (w/ Optional Refresh Token) +----------------+ + | Browser | in Fragment + | | +----------------+ + | |>---(D)-- Redirect URI -------->| | + | | without Fragment | Web Server | + | | | with Client | + | (F) |<---(E)-- Web Page with -------<| Resource | + | Access | Script | | + | Token | +----------------+ + +----------+ + +</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 3 </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + The user-agent flow illustrated in <a class='info' href='#Figure 5'>Figure 3</a> includes the following + steps: + + </p> +<blockquote class="text"><dl> +<dt>(A)</dt> +<dd> + The client sends the user-agent to the authorization server and includes its client + identifier and redirection URI in the request. + +</dd> +<dt>(B)</dt> +<dd> + The authorization server authenticates the end user (via the user-agent) and + establishes whether the end user grants or denies the client's access request. + +</dd> +<dt>(C)</dt> +<dd> + Assuming the end user granted access, the authorization server redirects the + user-agent to the redirection URI provided earlier. The redirection URI includes + the access token in the URI fragment. + +</dd> +<dt>(D)</dt> +<dd> + The user-agent follows the redirection instructions by making a request to the web + server which does not include the fragment. The user-agent retains the fragment + information locally. + +</dd> +<dt>(E)</dt> +<dd> + The web server returns a web page containing a script capable of extracting the + access token from the URI fragment retained by the user-agent. + +</dd> +<dt>(F)</dt> +<dd> + The user-agent executes the script provided by the web server which extracts the + access token and passes it to the client. + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor12"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.1.1"></a><h3>3.5.1.1. +Client Requests Authorization</h3> + +<p> + In order for the end user to grant the client access, the client sends the end user + to the authorization server. The client constructs the request URI by adding the + following URI query parameters to the user authorization endpoint URI: + + </p> +<blockquote class="text"><dl> +<dt>type</dt> +<dd> + + REQUIRED. The parameter value MUST be set to + <tt>user_agent</tt> (case sensitive). + +</dd> +<dt>client_id</dt> +<dd> + + REQUIRED. The client identifier as described in <a class='info' href='#client_id'>Section 3.4<span> (</span><span class='info'>Client Credentials</span><span>)</span></a>. + +</dd> +<dt>redirect_uri</dt> +<dd> + + REQUIRED unless a redirection URI has been established between the client and + authorization server via other means. An absolute URI to which the authorization + server will redirect the user-agent to when the end user authorization step is + completed. The authorization server SOULD require the client to pre-register + their redirection URI. The redirection URI MUST NOT includes a query component + as defined by <a class='info' href='#RFC3986'>[RFC3986]<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</span><span>)</span></a> section 3 if the + <tt>state</tt> parameter is present. + +</dd> +<dt>state</dt> +<dd> + + OPTIONAL. An opaque value used by the client to maintain state between the request + and callback. The authorization server includes this value when redirecting the + user-agent back to the client. + +</dd> +<dt>immediate</dt> +<dd> + + OPTIONAL. The parameter value must be set to <tt>true</tt> or + <tt>false</tt> (case sensitive). If set to + <tt>true</tt>, the authorization server MUST NOT prompt the + end user to authenticate or approve access. Instead, the authorization server + attempts to establish the end user's identity via other means (e.g. browser + cookies) and checks if the end user has previously approved an identical access + request by the same client and if that access grant is still active. If the + authorization server does not support an immediate check or if it is unable to + establish the end user's identity or approval status, it MUST deny the request + without prompting the end user. Defaults to <tt>false</tt> if + omitted. + +</dd> +<dt>secret_type</dt> +<dd> + + OPTIONAL. The access token secret type as described by + <a class='info' href='#crypto_token'>Section 5.3<span> (</span><span class='info'>Cryptographic Tokens Requests</span><span>)</span></a>. If omitted, the authorization server will issue a + bearer token (an access token without a matching secret) as described by + <a class='info' href='#bearer_token'>Section 5.2<span> (</span><span class='info'>Bearer Token Requests</span><span>)</span></a>. + +</dd> +</dl></blockquote><p> + +</p> +<p> + The client directs the end user to the constructed URI using an HTTP redirection + response, or by other means available to it via the end user's user-agent. The + request MUST use the HTTP <tt>GET</tt> method. + +</p> +<p> + For example, the client directs the end user's user-agent to make the following + HTTPS request (line breaks are for display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + GET /authorize?type=user_agent&client_id=s6BhdRkqt3& + redirect_uri=https%3A%2F%2FEexample%2Ecom%2Frd HTTP/1.1 + Host: server.example.com + +</pre></div> +<p> + If the client has previously registered a redirection URI with the authorization server, + the authorization server MUST verify that the redirection URI received matches the + registered URI associated with the client identifier. + +</p> +<p> + The authorization server authenticates the end user and obtains an authorization + decision (by asking the end user or establishing approval via other means). The + authorization server sends the end user's user-agent to the provided client + redirection URI using an HTTP redirection response. + +</p> +<a name="anchor13"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.1.1.1"></a><h3>3.5.1.1.1. +End User Grants Authorization</h3> + +<p> + If the end user authorizes the access request, the authorization server issues an + access token and delivers it to the client by adding the following parameters, using + the <tt>application/x-www-form-urlencoded</tt> format as defined + by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a>, to the redirection URI fragment: + + </p> +<blockquote class="text"><dl> +<dt>access_token</dt> +<dd> + + REQUIRED. The access token. + +</dd> +<dt>expires_in</dt> +<dd> + + OPTIONAL. The duration in seconds of the access token lifetime. + +</dd> +<dt>refresh_token</dt> +<dd> + + OPTIONAL. The refresh token. + +</dd> +<dt>state</dt> +<dd> + + REQUIRED if the <tt>state</tt> parameter was present in the + client authorization request. Set to the exact value received from the client. + +</dd> +<dt>access_token_secret</dt> +<dd> + + REQUIRED if requested by the client. The corresponding access token secret as + requested by the client. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example, the authorization server redirects the end user's user-agent by + sending the following HTTP response: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 302 Found + Location: http://example.com/rd#access_token=FJQbwq9&expires_in=3600 + +</pre></div> +<a name="anchor14"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.1.1.2"></a><h3>3.5.1.1.2. +End User Denies Authorization</h3> + +<p> + If the end user denied the access request, the authorization server responds to the + client by adding the following parameters, using the + <tt>application/x-www-form-urlencoded</tt> format as defined by + <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a>, to the redirection URI fragment: + + </p> +<blockquote class="text"><dl> +<dt>error</dt> +<dd> + + REQUIRED. The parameter value MUST be set to + <tt>user_denied</tt> (case sensitive). + +</dd> +<dt>state</dt> +<dd> + + REQUIRED if the <tt>state</tt> parameter was present in the + client authorization request. Set to the exact value received from the client. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example, the authorization server responds with the following: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 302 Found + Location: http://example.com/rd#error=user_denied + +</pre></div> +<p> + The authorization flow concludes unsuccessfully. To extract the error message, the + client follows the steps described in <a class='info' href='#user_agent_extract'>Section 3.5.1.2<span> (</span><span class='info'>Client Extracts Access Token</span><span>)</span></a>. + +</p> +<a name="user_agent_extract"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.1.2"></a><h3>3.5.1.2. +Client Extracts Access Token</h3> + +<p> + The user-agent follows the authorization server redirection response by making an + HTTP <tt>GET</tt> request to the URI received in the + <tt>Location</tt> HTTP response header. The user-agent SHALL NOT + include the fragment component with the request. + +</p> +<p> + For example, the user-agent makes the following HTTP + <tt>GET</tt> request in response to the redirection directive + received from the authorization server: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + GET /rd HTTP/1.1 + Host: example.com + +</pre></div> +<p> + The HTTP response to the redirection request returns a web page (typically an HTML + page with an embedded script) capable of accessing the full redirection URI including + the fragment retained by the user-agent, and extracting the access token (and other + parameters) contained in the fragment. + +</p> +<a name="web_server_flow"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.2"></a><h3>3.5.2. +Web Server Flow</h3> + +<p> + The web server flow is a user delegation flow suitable for clients capable of + interacting with the end user's user-agent (typically a web browser) and capable of + receiving incoming requests from the authorization server (capable of acting as an HTTP + server). + +</p><br /><hr class="insert" /> +<a name="Figure 3"></a> +<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + +----------+ Client Identifier +---------------+ + | -+----(A)-- & Redirect URI ------->| | + | End User | | Authorization | + | at |<---(B)-- User authenticates --->| Server | + | Browser | | | + | -+----(C)-- Verification Code ----<| | + +-|----|---+ +---------------+ + | | ^ v + (A) (C) | | + | | | | + ^ v | | + +---------+ | | + | |>---(D)-- Client Credentials, --------' | + | Web | Verification Code, | + | Client | & Redirect URI | + | | | + | |<---(E)------- Access Token -----------------' + +---------+ (w/ Optional Refresh Token) + +</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 4 </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + The web server flow illustrated in <a class='info' href='#Figure 3'>Figure 4</a> includes the following + steps: + + </p> +<blockquote class="text"><dl> +<dt>(A)</dt> +<dd> + The web client initiates the flow by redirecting the end user's user-agent to the + authorization endpoint with its client identifier and a redirect URI to which the + authorization server will send the end user back once authorization is received (or + denied). + +</dd> +<dt>(B)</dt> +<dd> + The authorization server authenticates the end user (via the user-agent) and + establishes whether the end user grants or denies the client's access request. + +</dd> +<dt>(C)</dt> +<dd> + Assuming the end user granted access, the authorization server redirects the + user-agent back to the client to the redirection URI provided earlier. The + authorization includes a verification code for the client to use to obtain an + access token. + +</dd> +<dt>(D)</dt> +<dd> + The client requests an access token from the authorization server by including its + client credentials (identifier and secret), as well as the verification code + received in the previous step. + +</dd> +<dt>(E)</dt> +<dd> + The authorization server validates the client credentials and the verification + code and responds back with the access token. + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor15"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.2.1"></a><h3>3.5.2.1. +Client Requests Authorization</h3> + +<p> + In order for the end user to grant the client access, the client sends the end user + to the authorization server. The client constructs the request URI by adding the + following URI query parameters to the user authorization endpoint URI: + + </p> +<blockquote class="text"><dl> +<dt>type</dt> +<dd> + + REQUIRED. The parameter value MUST be set to + <tt>web_server</tt> (case sensitive). + +</dd> +<dt>client_id</dt> +<dd> + + REQUIRED. The client identifier as described in <a class='info' href='#client_id'>Section 3.4<span> (</span><span class='info'>Client Credentials</span><span>)</span></a>. + +</dd> +<dt>redirect_uri</dt> +<dd> + + REQUIRED unless a redirection URI has been established between the client and + authorization server via other means. An absolute URI to which the authorization + server will redirect the user-agent to when the end user authorization step is + completed. The authorization server MAY require the client to pre-register + their redirection URI. The redirection URI MUST NOT includes a query component + as defined by <a class='info' href='#RFC3986'>[RFC3986]<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</span><span>)</span></a> section 3 if the + <tt>state</tt> parameter is present. + +</dd> +<dt>state</dt> +<dd> + + OPTIONAL. An opaque value used by the client to maintain state between the request + and callback. The authorization server includes this value when redirecting the + user-agent back to the client. + +</dd> +<dt>immediate</dt> +<dd> + + OPTIONAL. The parameter value must be set to <tt>true</tt> or + <tt>false</tt> (case sensitive). If set to + <tt>true</tt>, the authorization server MUST NOT prompt the + end user to authenticate or approve access. Instead, the authorization server + attempts to establish the end user's identity via other means (e.g. browser + cookies) and checks if the end user has previously approved an identical access + request by the same client and if that access grant is still active. If the + authorization server does not support an immediate check or if it is unable to + establish the end user's identity or approval status, it MUST deny the request + without prompting the end user. Defaults to <tt>false</tt> if + omitted. + +</dd> +</dl></blockquote><p> + +</p> +<p> + The client directs the end user to the constructed URI using an HTTP redirection + response, or by other means available to it via the end user's user-agent. The + request MUST use the HTTP <tt>GET</tt> method. + +</p> +<p> + For example, the client directs the end user's user-agent to make the + following HTTPS requests (line breaks are for display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + GET /authorize?type=web_server&client_id=s6BhdRkqt3&redirect_uri= + https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 + Host: server.example.com + +</pre></div> +<p> + If the client has previously registered a redirection URI with the authorization server, + the authorization server MUST verify that the redirection URI received matches the + registered URI associated with the client identifier. + +</p> +<p> + The authorization server authenticates the end user and obtains an authorization + decision (by asking the end user or establishing approval via other means). The + authorization server sends the end user's user-agent to the provided client + redirection URI using an HTTP redirection response, or by other means available to it + via the end user's user-agent. + +</p> +<a name="anchor16"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.2.1.1"></a><h3>3.5.2.1.1. +End User Grants Authorization</h3> + +<p> + If the end user authorizes the access request, the authorization server generates a + verification code and associates it with the client identifier and redirection URI. The + authorization server constructs the request URI by adding the following parameters to + the query component of redirection URI provided by the client: + + </p> +<blockquote class="text"><dl> +<dt>code</dt> +<dd> + + REQUIRED. The verification code generated by the authorization server. + +</dd> +<dt>state</dt> +<dd> + + REQUIRED if the <tt>state</tt> parameter was present in the + client authorization request. Set to the exact value received from the client. + +</dd> +</dl></blockquote><p> + +</p> +<p> + The verification code SHOULD expire shortly after it is issued and allowed for a + single use. + +</p> +<p> + For example, the authorization server redirects the end user's user-agent by + sending the following HTTP response: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 302 Found + Location: https://client.example.com/cb?code=i1WsRn1uB1 + +</pre></div> +<p> + In turn, the end user's user-agent makes the following HTTPS + <tt>GET</tt> request: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + GET /cb?code=i1WsRn1uB1 HTTP/1.1 + Host: client.example.com + +</pre></div> +<a name="anchor17"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.2.1.2"></a><h3>3.5.2.1.2. +End User Denies Authorization</h3> + +<p> + If the end user denied the access request, the authorization server constructs the + request URI by adding the following parameters to the query component of the + redirection URI provided by the client: + + </p> +<blockquote class="text"><dl> +<dt>error</dt> +<dd> + + REQUIRED. The parameter value MUST be set to + <tt>user_denied</tt> (case sensitive). + +</dd> +<dt>state</dt> +<dd> + + REQUIRED if the <tt>state</tt> parameter was present in the + client authorization request. Set to the exact value received from the client. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example, the authorization server directs the client to make the following HTTP + request: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + GET /cb?error=user_denied HTTP/1.1 + Host: client.example.com + +</pre></div> +<p> + The authorization flow concludes unsuccessfully. + +</p> +<a name="anchor18"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.2.2"></a><h3>3.5.2.2. +Client Requests Access Token</h3> + +<p> + The client obtains an access token from the authorization server by making an HTTP + <tt>POST</tt> request to the token endpoint. The client + constructs a request URI by adding the following parameters to the request: + + </p> +<blockquote class="text"><dl> +<dt>type</dt> +<dd> + + REQUIRED. The parameter value MUST be set to + <tt>web_server</tt> (case sensitive). + +</dd> +<dt>client_id</dt> +<dd> + + REQUIRED. The client identifier as described in <a class='info' href='#client_id'>Section 3.4<span> (</span><span class='info'>Client Credentials</span><span>)</span></a>. + +</dd> +<dt>client_secret</dt> +<dd> + + REQUIRED if the client identifier has a matching secret. The client secret as + described in <a class='info' href='#client_id'>Section 3.4<span> (</span><span class='info'>Client Credentials</span><span>)</span></a>. + +</dd> +<dt>code</dt> +<dd> + + REQUIRED. The verification code received from the authorization server. + +</dd> +<dt>redirect_uri</dt> +<dd> + + REQUIRED. The redirection URI used in the initial request. + +</dd> +<dt>secret_type</dt> +<dd> + + OPTIONAL. The access token secret type as described by + <a class='info' href='#crypto_token'>Section 5.3<span> (</span><span class='info'>Cryptographic Tokens Requests</span><span>)</span></a>. If omitted, the authorization server will issue a + bearer token (an access token without a matching secret) as described by + <a class='info' href='#bearer_token'>Section 5.2<span> (</span><span class='info'>Bearer Token Requests</span><span>)</span></a>. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example, the client makes the following HTTPS request (line breaks are for display + purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + POST /token HTTP/1.1 + Host: server.example.com + Content-Type: application/x-www-form-urlencoded + + type=web_server&client_id=s6BhdRkqt3& + client_secret=gX1fBat3bV&code=i1WsRn1uB1& + redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb + +</pre></div> +<p> + The authorization server MUST verify that the verification code, client identity, + client secret, and redirection URI are all valid and match its stored association. If + the request is valid, the authorization server issues an access token and delivers it + to the client in the HTTP response body using the + <tt>application/x-www-form-urlencoded</tt> content type as defined + by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 200 status code (OK). + +</p> +<p> + The response contains the following parameters: + + </p> +<blockquote class="text"><dl> +<dt>access_token</dt> +<dd> + + REQUIRED. The access token issued by the authorization server. + +</dd> +<dt>expires_in</dt> +<dd> + + OPTIONAL. The duration in seconds of the access token lifetime. + +</dd> +<dt>refresh_token</dt> +<dd> + + OPTIONAL. The refresh token used to obtain new access tokens using the same + end user access grant as described in <a class='info' href='#token_refresh'>Section 4<span> (</span><span class='info'>Refreshing an Access Token</span><span>)</span></a>. + +</dd> +<dt>access_token_secret</dt> +<dd> + + REQUIRED if requested by the client. The corresponding access token secret as + requested by the client. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 200 OK + Content-Type: application/x-www-form-urlencoded + + access_token=SlAV32hkKG&expires_in=3600&refresh_token=8xLOxBtZp8 + +</pre></div> +<p> + If the request is invalid, the authorization server returns an error message in the + HTTP response body using the + <tt>application/x-www-form-urlencoded</tt> content type as defined + by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 400 status code (Bad Request). + +</p> +<p> + The response contains the following parameter: + + </p> +<blockquote class="text"><dl> +<dt>error</dt> +<dd> + + OPTIONAL. The parameter value MUST be set to either + <tt>redirect_uri_mismatch</tt> or + <tt>expired_verification_code</tt> (case sensitive). + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 400 Bad Request + Content-Type: application/x-www-form-urlencoded + + error=expired_verification_code + +</pre></div> +<a name="device_flow"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.3"></a><h3>3.5.3. +Device Flow</h3> + +<p> + The device flow is a user delegation flow suitable for clients executing on devices + which do not have an easy data-entry method (e.g. game consoles or media hub), but + where the end user has separate access to a user-agent on another computer or device + (e.g. home computer, a laptop, or a smartphone). The client is incapable of receiving + incoming requests from the authorization server (incapable of acting as an HTTP + server). + +</p> +<p> + Instead of interacting with the end user's user-agent, the client instructs the end + user to use another computer or device and connect to the authorization server to + approve the access request. Since the client cannot receive incoming requests, it polls the + authorization server repeatedly until the end user completes the approval process. + +</p> +<p> + This device flow does not utilize the client secret since the client executables + reside on a local device which makes the client secret accessible and exploitable. + +</p><br /><hr class="insert" /> +<a name="Figure 6"></a> +<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + +----------+ +----------------+ + | |>---(A)-- Client Identifier --->| | + | | | | + | |<---(B)-- Verification Code, --<| | + | | User Code, | | + | | & Verification URI | | + | Device | | | + | Client | Client Identifier & | | + | |>---(E)-- Verification Code --->| | + | | ... | | + | |>---(E)---> | | + | | | Authorization | + | |<---(F)-- Access Token --------<| Server | + +----------+ (w/ Optional Refresh Token) | | + v | | + : | | + (C) User Code & Verification URI | | + : | | + v | | + +----------+ | | + | End User | | | + | at |<---(D)-- User authenticates -->| | + | Browser | | | + +----------+ +----------------+ + +</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 5 </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + The device flow illustrated in <a class='info' href='#Figure 6'>Figure 5</a> includes the following + steps: + + </p> +<blockquote class="text"><dl> +<dt>(A)</dt> +<dd> + The client requests access from the authorization server and includes its client + identifier in the request. + +</dd> +<dt>(B)</dt> +<dd> + The authorization server issues a verification code, a user code, and provides the + end user authorization URI. + +</dd> +<dt>(C)</dt> +<dd> + The client instructs the end user to use its user-agent (elsewhere) and visit the + provided authorization URI. The client provides the user with the user code to + enter in order to grant access. + +</dd> +<dt>(D)</dt> +<dd> + The authorization server authenticates the end user (via the user-agent) and + prompts the end user to grant the client's access request by entering the user + code provided by the client. + +</dd> +<dt>(E)</dt> +<dd> + While the end user authorizes (or denies) the client's request (D), the client + repeatedly polls the authorization server to find out if the end user completed the + user authorization step. The client includes the verification code and its client + identifier. + +</dd> +<dt>(F)</dt> +<dd> + Assuming the end user granted access, the authorization server validates the + verification code provided by the client and responds back with the access token. + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor19"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.3.1"></a><h3>3.5.3.1. +Client Requests Authorization</h3> + +<p> + The client initiates the flow by requesting a set of verification codes from the + authorization server by making an HTTP <tt>GET</tt> request to the + authorization endpoint. The client constructs a request URI by adding the following + parameters to the request: + + </p> +<blockquote class="text"><dl> +<dt>type</dt> +<dd> + + REQUIRED. The parameter value MUST be set to 'device' (case sensitive). + +</dd> +<dt>client_id</dt> +<dd> + + REQUIRED. The client identifier as described in <a class='info' href='#client_id'>Section 3.4<span> (</span><span class='info'>Client Credentials</span><span>)</span></a>. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example, the client makes the following HTTPS request (line breaks are for + display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + GET /authorize?type=device&client_id=s6BhdRkqt3 + HTTP/1.1 + Host: server.example.com + +</pre></div> +<p> + In response, the authorization server generates a verification code and a user code + and includes them in the HTTP response body using the + <tt>application/x-www-form-urlencoded</tt> format as defined by + <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 200 status code (OK). The + response contains the following parameters: + + </p> +<blockquote class="text"><dl> +<dt>code</dt> +<dd> + + REQUIRED. The verification code. + +</dd> +<dt>user_code</dt> +<dd> + + REQUIRED. The user code. + +</dd> +<dt>user_uri</dt> +<dd> + + REQUIRED. The user authorization URI on the authorization server. + +</dd> +<dt>expires_in</dt> +<dd> + + OPTIONAL. The duration in seconds of the verification code lifetime. + +</dd> +<dt>interval</dt> +<dd> + + OPTIONAL. The minimum amount of time in seconds that the client SHOULD wait + between polling requests to the token endpoint. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example (line breaks are for display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 200 OK + Content-Type: application/x-www-form-urlencoded + + device_code=74tq5miHKB&user_code=94248&user_uri=http%3A%2F%2 + Fwww%2Eexample%2Ecom%2Fdevice&interval=5 + +</pre></div> +<p> + The client displays the user code and the user authorization URI to the end-user, and + instructs the end user to visit the URI using a user-agent and enter the user code. + +</p> +<p> + The end user manually types the provided URI and authenticates with the authorization + server. The authorization server prompts the end user to authorize the client's + request by entering the user code provided by the client. Once the end user approves + or denies the request, the authorization server informs the end user to return to the + device for further instructions. + +</p> +<a name="anchor20"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.3.2"></a><h3>3.5.3.2. +Client Requests Access Token</h3> + +<p> + Since the client is unable to receive incoming requests from the authorization + server, it polls the authorization server repeatedly until the end user grants or + denies the request, or the verification code expires. + +</p> +<p> + The client makes the following request at an arbitrary but reasonable interval which + MUST NOT exceed the minimum interval rate provided by the authorization server (if + present via the <tt>interval</tt> parameter). Alternatively, the + client MAY provide a user interface for the end user to manually inform it when + authorization was granted. + +</p> +<p> + The client requests an access token by making an HTTP <tt>GET</tt> + request to the token endpoint. The client constructs a request URI by adding + the following parameters to the request: + + </p> +<blockquote class="text"><dl> +<dt>type</dt> +<dd> + + REQUIRED. The parameter value MUST be set to 'device' (case sensitive). + +</dd> +<dt>client_id</dt> +<dd> + + REQUIRED. The client identifier as described in <a class='info' href='#client_id'>Section 3.4<span> (</span><span class='info'>Client Credentials</span><span>)</span></a>. + +</dd> +<dt>code</dt> +<dd> + + The verification code received from the authorization server. + +</dd> +<dt>secret_type</dt> +<dd> + + OPTIONAL. The access token secret type as described by + <a class='info' href='#crypto_token'>Section 5.3<span> (</span><span class='info'>Cryptographic Tokens Requests</span><span>)</span></a>. If omitted, the authorization server will issue a + bearer token (an access token without a matching secret) as described by + <a class='info' href='#bearer_token'>Section 5.2<span> (</span><span class='info'>Bearer Token Requests</span><span>)</span></a>. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example, the client makes the following HTTPS request (line breaks are for display + purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + GET /token?type=device&client_id=s6BhdRkqt3 + &code=J2vC42OifV HTTP/1.1 + Host: server.example.com + +</pre></div> +<a name="anchor21"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.3.2.1"></a><h3>3.5.3.2.1. +End User Grants Authorization</h3> + +<p> + If the end user authorized the request, the authorization server issues an access + token and delivers it to the client by including it in the HTTP response + body using the <tt>application/x-www-form-urlencoded</tt> + content type as defined by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 200 + status code (OK). The response contains the following parameters: + + </p> +<blockquote class="text"><dl> +<dt>access_token</dt> +<dd> + + REQUIRED. The access token. + +</dd> +<dt>expires_in</dt> +<dd> + + OPTIONAL. The duration in seconds of the access token lifetime. + +</dd> +<dt>refresh_token</dt> +<dd> + + OPTIONAL. The refresh token. + +</dd> +<dt>access_token_secret</dt> +<dd> + + REQUIRED if requested by the client. The corresponding access token secret as + requested by the client. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 200 OK + Content-Type: application/x-www-form-urlencoded + + access_token=FJQbwq9OD8&expires_in=3600 + +</pre></div> +<a name="anchor22"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.3.2.2"></a><h3>3.5.3.2.2. +End User Denies Authorization</h3> + +<p> + If the end user denied the request, the authorization server provides the client + with the error message in the HTTP response body using the + <tt>application/x-www-form-urlencoded</tt> content type as + defined by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 400 status code + (Bad Request). The response contains the following parameters: + + </p> +<blockquote class="text"><dl> +<dt>error</dt> +<dd> + + REQUIRED. Value must be set to + <tt>authorization_declined</tt>. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 400 Bad Request + Content-Type: application/x-www-form-urlencoded + + error=authorization_declined + +</pre></div> +<a name="anchor23"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.5.3.2.3"></a><h3>3.5.3.2.3. +End User Authorization Pending or Expired</h3> + +<p> + If the end user authorization is pending or expired without receiving any response + from the end user, or the client is exceeding the allowed polling interval, the + authorization server provides the client with the error message in the HTTP + response body using the <tt>application/x-www-form-urlencoded</tt> + content type as defined by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 400 + status code (Bad Request). The response contains the following parameters: + + </p> +<blockquote class="text"><dl> +<dt>error</dt> +<dd> + + REQUIRED. Value MUST be set to + <tt>authorization_pending</tt>, + <tt>slow_down</tt>, or + <tt>code_expired</tt> (case sensitive). + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 400 Bad Request + Content-Type: application/x-www-form-urlencoded + + error=authorization_pending + +</pre></div> +<a name="anchor24"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.6"></a><h3>3.6. +End User Credentials Flows</h3> + +<p> + End user credential flows are used to grant client access to protected resources by the + end user directly sharing the end user credentials (typically a username and password) + with the client. Unlike user delegation flows, end user credentials flows require a much + higher degree of trust between the client and end user. + +</p> +<p> + These flows are suitable in cases where the end user already has a trust relationship + with the client, such as its computer operating system or highly privileged applications. + Authorization servers SHOULD take special care when enabling user credentials flows, and + SHOULD only do so when other delegation flows are not viable. + +</p> +<p> + However, unlike the HTTP Basic authentication scheme defined in + <a class='info' href='#RFC2617'>[RFC2617]<span> (</span><span class='info'>Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</span><span>)</span></a>, the end user's credentials are used in a single request and + are exchanged for an access token and refresh token which eliminates the client need to + store them for future use. + +</p> +<a name="username_password_flow"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.6.1"></a><h3>3.6.1. +Username and Password Flow</h3> + +<p> + The username and password flow is an end user credentials flow suitable for clients + capable of asking end users for their usernames and passwords. It is also used to + migrate existing clients using direct authentication schemes such as HTTP Basic or + Digest authentication to OAuth by converting the end user credentials stored with + tokens. + +</p> +<p> + The methods through which the client prompts end users for their usernames and + passwords is beyond the scope of this specification. The client MUST discard the + usernames and passwords once an access token has been obtained. + +</p><br /><hr class="insert" /> +<a name="Figure 7"></a> +<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + End User + v + : + (A) + : + v + +--------+ +---------------+ + | | Client Credentials | | + | |>--(B)--- & User Credentials ---->| Authorization | + | Client | | Server | + | |<--(C)---- Access Token ---------<| | + | | (w/ Optional Refresh Token) | | + +--------+ +---------------+ + +</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 6 </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + The username and password flow illustrated in <a class='info' href='#Figure 7'>Figure 6</a> includes the + following steps: + + </p> +<blockquote class="text"><dl> +<dt>(A)</dt> +<dd> + The end user provides the client with its username and password. + +</dd> +<dt>(B)</dt> +<dd> + The client sends an access token request to the authorization server and includes + its client identifier and client secret, and the end user's username and password. + +</dd> +<dt>(C)</dt> +<dd> + The authorization server validates the end user credentials and the client + credentials and issues an access token. + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor25"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.6.1.1"></a><h3>3.6.1.1. +Client Requests Access Token</h3> + +<p> + The client requests an access token by making an HTTP <tt>POST</tt> + request to the token endpoint. The client constructs a request URI by adding + the following parameters to the request: + + </p> +<blockquote class="text"><dl> +<dt>type</dt> +<dd> + + REQUIRED. The parameter value MUST be set to 'username' (case sensitive). + +</dd> +<dt>client_id</dt> +<dd> + + REQUIRED. The client identifier as described in <a class='info' href='#client_id'>Section 3.4<span> (</span><span class='info'>Client Credentials</span><span>)</span></a>. + +</dd> +<dt>client_secret</dt> +<dd> + + REQUIRED. The client secret as described in <a class='info' href='#client_id'>Section 3.4<span> (</span><span class='info'>Client Credentials</span><span>)</span></a>. OPTIONAL + if no client secret was issued. + +</dd> +<dt>username</dt> +<dd> + + REQUIRED. The end user's username. + +</dd> +<dt>password</dt> +<dd> + + REQUIRED. The end user's password. + +</dd> +<dt>secret_type</dt> +<dd> + + OPTIONAL. The access token secret type as described by + <a class='info' href='#crypto_token'>Section 5.3<span> (</span><span class='info'>Cryptographic Tokens Requests</span><span>)</span></a>. If omitted, the authorization server will issue a + bearer token (an access token without a matching secret) as described by + <a class='info' href='#bearer_token'>Section 5.2<span> (</span><span class='info'>Bearer Token Requests</span><span>)</span></a>. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example, the client makes the following HTTPS request (line breaks are for + display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + POST /token HTTP/1.1 + Host: server.example.com + + type=username&client_id=s6BhdRkqt3&client_secret= + 47HDu8s&username=johndoe&password=A3ddj3w + +</pre></div> +<p> + The authorization server MUST validate the client credentials and end user credentials + and if valid issue an access token and deliver to the client in the HTTP response body + using the <tt>application/x-www-form-urlencoded</tt> content type as + defined by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 200 status code (OK). + +</p> +<p> + The response contains the following parameters: + + </p> +<blockquote class="text"><dl> +<dt>access_token</dt> +<dd> + + REQUIRED. The access token. + +</dd> +<dt>expires_in</dt> +<dd> + + OPTIONAL. The duration in seconds of the access token lifetime. + +</dd> +<dt>refresh_token</dt> +<dd> + + OPTIONAL. The refresh token. + +</dd> +<dt>access_token_secret</dt> +<dd> + + REQUIRED if requested by the client. The corresponding access token secret as + requested by the client. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 200 OK + Content-Type: application/x-www-form-urlencoded + + access_token=FJQbwq9OD8&refresh_token=gO3CHNqpH8 + +</pre></div> +<p> + If the request is invalid, the authorization server returns an error message in the + HTTP response body using the + <tt>application/x-www-form-urlencoded</tt> content type as defined + by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 400 status code (Bad Request). + +</p> +<p> + The response contains the following parameter: + + </p> +<blockquote class="text"><dl> +<dt>error</dt> +<dd> + + OPTIONAL. The parameter value MUST be set to either + <tt>incorrect_credentials</tt> or + <tt>unauthorized_client</tt> (case sensitive). + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 400 Bad Request + Content-Type: application/x-www-form-urlencoded + + error=incorrect_credentials + +</pre></div> +<a name="anchor26"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.7"></a><h3>3.7. +Autonomous Client Flows</h3> + +<p> + Autonomous client flows are used to grant client access to protected resources controlled + by the client (i.e. the client is the resource owner). For example, these flows are + useful when a service provides both client-specific resources in addition to end user + resources. + +</p> +<a name="client_credentials_flow"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.7.1"></a><h3>3.7.1. +Client Credentials Flow</h3> + +<p> + The client credentials flow is used when the client acts autonomously without acting on + behalf of a separate resource owner. The client secret is assumed to be high-entropy + since it is not designed to be memorize by an end user. + +</p><br /><hr class="insert" /> +<a name="Figure 8"></a> +<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + + +--------+ +---------------+ + | | | | + | |>--(A)--- Client Credentials ---->| Authorization | + | Client | | Server | + | |<--(B)---- Access Token ---------<| | + | | (w/ Optional Refresh Token) | | + +--------+ +---------------+ + +</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 7 </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + The client credential flow illustrated in <a class='info' href='#Figure 8'>Figure 7</a> includes the + following steps: + + </p> +<blockquote class="text"><dl> +<dt>(A)</dt> +<dd> + The client sends an access token request to the authorization server and includes + its client identifier and client secret. + +</dd> +<dt>(B)</dt> +<dd> + The authorization server validates the client credentials and issues an access + token. + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor27"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.7.1.1"></a><h3>3.7.1.1. +Client Requests Access Token</h3> + +<p> + The client requests an access token by making an HTTP <tt>POST</tt> + request to the token endpoint. The client constructs a request URI by adding + the following parameters to the request: + + </p> +<blockquote class="text"><dl> +<dt>type</dt> +<dd> + + REQUIRED. The parameter value MUST be set to 'client_cred' (case sensitive). + +</dd> +<dt>client_id</dt> +<dd> + + REQUIRED. The client identifier as described in <a class='info' href='#client_id'>Section 3.4<span> (</span><span class='info'>Client Credentials</span><span>)</span></a>. + +</dd> +<dt>client_secret</dt> +<dd> + + REQUIRED. The client secret as described in <a class='info' href='#client_id'>Section 3.4<span> (</span><span class='info'>Client Credentials</span><span>)</span></a>. + +</dd> +<dt>secret_type</dt> +<dd> + + OPTIONAL. The access token secret type as described by + <a class='info' href='#crypto_token'>Section 5.3<span> (</span><span class='info'>Cryptographic Tokens Requests</span><span>)</span></a>. If omitted, the authorization server will issue a + bearer token (an access token without a matching secret) as described by + <a class='info' href='#bearer_token'>Section 5.2<span> (</span><span class='info'>Bearer Token Requests</span><span>)</span></a>. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example, the client makes the following HTTPS request (line breaks are for + display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + POST /token HTTP/1.1 + Host: server.example.com + + type=client_cred&client_id=s6BhdRkqt3&client_secret=47HDu8s + +</pre></div> +<p> + The authorization server MUST validate the client credentials and if valid issue an + access token and deliver to the client in the HTTP response body using the + <tt>application/x-www-form-urlencoded</tt> content type as defined + by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 200 status code (OK). + +</p> +<p> + The response contains the following parameters: + + </p> +<blockquote class="text"><dl> +<dt>access_token</dt> +<dd> + + REQUIRED. The access token. + +</dd> +<dt>expires_in</dt> +<dd> + + OPTIONAL. The duration in seconds of the access token lifetime. + +</dd> +<dt>refresh_token</dt> +<dd> + + OPTIONAL. The refresh token. + +</dd> +<dt>access_token_secret</dt> +<dd> + + REQUIRED if requested by the client. The corresponding access token secret as + requested by the client. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 200 OK + Content-Type: application/x-www-form-urlencoded + + access_token=FJQbwq9OD8 + +</pre></div> +<p> + If the request is invalid, the authorization server returns an error message in the + HTTP response body using the + <tt>application/x-www-form-urlencoded</tt> content type as defined + by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 400 status code (Bad Request). + +</p> +<p> + The response contains the following parameter: + + </p> +<blockquote class="text"><dl> +<dt>error</dt> +<dd> + + OPTIONAL. The parameter value MUST be set to either + <tt>incorrect_credentials</tt> or + <tt>unauthorized_client</tt> (case sensitive). + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 400 Bad Request + Content-Type: application/x-www-form-urlencoded + + error=incorrect_credentials + +</pre></div> +<a name="assertion_flow"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.7.2"></a><h3>3.7.2. +Assertion Flow</h3> + +<p> + The assertion flow requires the client to obtain a assertion such as a + <a class='info' href='#OASIS.saml-core-2.0-os'>SAML<span> (</span><span class='info'>Cantor, S., Kemp, J., Philpott, R., and E. Maler, “Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.</span><span>)</span></a> [OASIS.saml‑core‑2.0‑os] assertion from an assertion issuer + prior to initiating the flow. The process in which the assertion is obtained is defined + by the assertion issuer and the authorization server, and is beyond the scope of this + specification. + +</p> +<p> + The client credentials flow is used when the client acts autonomously without acting on + behalf of a separate resource owner. + +</p><br /><hr class="insert" /> +<a name="Figure 9"></a> +<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + + +--------+ +---------------+ + | | | | + | |>--(A)------ Assertion ---------->| Authorization | + | Client | | Server | + | |<--(B)---- Access Token ---------<| | + | | (w/ Optional Refresh Token) | | + +--------+ +---------------+ + +</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 8 </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + The client credential flow illustrated in <a class='info' href='#Figure 9'>Figure 8</a> includes the + following steps: + + </p> +<blockquote class="text"><dl> +<dt>(A)</dt> +<dd> + The client sends an access token request to the authorization server and includes + an assertion. + +</dd> +<dt>(B)</dt> +<dd> + The authorization server validates the assertion and issues an access token. + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor28"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.7.2.1"></a><h3>3.7.2.1. +Client Requests Access Token</h3> + +<p> + The client requests an access token by making an HTTP <tt>POST</tt> + request to the token endpoint. The client constructs a request URI by adding + the following parameters to the request: + + </p> +<blockquote class="text"><dl> +<dt>type</dt> +<dd> + + REQUIRED. The parameter value MUST be set to 'assertion' (case sensitive). + +</dd> +<dt>format</dt> +<dd> + + REQUIRED. The format of the assertion as defined by the authorization server. + +</dd> +<dt>assertion</dt> +<dd> + + REQUIRED. The assertion. + +</dd> +<dt>secret_type</dt> +<dd> + + OPTIONAL. The access token secret type as described by + <a class='info' href='#crypto_token'>Section 5.3<span> (</span><span class='info'>Cryptographic Tokens Requests</span><span>)</span></a>. If omitted, the authorization server will issue a + bearer token (an access token without a matching secret) as described by + <a class='info' href='#bearer_token'>Section 5.2<span> (</span><span class='info'>Bearer Token Requests</span><span>)</span></a>. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example, the client makes the following HTTPS request (line breaks are for + display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + POST /token HTTP/1.1 + Host: server.example.com + + type=assertion&format=_______&assertion=_______ + +</pre></div> +<p> + The authorization server MUST validate the assertion and if valid issue an access + token and deliver to the client in the HTTP response body using the + <tt>application/x-www-form-urlencoded</tt> content type as defined + by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 200 status code (OK). + +</p> +<p> + The response contains the following parameters: + + </p> +<blockquote class="text"><dl> +<dt>access_token</dt> +<dd> + + REQUIRED. The access token. + +</dd> +<dt>expires_in</dt> +<dd> + + OPTIONAL. The duration in seconds of the access token lifetime. + +</dd> +<dt>refresh_token</dt> +<dd> + + OPTIONAL. The refresh token. + +</dd> +<dt>access_token_secret</dt> +<dd> + + REQUIRED if requested by the client. The corresponding access token secret as + requested by the client. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 200 OK + Content-Type: application/x-www-form-urlencoded + + access_token=FJQbwq9OD8 + +</pre></div> +<p> + If the assertion is invalid, the authorization server returns an error message in the + HTTP response body using the + <tt>application/x-www-form-urlencoded</tt> content type as defined + by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 400 status code (Bad Request). + +</p> +<p> + The response contains the following parameter: + + </p> +<blockquote class="text"><dl> +<dt>error</dt> +<dd> + + OPTIONAL. The parameter value MUST be set to either + <tt>invalid_assertion</tt> or + <tt>unknown_format</tt> (case sensitive). + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 400 Bad Request + Content-Type: application/x-www-form-urlencoded + + error=incorrect_credentials + +</pre></div> +<p> + Authorization servers SHOULD issue access tokens with a limited lifetime and require + clients to refresh them by requesting a new access token using the same assertion if it + is still valid. Otherwise the client MUST obtain a new valid assertion. + +</p> +<a name="token_refresh"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4"></a><h3>4. +Refreshing an Access Token</h3> + +<p> + Token refresh is used when the lifetime of an access token is shorter than the lifetime of + the authorization grant. It allows clients to obtain a new access token without having to + go through the authorization flow again or involve the resource owner. It is also used to + obtain a new token with different security properties (e.g. bearer token, token with + shared symmetric secret). + +</p><br /><hr class="insert" /> +<a name="Figure 10"></a> +<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + +--------+ Client Credentials, +---------------+ + | | Refresh Token, | | + | |>--(A)----- & Secret Type ------->| Authorization | + | Client | | Server | + | |<--(B)----- Access Token --------<| | + | | & Optional Secret | | + +--------+ +---------------+ + +</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 9 </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + To refresh a token, the client constructs an HTTP <tt>POST</tt> request + to the token endpoint and includes the following parameters in the HTTP request + body using the <tt>application/x-www-form-urlencoded</tt> content type + as defined by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a>: + + </p> +<blockquote class="text"><dl> +<dt>type</dt> +<dd> + + REQUIRED. The parameter value MUST be set to 'refresh' (case sensitive). + +</dd> +<dt>client_id</dt> +<dd> + + REQUIRED. The client identifier as described in <a class='info' href='#client_id'>Section 3.4<span> (</span><span class='info'>Client Credentials</span><span>)</span></a>. + +</dd> +<dt>client_secret</dt> +<dd> + + REQUIRED if the client was issued a secret. The client secret. + +</dd> +<dt>refresh_token</dt> +<dd> + + REQUIRED. The refresh token associated with the access token to be refreshed. + +</dd> +<dt>secret_type</dt> +<dd> + + OPTIONAL. The access token secret type as described by <a class='info' href='#crypto_token'>Section 5.3<span> (</span><span class='info'>Cryptographic Tokens Requests</span><span>)</span></a>. + If omitted, the authorization server will issue a bearer token (an access token without + a matching secret) as described by <a class='info' href='#bearer_token'>Section 5.2<span> (</span><span class='info'>Bearer Token Requests</span><span>)</span></a>. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example, the client makes the following HTTPS request (line break are for display + purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + + POST /authorize HTTP/1.1 + Host: server.example.com + Content-Type: application/x-www-form-urlencoded + + type=refresh_token&client_id=s6BhdRkqt3&client_secret=8eSEIpnqmM + &refresh_token=n4E9O119d&secret_type=hmac-sha256 + +</pre></div> +<p> + The authorization server MUST verify the client credential, the validity of the refresh + token, and that the resource owner's authorization is still valid. If the request is valid, + the authorization server issues a new access token and includes the following parameters in + the HTTP response body using the + <tt>application/x-www-form-urlencoded</tt> content type as defined by + <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 200 status code (OK): + + </p> +<blockquote class="text"><dl> +<dt>access_token</dt> +<dd> + + REQUIRED. The access token. + +</dd> +<dt>expires_in</dt> +<dd> + + OPTIONAL. The duration in seconds of the access token lifetime. + +</dd> +<dt>access_token_secret</dt> +<dd> + + REQUIRED if requested by the client. The corresponding access token secret as requested + by the client. + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + + HTTP/1.1 200 OK + Content-Type: application/x-www-form-urlencoded + + access_token=8F44J2HGMl&access_token_secret=hfd83hjd&expires_in=3600 + +</pre></div> +<p> + If the request fails verification, the authorization server returns an error message in the + HTTP response body using the + <tt>application/x-www-form-urlencoded</tt> content type as defined + by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a> with a 400 status code (Bad Request). + +</p> +<p> + The response contains the following parameter: + + </p> +<blockquote class="text"><dl> +<dt>error</dt> +<dd> + + OPTIONAL. The parameter value MUST be set to either + <tt>incorrect_credentials</tt>, + <tt>authorization_expired</tt>, or + <tt>unsupported_secret_type</tt> (case sensitive). + +</dd> +</dl></blockquote><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 400 Bad Request + Content-Type: application/x-www-form-urlencoded + + error=incorrect_credentials + +</pre></div> +<a name="access_resource"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5"></a><h3>5. +Accessing a Protected Resource</h3> + +<p> + Clients access protected resources by presenting an access token to the resource server. + The methods used by the resource server to validate the access token are beyond the scope + of this specification, but generally involve an interaction or coordination between the + resource server and authorization server. + +</p> +<p> + The method in which a client uses an access token depends on the security properties of the + access tokens. By default, access tokens are issued without a matching secret. Clients MAY + request an access token with a matchin secret by specifying the desired secret type using + the <tt>secret_type</tt> token request parameter. + +</p> +<p> + When an access token does not include a matching secret, the access token acts as a bearer + token, where the token string is a shared symmetric secret. This requires treating the + access token with the same care as other secrets (e.g. user passwords). Access tokens + SHOULD NOT be sent in the clear over an insecure channel. + +</p> +<p> + However, when it is necessary to transmit bearer tokens in the clear without a secure + channel, authorization servers must issue access tokens with limited scope and lifetime to + reduce the potential risk from a compromised access token. Clients SHOULD request and + utilize an access token with a matching secret when making protected resource requests over + an insecure channel (e.g. an HTTP request without using SSL/TLS). + +</p> +<p> + When an access token includes a matching secret, the secret is not included directly in the + request but is used instead to generate a cryptographic signature of the request. The + signature can only be generated and verified by entities with access to the secret. + +</p> +<p> + Clients SHOULD NOT make authenticated requests with an access token to unfamiliar resource + servers, especially when using bearer tokens, regardless of the presence of a secure + channel. + +</p> +<a name="authz_header"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.1"></a><h3>5.1. +The Authorization Request Header</h3> + +<p> + The <tt>Authorization</tt> request header field is used by clients to + make both bearer token and cryptographic token requests. When making bearer token + requests, the client uses the <tt>token</tt> attribute to include the + access token in the request without any of the other attributes. Additional methods for + making bearer token requests are described in <a class='info' href='#bearer_token'>Section 5.2<span> (</span><span class='info'>Bearer Token Requests</span><span>)</span></a>. + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + GET /resource HTTP/1.1 + Host: server.example.com + Authorization: Token token="vF9dft4qmT" + +</pre></div> +<p> + When making a cryptographic token request (using an access token with a matching secret) + the client uses the <tt>token</tt> attribute to include the access + token in the request, and uses the <tt>nonce</tt>, + <tt>timestamp</tt>, <tt>algorithm</tt>, and + <tt>signature</tt> attributes to apply the matching secret. + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + GET /resource HTTP/1.1 + Host: server.example.com + Authorization: Token token="vF9dft4qmT", + nonce="s8djwd", + timestamp="137131200", + algorithm="hmac-sha256", + signature="wOJIO9A2W5mFwDgiDvZbTSMK/PY=" + +</pre></div> +<p> + The <tt>Authorization</tt> header field uses the framework defined by + <a class='info' href='#RFC2617'>[RFC2617]<span> (</span><span class='info'>Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</span><span>)</span></a> as follows: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + credentials = "Token" RWS token-response + + token-response = token-id + [ CS nonce ] + [ CS timestamp ] + [ CS algorithm ] + [ CS signature ] + + token-id = "token" "=" <"> token <"> + timestamp = "timestamp" "=" <"> 1*DIGIT <"> + nonce = "nonce" "=" <"> token <"> + + algorithm = "algorithm" "=" algorithm-name + algorithm-name = "hmac-sha256" / + token + + signature = "signature" "=" <"> token <"> + +</pre></div> +<a name="bearer_token"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.2"></a><h3>5.2. +Bearer Token Requests</h3> + +<p> + Clients make bearer token requests by including the access token using the HTTP + <tt>Authorization</tt> request header with the + <tt>Token</tt> authentication scheme as described in + <a class='info' href='#authz_header'>Section 5.1<span> (</span><span class='info'>The Authorization Request Header</span><span>)</span></a>. The access token is included using the + <tt>token</tt> parameter. + +</p> +<p> + For example, the client makes the following HTTPS request: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + GET /resource HTTP/1.1 + Host: server.example.com + Authorization: Token token="vF9dft4qmT" + +</pre></div> +<p> + The resource server MUST validate the access token and ensure it has not expired and + that its scope covers the requested resource. If the token expired or is invalid, the + resource server MUST reply with an HTTP 401 status code (Unauthorized) and include + the HTTP <tt>WWW-Authenticate</tt> response header as described in + <a class='info' href='#authn_header'>Section 6.1<span> (</span><span class='info'>The WWW-Authenticate Response Header</span><span>)</span></a>. + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 401 Unauthorized + WWW-Authenticate: Token realm='Service', error='token_expired' + +</pre></div> +<p> + Alternatively, the client MAY include the access token using the HTTP request URI in the + query component as described in <a class='info' href='#query_param'>Section 5.2.1<span> (</span><span class='info'>URI Query Parameter</span><span>)</span></a>, or in the HTTP body when + using the <tt>application/x-www-form-urlencoded</tt> content type as + described in <a class='info' href='#body_param'>Section 5.2.2<span> (</span><span class='info'>Form-Encoded Body Parameter</span><span>)</span></a>. Clients SHOULD only use the request URI or + body when the <tt>Authorization</tt> request header is not available, + and MUST NOT use more than one method in each request. + +</p> +<a name="query_param"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.2.1"></a><h3>5.2.1. +URI Query Parameter</h3> + +<p> + When including the access token in the HTTP request URI, the client adds the access + token to the request URI query component as defined by <a class='info' href='#RFC3986'>[RFC3986]<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</span><span>)</span></a> using + the <tt>oauth_token</tt> parameter. + +</p> +<p> + For example, the client makes the following HTTPS request: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + + GET /resource?oauth_token=vF9dft4qmT HTTP/1.1 + Host: server.example.com + +</pre></div> +<p> + The HTTP request URI query can include other request-specific parameters, in which + case, the <tt>oauth_token</tt> parameters SHOULD be appended + following the request-specific parameters, properly separated by an + <tt>&</tt> character (ASCII code 38). + +</p> +<p> + The resource server MUST validate the access token and ensure it has not expired and + its includes the requested resource. If the resource expired or is not valid, the + resource server MUST reply with an HTTP 401 status code (Unauthorized) and include the + HTTP <tt>WWW-Authenticate</tt> response header as described in + <a class='info' href='#authn_header'>Section 6.1<span> (</span><span class='info'>The WWW-Authenticate Response Header</span><span>)</span></a>. + +</p> +<a name="body_param"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.2.2"></a><h3>5.2.2. +Form-Encoded Body Parameter</h3> + +<p> + When including the access token in the HTTP request entity-body, the client adds the + access token to the request body using the <tt>oauth_token</tt> + parameter. The client can use this method only if the following REQUIRED conditions are + met: + + </p> +<ul class="text"> +<li> + The entity-body is single-part. + +</li> +<li> + The entity-body follows the encoding requirements of the + <tt>application/x-www-form-urlencoded</tt> content-type as + defined by <a class='info' href='#W3C.REC-html40-19980424'>[W3C.REC‑html40‑19980424]<span> (</span><span class='info'>Hors, A., Jacobs, I., and D. Raggett, “HTML 4.0 Specification,” April 1998.</span><span>)</span></a>. + +</li> +<li> + The HTTP request entity-header includes the <tt>Content-Type</tt> + header field set to <tt>application/x-www-form-urlencoded</tt>. + +</li> +<li> + The HTTP request method is <tt>POST</tt>, + <tt>PUT</tt>, or <tt>DELETE</tt>. + +</li> +</ul><p> + +</p> +<p> + The entity-body can include other request-specific parameters, in which case, the + <tt>oauth_token</tt> parameters SHOULD be appended following the + request-specific parameters, properly separated by an <tt>&</tt> + character (ASCII code 38). + +</p> +<p> + For example, the client makes the following HTTPS request: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + + POST /resource HTTP/1.1 + Host: server.example.com + Content-Type: application/x-www-form-urlencoded + + oauth_token=vF9dft4qmT + +</pre></div> +<p> + The resource server MUST validate the access token and ensure it has not expired and + its includes the requested resource. If the resource expired or is not valid, the + resource server MUST reply with an HTTP 401 status code (Unauthorized) and include the + HTTP <tt>WWW-Authenticate</tt> response header as described in + <a class='info' href='#authn_header'>Section 6.1<span> (</span><span class='info'>The WWW-Authenticate Response Header</span><span>)</span></a>. + +</p> +<a name="crypto_token"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.3"></a><h3>5.3. +Cryptographic Tokens Requests</h3> + +<p> + Clients make authenticated protected resource requests using an access token with a + matching secret by calculating a set of values and including them in the request using + the <tt>Authorization</tt> header field. The way clients calculate + these values depends on the access token secret type as issued by the authorization + server. + +</p> +<p> + This specification defines the <tt>hmac-sha256</tt> algorithm, and + establishes a registry for providing additional algorithms. Clients obtain an access + token with a matchin <tt>hmac-sha256</tt> secret by using the + <tt>token_type</tt> parameter when requesting an access token. + +</p> +<a name="hmac-sha256"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.3.1"></a><h3>5.3.1. +The 'hmac-sha256' Algorithm</h3> + +<p> + The <tt>hmac-sha256</tt> algorithm uses the HMAC method as defined + in <a class='info' href='#RFC2104'>[RFC2104]<span> (</span><span class='info'>Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” February 1997.</span><span>)</span></a> together with the SHA-256 hash function defined in + <a class='info' href='#NIST FIPS-180-3'>[NIST FIPS‑180‑3]<span> (</span><span class='info'>National Institute of Standards and Technology, “Secure Hash Standard (SHS). FIPS PUB 180-3, October 2008,” .</span><span>)</span></a> to apply the access token secret to the request and + generate a signature value that is included in the request instead of transmitting + the secret in the clear. + +</p> +<p> + To use the <tt>hmac-sha256</tt> algorithm, clients: + + </p> +<ol class="text"> +<li> + Calculate the request timestamp and generate a request nonce as described in + <a class='info' href='#nonce_ts'>Section 5.3.1.1<span> (</span><span class='info'>Nonce and Timestamp</span><span>)</span></a>. + +</li> +<li> + Construct the normalized request string as described in + <a class='info' href='#base_string'>Section 5.3.1.2<span> (</span><span class='info'>Normalized String Construction</span><span>)</span></a>. + +</li> +<li> + Calculate the request signature as described in + <a class='info' href='#hmac_sha256_function'>Section 5.3.1.3<span> (</span><span class='info'>Signature Calculation</span><span>)</span></a>. + +</li> +<li> + Include the timestamp, nonce, algorithm name, and calculated signature in the + request using the <tt>Authorization</tt> header field. + +</li> +</ol><p> + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + GET /resource HTTP/1.1 + Host: server.example.com + Authorization: Token token="vF9dft4qmT", + nonce="s8djwd", + timestamp="137131200", + algorithm="hmac-sha256", + signature="wOJIO9A2W5mFwDgiDvZbTSMK/PY=" + +</pre></div> +<p> + The resource server MUST validate the access token and ensure it has not expired and + that its scope covers the requested resource. The resource server MUST also recalculate + the request signature using the attributes provided by the client and compare it to the + signature provided. If the token expired or is invalid, or if the signature is + incorrect, the resource server MUST reply with an HTTP 401 status code (Unauthorized) + and include the HTTP <tt>WWW-Authenticate</tt> response header as + described in <a class='info' href='#authn_header'>Section 6.1<span> (</span><span class='info'>The WWW-Authenticate Response Header</span><span>)</span></a>. + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + HTTP/1.1 401 Unauthorized + Date: Tue, 15 Nov 2010 08:12:31 GMT + WWW-Authenticate: Token realm='Service', + algorithms='hmac-sha256', + error='invalid_signature' + +</pre></div> +<p> + [[ Errors list ]] + +</p> +<a name="nonce_ts"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.3.1.1"></a><h3>5.3.1.1. +Nonce and Timestamp</h3> + +<p> + A timestamp in combination with unique nonce values is used to protect against + replay attacks when transmitted over an insecure channel. + +</p> +<p> + The nonce is a random string, uniquely generated by the client to allow the resource + server to verify that a request has never been made before and helps prevent replay + attacks when requests are made over a non-secure channel. The nonce value MUST be + unique across all requests with the same timestamp and token combinations. + +</p> +<p> + The timestamp value is the current time expressed in the number of seconds since + January 1, 1970 00:00:00 GMT, and MUST be a positive integer. + +</p> +<p> + To avoid the need to retain an infinite number of nonce values for future checks, + resource servers MAY choose to restrict the time period after which a request with an + old timestamp is rejected. When resource servers apply such a restriction, clients + SHOULD synchronize their clocks by using the resource server's time as indicated by + the HTTP <tt>Date</tt> response header field as defined in + <a class='info' href='#RFC2616'>[RFC2616]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.</span><span>)</span></a>. + +</p> +<a name="base_string"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.3.1.2"></a><h3>5.3.1.2. +Normalized String Construction</h3> + +<p> + The normalized request string is a consistent, reproducible concatenation of + several of the HTTP request elements into a single string. The string is used as an + input to the selected cryptographic method and includes the HTTP request method + (e.g. <tt>GET</tt>, <tt>POST</tt>, etc.), the + authority as declared by the HTTP <tt>Host</tt> request header, + and the request resource URI. + +</p> +<p> + The normalized request string does not cover the entire HTTP request. Most notably, + it does not include the entity-body or most HTTP entity-headers. It is important to + note that the resource server cannot verify the authenticity of the excluded request + elements without using additional protections such as SSL/TLS. + +</p> +<p> + The normalized request string is constructed by concatenating together, in order, + the following HTTP request elements, separated by the <tt>,</tt> + character (ASCII code 44): + + </p> +<ol class="text"> +<li> + The request timestamp as described in <a class='info' href='#nonce_ts'>Section 5.3.1.1<span> (</span><span class='info'>Nonce and Timestamp</span><span>)</span></a>. + +</li> +<li> + The request nonce as described in <a class='info' href='#nonce_ts'>Section 5.3.1.1<span> (</span><span class='info'>Nonce and Timestamp</span><span>)</span></a>. + +</li> +<li> + The cryptographic algorithm used. + +</li> +<li> + The HTTP request method in uppercase. For example: + <tt>HEAD</tt>, <tt>GET</tt>, + <tt>POST</tt>, etc. + +</li> +<li> + The hostname, colon-separated (ASCII code 58) from the TCP port used to make + the request as included in the HTTP request <tt>Host</tt> + header field. The port MUST be included even if it is not included in the + <tt>Host</tt> header field (i.e. the default port for the + scheme). + +</li> +<li> + The request resource URI. + +</li> +</ol><p> + +</p> +<p> + For example, the normalized request string for the + <tt>GET</tt> request URI + <tt>http://example.com/resource</tt>, request timestamp + <tt>137131200</tt>, request nonce + <tt>s8djwd</tt>, and <tt>hmac-sha256</tt> + algorithm (line breaks are for display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + 137131200,s8djwd,hmac-sha256,GET,example.com:80, + http://example.com/resource + +</pre></div> +<a name="hmac_sha256_function"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.3.1.3"></a><h3>5.3.1.3. +Signature Calculation</h3> + +<p> + Clients calculate the request signature using the HMAC-SHA256 function: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + digest = HMAC-SHA256 (key, text) + +</pre></div> +<p> + by setting the function variables are follows: + + </p> +<blockquote class="text"><dl> +<dt>text</dt> +<dd> + + is set to the value of the normalize request string as described in + <a class='info' href='#base_string'>Section 5.3.1.2<span> (</span><span class='info'>Normalized String Construction</span><span>)</span></a>. + +</dd> +<dt>key</dt> +<dd> + + is set to the access token secret. + +</dd> +</dl></blockquote><p> + +</p> +<p> + The request signature is the calculated value of the + <tt>digest</tt> variable after the result octet string is + base64-encoded per <a class='info' href='#RFC2045'>[RFC2045]<span> (</span><span class='info'>Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” November 1996.</span><span>)</span></a> section 6.8. + +</p> +<a name="anchor29"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.6"></a><h3>6. +Identifying a Protected Resource</h3> + +<p> + Clients access protected resources after locating the appropriate authorization and token endpoints + and obtaining an access token. In many cases, interacting with a protected resource requires + prior knowledge of the protected resource properties and methods, as well as its + authentication requirements (i.e. establishing client identity, locating the authorization + and token endpoints). + +</p> +<p> + However, there are cases in which clients are unfamiliar with the protected resource, + including whether the resource requires authentication. When clients attempt to access an + unfamiliar protected resource without an access token, the resource server denies the + request and informs the client of the required credentials using an HTTP authentication + challenge. + +</p> +<p> + In addition, when receiving an invalid authenticated request, the resource server issues an + authentication challenge including the error type and message. + +</p> +<a name="authn_header"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.6.1"></a><h3>6.1. +The WWW-Authenticate Response Header</h3> + +<p> + A resource server receiving a request for a protected resource without a valid access + token MUST respond with a 401 HTTP status code (Unauthorized), and includes at least one + <tt>Token</tt> <tt>WWW-Authenticate</tt> response + header field challenge. + +</p> +<p> + The <tt>WWW-Authenticate</tt> header field uses the framework defined by + <a class='info' href='#RFC2617'>[RFC2617]<span> (</span><span class='info'>Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</span><span>)</span></a> as follows: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> + challenge = "Token" RWS token-challenge + + token-challenge = realm + [ CS authz-uri ] + [ CS token-uri ] + [ CS algorithms ] + [ CS error ] + + authz-uri = "auth-uri" "=" URI-Reference + token-uri = "token-uri" "=" URI-Reference + algorithms = "algorithms" "=" <"> 1#algorithm-name <"> + error = "error" "=" <"> token <"> + + CS = OWS "," OWS + +</pre></div> +<a name="anchor30"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.6.1.1"></a><h3>6.1.1. +The 'realm' Attribute</h3> + +<p> + The <tt>realm</tt> attribute is used to provide the protected + resources partition as defined by <a class='info' href='#RFC2617'>[RFC2617]<span> (</span><span class='info'>Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</span><span>)</span></a>. + +</p> +<a name="authz_uri_attribute"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.6.1.2"></a><h3>6.1.2. +The 'authorization-uri' Attribute</h3> + +<p> + +</p> +<a name="anchor31"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.6.1.3"></a><h3>6.1.3. +The 'algorithms' Attribute</h3> + +<p> + +</p> +<a name="anchor32"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.6.1.4"></a><h3>6.1.4. +The 'error' Attribute</h3> + +<p> + +</p> +<a name="anchor33"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.7"></a><h3>7. +Security Considerations</h3> + +<p> + [[ Todo ]] + +</p> +<a name="anchor34"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.8"></a><h3>8. +IANA Considerations</h3> + +<p> + [[ Not Yet ]] + +</p> +<a name="anchor35"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.9"></a><h3>9. +Acknowledgements</h3> + +<p> + [[ Add OAuth 1.0a authors + WG contributors ]] + +</p> +<a name="anchor36"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.A"></a><h3>Appendix A. +Differences from OAuth 1.0a</h3> + +<p> + [[ Todo ]] + +</p> +<a name="anchor37"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.B"></a><h3>Appendix B. +Document History</h3> + +<p> + [[ to be removed by RFC editor before publication as an RFC ]] + +</p> +<p> + -00 + + </p> +<ul class="text"> +<li> + Initial draft based on a combination of WRAP and OAuth 1.0a. + +</li> +</ul><p> + +</p> +<a name="rfc.references"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.10"></a><h3>10. +References</h3> + +<a name="rfc.references1"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>10.1. Normative References</h3> +<table width="99%" border="0"> +<tr><td class="author-text" valign="top"><a name="I-D.ietf-httpbis-p1-messaging">[I-D.ietf-httpbis-p1-messaging]</a></td> +<td class="author-text">Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, “<a href="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p1-messaging-09.txt">HTTP/1.1, part 1: URIs, Connections, and Message Parsing</a>,” draft-ietf-httpbis-p1-messaging-09 (work in progress), March 2010 (<a href="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p1-messaging-09.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="NIST FIPS-180-3">[NIST FIPS-180-3]</a></td> +<td class="author-text">National Institute of Standards and Technology, “<a href="http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf">Secure Hash Standard (SHS). FIPS PUB 180-3, October 2008</a>.”</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2045">[RFC2045]</a></td> +<td class="author-text"><a href="mailto:ned@innosoft.com">Freed, N.</a> and <a href="mailto:nsb@nsb.fv.com">N. Borenstein</a>, “<a href="http://tools.ietf.org/html/rfc2045">Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</a>,” RFC 2045, November 1996 (<a href="http://www.rfc-editor.org/rfc/rfc2045.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2104">[RFC2104]</a></td> +<td class="author-text"><a href="mailto:hugo@watson.ibm.com">Krawczyk, H.</a>, <a href="mailto:mihir@cs.ucsd.edu">Bellare, M.</a>, and <a href="mailto:canetti@watson.ibm.com">R. Canetti</a>, “<a href="http://tools.ietf.org/html/rfc2104">HMAC: Keyed-Hashing for Message Authentication</a>,” RFC 2104, February 1997 (<a href="http://www.rfc-editor.org/rfc/rfc2104.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td> +<td class="author-text"><a href="mailto:sob@harvard.edu">Bradner, S.</a>, “<a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>,” BCP 14, RFC 2119, March 1997 (<a href="http://www.rfc-editor.org/rfc/rfc2119.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2119.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2119.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2616">[RFC2616]</a></td> +<td class="author-text"><a href="mailto:fielding@ics.uci.edu">Fielding, R.</a>, <a href="mailto:jg@w3.org">Gettys, J.</a>, <a href="mailto:mogul@wrl.dec.com">Mogul, J.</a>, <a href="mailto:frystyk@w3.org">Frystyk, H.</a>, <a href="mailto:masinter@parc.xerox.com">Masinter, L.</a>, <a href="mailto:paulle@microsoft.com">Leach, P.</a>, and <a href="mailto:timbl@w3.org">T. Berners-Lee</a>, “<a href="http://tools.ietf.org/html/rfc2616">Hypertext Transfer Protocol -- HTTP/1.1</a>,” RFC 2616, June 1999 (<a href="http://www.rfc-editor.org/rfc/rfc2616.txt">TXT</a>, <a href="http://www.rfc-editor.org/rfc/rfc2616.ps">PS</a>, <a href="http://www.rfc-editor.org/rfc/rfc2616.pdf">PDF</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2616.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2616.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2617">[RFC2617]</a></td> +<td class="author-text"><a href="mailto:john@math.nwu.edu">Franks, J.</a>, <a href="mailto:pbaker@verisign.com">Hallam-Baker, P.</a>, <a href="mailto:jeff@AbiSource.com">Hostetler, J.</a>, <a href="mailto:lawrence@agranat.com">Lawrence, S.</a>, <a href="mailto:paulle@microsoft.com">Leach, P.</a>, Luotonen, A., and <a href="mailto:stewart@OpenMarket.com">L. Stewart</a>, “<a href="http://tools.ietf.org/html/rfc2617">HTTP Authentication: Basic and Digest Access Authentication</a>,” RFC 2617, June 1999 (<a href="http://www.rfc-editor.org/rfc/rfc2617.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2617.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2617.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2818">[RFC2818]</a></td> +<td class="author-text">Rescorla, E., “<a href="http://tools.ietf.org/html/rfc2818">HTTP Over TLS</a>,” RFC 2818, May 2000 (<a href="http://www.rfc-editor.org/rfc/rfc2818.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC3447">[RFC3447]</a></td> +<td class="author-text">Jonsson, J. and B. Kaliski, “<a href="http://tools.ietf.org/html/rfc3447">Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1</a>,” RFC 3447, February 2003 (<a href="http://www.rfc-editor.org/rfc/rfc3447.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC3629">[RFC3629]</a></td> +<td class="author-text">Yergeau, F., “<a href="http://tools.ietf.org/html/rfc3629">UTF-8, a transformation format of ISO 10646</a>,” STD 63, RFC 3629, November 2003 (<a href="http://www.rfc-editor.org/rfc/rfc3629.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC3986">[RFC3986]</a></td> +<td class="author-text"><a href="mailto:timbl@w3.org">Berners-Lee, T.</a>, <a href="mailto:fielding@gbiv.com">Fielding, R.</a>, and <a href="mailto:LMM@acm.org">L. Masinter</a>, “<a href="http://tools.ietf.org/html/rfc3986">Uniform Resource Identifier (URI): Generic Syntax</a>,” STD 66, RFC 3986, January 2005 (<a href="http://www.rfc-editor.org/rfc/rfc3986.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc3986.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc3986.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="W3C.REC-html40-19980424">[W3C.REC-html40-19980424]</a></td> +<td class="author-text">Hors, A., Jacobs, I., and D. Raggett, “<a href="http://www.w3.org/TR/1998/REC-html40-19980424">HTML 4.0 Specification</a>,” World Wide Web Consortium Recommendation REC-html40-19980424, April 1998 (<a href="http://www.w3.org/TR/1998/REC-html40-19980424">HTML</a>).</td></tr> +</table> + +<a name="rfc.references2"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>10.2. Informative References</h3> +<table width="99%" border="0"> +<tr><td class="author-text" valign="top"><a name="I-D.hammer-oauth">[I-D.hammer-oauth]</a></td> +<td class="author-text">Hammer-Lahav, E., “<a href="http://www.ietf.org/internet-drafts/draft-hammer-oauth-10.txt">The OAuth 1.0 Protocol</a>,” draft-hammer-oauth-10 (work in progress), February 2010 (<a href="http://www.ietf.org/internet-drafts/draft-hammer-oauth-10.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="I-D.hardt-oauth">[I-D.hardt-oauth]</a></td> +<td class="author-text">Hardt, D., Tom, A., Eaton, B., and Y. Goland, “<a href="http://www.ietf.org/internet-drafts/draft-hardt-oauth-01.txt">OAuth Web Resource Authorization Profiles</a>,” draft-hardt-oauth-01 (work in progress), January 2010 (<a href="http://www.ietf.org/internet-drafts/draft-hardt-oauth-01.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="OASIS.saml-core-2.0-os">[OASIS.saml-core-2.0-os]</a></td> +<td class="author-text"><a href="mailto:cantor.2@osu.edu">Cantor, S.</a>, <a href="mailto:John.Kemp@nokia.com">Kemp, J.</a>, <a href="mailto:rphilpott@rsasecurity.com">Philpott, R.</a>, and <a href="mailto:eve.maler@sun.com">E. Maler</a>, “<a href="http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf">Assertions and Protocol for the OASIS Security Assertion Markup Language + (SAML) V2.0</a>,” OASIS Standard saml-core-2.0-os, March 2005.</td></tr> +</table> + +<a name="rfc.authors"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>Authors' Addresses</h3> +<table width="99%" border="0" cellpadding="0" cellspacing="0"> +<tr><td class="author-text"> </td> +<td class="author-text">Eran Hammer-Lahav (editor)</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Yahoo!</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:eran@hueniverse.com">eran@hueniverse.com</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">David Recordon</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Facebook</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:davidrecordon@facebook.com">davidrecordon@facebook.com</a></td></tr> +<tr><td class="author" align="right">URI: </td> +<td class="author-text"><a href="http://www.davidrecordon.com/">http://www.davidrecordon.com/</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Dick Hardt</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:dick.hardt@gmail.com">dick.hardt@gmail.com</a></td></tr> +<tr><td class="author" align="right">URI: </td> +<td class="author-text"><a href="http://dickhardt.org/">http://dickhardt.org/</a></td></tr> +</table> +</body></html> + diff --git a/src/DotNetOpenAuth.sln b/src/DotNetOpenAuth.sln index 135d51f..dcff8d0 100644 --- a/src/DotNetOpenAuth.sln +++ b/src/DotNetOpenAuth.sln @@ -13,7 +13,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Specs", "Specs", "{CD57219F-24F4-4136-8741-6063D0D7A031}" ProjectSection(SolutionItems) = preProject - ..\doc\specs\draft-hardt-oauth-01.htm = ..\doc\specs\draft-hardt-oauth-01.htm + ..\doc\specs\draft-ietf-oauth.html = ..\doc\specs\draft-ietf-oauth.html ..\doc\specs\ICAM_OpenID20Profile.pdf = ..\doc\specs\ICAM_OpenID20Profile.pdf ..\doc\specs\OAuth Core 1.0.htm = ..\doc\specs\OAuth Core 1.0.htm ..\doc\specs\OAuth Core 1.0a (Draft 3).htm = ..\doc\specs\OAuth Core 1.0a (Draft 3).htm @@ -341,7 +341,6 @@ Global {BBACD972-014D-478F-9B07-56B9E1D4CC73} = {034D5B5B-7D00-4A9D-8AFE-4A476E0575B1} {B64A1E7E-6A15-4B91-AF13-7D48F7DA5942} = {034D5B5B-7D00-4A9D-8AFE-4A476E0575B1} {0B4EB2A8-283D-48FB-BCD0-85B8DFFE05E4} = {034D5B5B-7D00-4A9D-8AFE-4A476E0575B1} - {6EB90284-BD15-461C-BBF2-131CF55F7C8B} = {8A5CEDB9-7F8A-4BE2-A1B9-97130F453277} {F289B925-4307-4BEC-B411-885CE70E3379} = {034D5B5B-7D00-4A9D-8AFE-4A476E0575B1} {6EC36418-DBC5-4AD1-A402-413604AA7A08} = {1E2CBAA5-60A3-4AED-912E-541F5753CDC6} {9ADBE36D-9960-48F6-82E9-B4AC559E9AC3} = {1E2CBAA5-60A3-4AED-912E-541F5753CDC6} |