Skip to content

Commit 4da5fe9

Browse files
aaronpkaaronpk
authored
Merge pull request #1 from selfissued/mbj-www-authenticate
Added WWW-Authenticate functionality from draft-parecki-oauth-authorization-server-discovery-00
2 parents f63db1b + 0895086 commit 4da5fe9

File tree

1 file changed

+164
-10
lines changed

1 file changed

+164
-10
lines changed

Diff for: ‎draft-jones-oauth-resource-metadata.xml

+164-10
Original file line numberDiff line numberDiff line change
@@ -117,10 +117,13 @@
117117
</t>
118118

119119
<section anchor="rnc" title="Requirements Notation and Conventions">
120-
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
121-
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
122-
document are to be interpreted as described in <xref
123-
target="RFC2119">RFC 2119</xref>.</t>
120+
<t>
121+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
122+
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL"
123+
in this document are to be interpreted as described in
124+
BCP 14 <xref target="RFC2119"></xref> <xref target="RFC8174"></xref>
125+
when, and only when, they appear in all capitals, as shown here.
126+
</t>
124127

125128
<t>
126129
All uses of <xref target="JWS">JSON Web Signature (JWS)</xref>
@@ -142,6 +145,17 @@
142145
the terms "Claim Name", "Claim Value", and "JSON Web Token (JWT)"
143146
defined by <xref target="JWT">JSON Web Token (JWT)</xref>.
144147
</t>
148+
<t>
149+
This specification defines the following term:
150+
<list style='hanging'>
151+
<t hangText='Resource Identifier:'>
152+
<vspace/>
153+
A URL that uses the <spanx style="verb">https</spanx> scheme and has no fragment components
154+
where <spanx style="verb">.well-known</spanx> <xref target="RFC5785"/> resources
155+
containing information about the protected resource are published.
156+
</t>
157+
</list>
158+
</t>
145159
</section>
146160
</section>
147161

@@ -161,7 +175,7 @@
161175
The protected resource's resource identifier, which is a URL that
162176
uses the <spanx style="verb">https</spanx> scheme and has no fragment components.
163177
This is the location where
164-
<spanx style="verb">.well-known</spanx> <xref target="RFC5785">RFC 5785</xref> resources
178+
<spanx style="verb">.well-known</spanx> <xref target="RFC5785"/> resources
165179
containing information about the protected resource are published.
166180
Using these well-known resources is described in <xref target="PRConfig"/>.
167181
</t>
@@ -315,7 +329,7 @@
315329
<spanx style="verb">/.well-known/oauth-protected-resource</spanx> to the
316330
protected resource's resource identifier.
317331
The syntax and semantics of <spanx style="verb">.well-known</spanx>
318-
are defined in <xref target="RFC5785">RFC 5785</xref>.
332+
are defined in <xref target="RFC5785"/>.
319333
The well-known URI path suffix used MUST be registered in the IANA
320334
"Well-Known URIs" registry <xref target="IANA.well-known"/>.
321335
</t>
@@ -388,7 +402,7 @@
388402
This is required in some multi-tenant hosting configurations.
389403
This use of <spanx style="verb">.well-known</spanx> is for supporting
390404
multiple resources per host; unlike its use in
391-
<xref target="RFC5785">RFC 5785</xref>, it does not provide
405+
<xref target="RFC5785"/>, it does not provide
392406
general information about the host.
393407
</t>
394408

@@ -489,6 +503,126 @@
489503
</t>
490504
</section>
491505

506+
<section anchor="WWW-Authenticate" title="Use of WWW-Authenticate for Protected Resource Metadata">
507+
<t>
508+
A protected resource MAY use a <spanx style="verb">WWW-Authenticate</spanx> response to return its resource identifier to the client.
509+
The client can then retrieve protected resource metadata using the resource identifier as described in <xref target="PRConfig"/>.
510+
The client might then, for instance, determine what authorization server to use for the resource
511+
based on protected resource metadata retrieved.
512+
</t>
513+
<t>
514+
A typical end-to-end flow doing so is as follows.
515+
Note that while this example uses the OAuth 2.0 Authorization Code flow,
516+
a similar sequence could also be implemented with any other OAuth flow.
517+
</t>
518+
<t>
519+
<list style="numbers">
520+
<t>
521+
The client makes a request to a protected resource without presenting an access token.
522+
</t>
523+
<t>
524+
The resource server responds with a <spanx style="verb">WWW-Authenticate</spanx> header including the resource identifier of the protected resource.
525+
</t>
526+
<t>
527+
The client fetches resource metadata from the <spanx style="verb">.well-known/oauth-protected-resource</spanx> location
528+
derived from the resource identifier according to <xref target="PRConfig"/>.
529+
</t>
530+
<t>
531+
The protected resource responds with the protected resource metadata according to <xref target="PRConfigurationResponse"/>.
532+
</t>
533+
<t>
534+
The client builds the authorization server metadata URL from an issuer identifier in the resource metadata according to <xref target="RFC8414"/>
535+
and makes a request to fetch the authorization server metadata.
536+
</t>
537+
<t>
538+
The authorization server responds with the authorization server metadata document according to <xref target="RFC8414"/>.
539+
</t>
540+
<t>
541+
The client directs the user agent to the authorization server to begin the authorization flow.
542+
</t>
543+
<t>
544+
The authorization exchange is completed and the authorization server returns an access token to the client.
545+
</t>
546+
<t>
547+
The client repeats the resource request from step 1, presenting the newly obtained access token.
548+
</t>
549+
<t>
550+
The resource server returns the requested protected resource.
551+
</t>
552+
</list>
553+
</t>
554+
555+
<section anchor="WWW-Authenticate-Response" title="WWW-Authenticate Response">
556+
<t>
557+
This specification introduces a new parameter in the <spanx style="verb">WWW-Authenticate</spanx> response
558+
to indicate the resource identifier of the protected resource:
559+
<list style='hanging'>
560+
<t hangText='resource:'>
561+
<vspace/>
562+
The resource identifier of the protected resource.
563+
</t>
564+
</list>
565+
</t>
566+
<t>
567+
<figure>
568+
<preamble>The response below is an example of a <spanx style="verb">WWW-Authenticate</spanx> header that includes the resource identifier.</preamble>
569+
570+
<artwork><![CDATA[
571+
HTTP/1.1 400 Bad Request
572+
WWW-Authenticate: Bearer error="invalid_request",
573+
error_description="No access token was provided in this request",
574+
resource="https://resource.example.com"
575+
]]></artwork>
576+
</figure>
577+
</t>
578+
<t>
579+
The HTTP status code and error string in the response are defined by <xref target="RFC6750"/>.
580+
</t>
581+
<t>
582+
The issuer parameter MAY be combined with other parameters defined in other extensions,
583+
such as the <spanx style="verb">max_age</spanx> parameter defined by <xref target="I-D.ietf-oauth-step-up-authn-challenge"/>.
584+
</t>
585+
</section>
586+
587+
<section anchor="changes" title="Changes to Resource Metadata">
588+
<t>
589+
At any point, for any reason determined by the protected resource,
590+
the protected resource MAY respond with a new <spanx style="verb">WWW-Authenticate</spanx> challenge
591+
that includes a value for the resource identifier to indicate that its metadata MAY have changed.
592+
If the client receives such a <spanx style="verb">WWW-Authenticate</spanx> response,
593+
it is expected retrieve the protected resource metadata again,
594+
and SHOULD use the new metadata values obtained.
595+
Among other things,
596+
this enables a resource server to change which authorization servers it uses without any other coordination with clients.
597+
</t>
598+
</section>
599+
600+
<section anchor="assumptions" title="Client Identifier and Client Authentication">
601+
<t>
602+
The way in which the client identifier is established at the authorization server is out of scope of this specification.
603+
</t>
604+
<t>
605+
This specification is intended to be deployed in scenarios where the client has no prior knowledge about the resource server,
606+
and the resource server might or might not have prior knowledge about the client.
607+
</t>
608+
<t>
609+
There are some existing methods by which an unrecognized client can make use of an authorization server,
610+
such as using Dynamic Client Registration <xref target="RFC7591"/>,
611+
to register the client prior to initiating the authorization flow.
612+
Future extensions might define alternatives, such as using URLs to identify clients.
613+
</t>
614+
</section>
615+
616+
<section anchor="compatibility" title="Compatibility with other authentication methods">
617+
<t>
618+
Resource servers MAY return other <spanx style="verb">WWW-Authenticate</spanx> headers indicating various authentication schemes.
619+
This allows the resource server to support clients that may or may not implement this specification,
620+
and allows clients to choose their preferred authentication scheme.
621+
</t>
622+
</section>
623+
624+
</section>
625+
492626
<section anchor="StringOps" title="String Operations">
493627

494628
<t>
@@ -536,7 +670,7 @@
536670
TLS version 1.2 <xref target='RFC5246' />
537671
and MAY support additional transport-layer security mechanisms meeting its security requirements.
538672
When using TLS, the client MUST perform a TLS/SSL server certificate check,
539-
per <xref target="RFC6125">RFC 6125</xref>.
673+
per <xref target="RFC6125"/>.
540674
Implementation security considerations can be found in
541675
<xref target="BCP195">Recommendations for Secure Use of TLS and DTLS</xref>.
542676
</t>
@@ -979,7 +1113,7 @@
9791113
This specification registers the well-known URI defined in
9801114
<xref target="PRConfig"/> in the IANA
9811115
"Well-Known URIs" registry <xref target="IANA.well-known"/>
982-
established by <xref target="RFC5785">RFC 5785</xref>.
1116+
established by <xref target="RFC5785"/>.
9831117
</t>
9841118

9851119
<section anchor='WellKnownContents' title='Registry Contents'>
@@ -1019,6 +1153,7 @@
10191153
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7033.xml"/>
10201154
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7159.xml"/>
10211155
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7591.xml"/>
1156+
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>
10221157

10231158
<reference anchor='BCP195' target='http://www.rfc-editor.org/info/bcp195'>
10241159
<front>
@@ -1199,6 +1334,9 @@
11991334

12001335
<references title="Informative References">
12011336

1337+
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8414.xml"/>
1338+
<xi:include href="https://bib.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-step-up-authn-challenge-17.xml"/>
1339+
12021340
<reference anchor="OpenID.Discovery" target="http://openid.net/specs/openid-connect-discovery-1_0.html">
12031341
<front>
12041342
<title>OpenID Connect Discovery 1.0</title>
@@ -1249,13 +1387,29 @@
12491387
<section anchor="Acknowledgements" title="Acknowledgements">
12501388

12511389
<t>
1252-
Thanks to George Fletcher and Tony Nadalin for their input on the specification.
1390+
The authors of this specification would like to thank the attendees of the IETF 115 OAuth and HTTP API Working Groups
1391+
and the attendees of the IETF 116 OAuth Working Group for their input on this specification.
1392+
We would would also like to thank
1393+
George Fletcher
1394+
and
1395+
Tony Nadalin
1396+
for their contributions to the specification.
12531397
</t>
12541398
</section>
12551399

12561400
<section anchor="History" title="Document History">
12571401
<t>[[ to be removed by the RFC Editor before publication as an RFC ]]</t>
12581402

1403+
<t>
1404+
-04
1405+
<list style="symbols">
1406+
<t>
1407+
Merged <spanx style="verb">WWW-Authenticate</spanx> functionality from draft-parecki-oauth-authorization-server-discovery-00
1408+
into this specification, as requsted by attendees of the IETF 116 OAuth Working Group.
1409+
</t>
1410+
</list>
1411+
</t>
1412+
12591413
<t>
12601414
-03
12611415
<list style="symbols">

0 commit comments

Comments
 (0)