< draft-ietf-oauth-v2-1-01.txt   draft-ietf-oauth-v2-1-02.txt >
OAuth Working Group D. Hardt OAuth Working Group D. Hardt
Internet-Draft SignIn.Org Internet-Draft SignIn.Org
Intended status: Standards Track A. Parecki Intended status: Standards Track A. Parecki
Expires: 5 August 2021 Okta Expires: 16 September 2021 Okta
T. Lodderstedt T. Lodderstedt
yes.com yes.com
1 February 2021 15 March 2021
The OAuth 2.1 Authorization Framework The OAuth 2.1 Authorization Framework
draft-ietf-oauth-v2-1-01 draft-ietf-oauth-v2-1-02
Abstract Abstract
The OAuth 2.1 authorization framework enables a third-party The OAuth 2.1 authorization framework enables a third-party
application to obtain limited access to an HTTP service, either on application to obtain limited access to an HTTP service, either on
behalf of a resource owner by orchestrating an approval interaction behalf of a resource owner by orchestrating an approval interaction
between the resource owner and an authorization service, or by between the resource owner and an authorization service, or by
allowing the third-party application to obtain access on its own allowing the third-party application to obtain access on its own
behalf. This specification replaces and obsoletes the OAuth 2.0 behalf. This specification replaces and obsoletes the OAuth 2.0
Authorization Framework described in RFC 6749. Authorization Framework described in RFC 6749.
skipping to change at page 1, line 39 skipping to change at page 1, line 39
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 5 August 2021. This Internet-Draft will expire on 16 September 2021.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 2, line 28 skipping to change at page 2, line 28
1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 10 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 10
1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 12 1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 12
1.7. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 12 1.7. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 12
1.8. Interoperability . . . . . . . . . . . . . . . . . . . . 12 1.8. Interoperability . . . . . . . . . . . . . . . . . . . . 12
1.9. Compatibility with OAuth 2.0 . . . . . . . . . . . . . . 13 1.9. Compatibility with OAuth 2.0 . . . . . . . . . . . . . . 13
1.10. Notational Conventions . . . . . . . . . . . . . . . . . 13 1.10. Notational Conventions . . . . . . . . . . . . . . . . . 13
2. Client Registration . . . . . . . . . . . . . . . . . . . . . 14 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 14
2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 14 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 14
2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 16 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 16
2.3. Client Authentication . . . . . . . . . . . . . . . . . . 16 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 16
2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 17 2.3.1. Client Secret . . . . . . . . . . . . . . . . . . . . 17
2.3.2. Other Authentication Methods . . . . . . . . . . . . 18 2.3.2. Other Authentication Methods . . . . . . . . . . . . 18
2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 18 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 18
3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . 18 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . 18
3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 19 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 19
3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 19 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 19
3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . 20 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . 20
3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 22 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 22
3.2.1. Client Authentication . . . . . . . . . . . . . . . . 22 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 22
3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 23 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 23
4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 23 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 23
4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 23 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 23
4.1.1. Authorization Request . . . . . . . . . . . . . . . . 25 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 25
4.1.2. Authorization Response . . . . . . . . . . . . . . . 28 4.1.2. Authorization Response . . . . . . . . . . . . . . . 28
4.1.3. Access Token Request . . . . . . . . . . . . . . . . 31 4.1.3. Access Token Request . . . . . . . . . . . . . . . . 31
4.1.4. Access Token Response . . . . . . . . . . . . . . . . 32 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 32
4.2. Client Credentials Grant . . . . . . . . . . . . . . . . 33 4.2. Client Credentials Grant . . . . . . . . . . . . . . . . 32
4.2.1. Authorization Request and Response . . . . . . . . . 33 4.2.1. Authorization Request and Response . . . . . . . . . 33
4.2.2. Access Token Request . . . . . . . . . . . . . . . . 33 4.2.2. Access Token Request . . . . . . . . . . . . . . . . 33
4.2.3. Access Token Response . . . . . . . . . . . . . . . . 34 4.2.3. Access Token Response . . . . . . . . . . . . . . . . 34
4.3. Extension Grants . . . . . . . . . . . . . . . . . . . . 34 4.3. Extension Grants . . . . . . . . . . . . . . . . . . . . 34
5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 35 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 35
5.1. Successful Response . . . . . . . . . . . . . . . . . . . 35 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 35
5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 36 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 36
6. Refreshing an Access Token . . . . . . . . . . . . . . . . . 38 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . 38
6.1. Refresh Token Protection . . . . . . . . . . . . . . . . 39 6.1. Refresh Token Request . . . . . . . . . . . . . . . . . . 38
6.2. Refresh Token Response . . . . . . . . . . . . . . . . . 40
7. Accessing Protected Resources . . . . . . . . . . . . . . . . 41 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 41
7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 41 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 41
7.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 42 7.2. Bearer Tokens . . . . . . . . . . . . . . . . . . . . . . 42
7.2.1. Authenticated Requests . . . . . . . . . . . . . . . 42 7.2.1. Authenticated Requests . . . . . . . . . . . . . . . 42
7.2.2. The WWW-Authenticate Response Header Field . . . . . 44 7.2.2. The WWW-Authenticate Response Header Field . . . . . 44
7.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . . 45 7.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . . 45
7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 46 7.3. Error Response . . . . . . . . . . . . . . . . . . . . . 46
7.3.1. Extension Token Types . . . . . . . . . . . . . . . . 46 7.3.1. Extension Token Types . . . . . . . . . . . . . . . . 46
7.4. Access Token Security Considerations . . . . . . . . . . 46 7.4. Access Token Security Considerations . . . . . . . . . . 46
7.4.1. Security Threats . . . . . . . . . . . . . . . . . . 47 7.4.1. Security Threats . . . . . . . . . . . . . . . . . . 47
skipping to change at page 14, line 29 skipping to change at page 14, line 29
establishing trust and obtaining the required client properties establishing trust and obtaining the required client properties
(e.g., redirect URI, client type). For example, registration can be (e.g., redirect URI, client type). For example, registration can be
accomplished using a self-issued or third-party-issued assertion, or accomplished using a self-issued or third-party-issued assertion, or
by the authorization server performing client discovery using a by the authorization server performing client discovery using a
trusted channel. trusted channel.
When registering a client, the client developer SHALL: When registering a client, the client developer SHALL:
* specify the client type as described in Section 2.1, * specify the client type as described in Section 2.1,
* provide its client redirect URIs as described in Section 3.1.2, * provide client details needed by the grant type in use, such as
and redirect URIs as described in Section 3.1.2, and
* include any other information required by the authorization server * include any other information required by the authorization server
(e.g., application name, website, description, logo image, the (e.g., application name, website, description, logo image, the
acceptance of legal terms). acceptance of legal terms).
Dynamic Client Registration ([RFC7591]) defines a common general data Dynamic Client Registration ([RFC7591]) defines a common general data
model for clients that may be used even with manual client model for clients that may be used even with manual client
registration. registration.
2.1. Client Types 2.1. Client Types
Clients are identified at the authorization server by a "client_id". OAuth 2.1 defines three client types based on their ability to
It is, for example, used by the authorization server to determine the authenticate securely with the authorization server as well as the
set of redirect URIs this client can use. authorization server's assurance of the client's identity.
Clients requiring a higher level of confidence in their identity by
the authorization server use credentials to authenticate with the
authorization server. Such credentials are either issued by the
authorization server or registered by the developer of the client
with the authorization server.
OAuth 2.1 defines three client types:
"confidential": Clients that have credentials and their identity has "confidential": Clients that have credentials and their identity has
been confirmed by the AS are designated as "confidential clients" been confirmed by the AS are designated as "confidential clients"
"credentialed": Clients that have credentials and their identity has "credentialed": Clients that have credentials and their identity has
been not been confirmed by the AS are designated as "credentialed been not been confirmed by the AS are designated as "credentialed
clients" clients"
"public": Clients without credentials are called "public clients" "public": Clients without credentials are called "public clients"
skipping to change at page 16, line 34 skipping to change at page 16, line 24
The client identifier string size is left undefined by this The client identifier string size is left undefined by this
specification. The client should avoid making assumptions about the specification. The client should avoid making assumptions about the
identifier size. The authorization server SHOULD document the size identifier size. The authorization server SHOULD document the size
of any identifier it issues. of any identifier it issues.
Authorization servers SHOULD NOT allow clients to choose or influence Authorization servers SHOULD NOT allow clients to choose or influence
their "client_id" value. See Section 9.6 for details. their "client_id" value. See Section 9.6 for details.
2.3. Client Authentication 2.3. Client Authentication
If the client type is confidential, the client and authorization Confidential and credentialed clients establish a client
server establish a client authentication method suitable for the authentication method with the authorization server suitable for the
security requirements of the authorization server. The authorization security requirements of the authorization server. The authorization
server MAY accept any form of client authentication meeting its server MAY accept any form of client authentication meeting its
security requirements. security requirements.
Confidential clients are typically issued (or establish) a set of Confidential and credentialed clients are typically issued (or
client credentials used for authenticating with the authorization establish) a set of client credentials used for authenticating with
server (e.g., password, public/private key pair). the authorization server (e.g., password, public/private key pair).
Authorization servers SHOULD use client authentication if possible. Authorization servers SHOULD use client authentication if possible.
It is RECOMMENDED to use asymmetric (public-key based) methods for It is RECOMMENDED to use asymmetric (public-key based) methods for
client authentication such as mTLS [RFC8705] or "private_key_jwt" client authentication such as mTLS [RFC8705] or "private_key_jwt"
[OpenID]. When asymmetric methods for client authentication are [OpenID]. When asymmetric methods for client authentication are
used, authorization servers do not need to store sensitive symmetric used, authorization servers do not need to store sensitive symmetric
keys, making these methods more robust against a number of attacks. keys, making these methods more robust against a number of attacks.
The authorization server MAY establish a client authentication method The authorization server MAY establish a client authentication method
with public clients, which converts them to credentialed clients. with public clients, which converts them to credentialed clients.
However, the authorization server MUST NOT rely on credentialed However, the authorization server MUST NOT rely on credentialed
client authentication for the purpose of identifying the client. client authentication for the purpose of identifying the client.
The client MUST NOT use more than one authentication method in each The client MUST NOT use more than one authentication method in each
request. request.
2.3.1. Client Password 2.3.1. Client Secret
Clients in possession of a client password, also known as a client Clients in possession of a client secret, sometimes known as a client
secret, MAY use the HTTP Basic authentication scheme as defined in password, MAY use the HTTP Basic authentication scheme as defined in
[RFC2617] to authenticate with the authorization server. The client [RFC2617] to authenticate with the authorization server. The client
identifier is encoded using the "application/x-www-form-urlencoded" identifier is encoded using the "application/x-www-form-urlencoded"
encoding algorithm per Appendix B, and the encoded value is used as encoding algorithm per Appendix B, and the encoded value is used as
the username; the client secret is encoded using the same algorithm the username; the client secret is encoded using the same algorithm
and used as the password. The authorization server MUST support the and used as the password. The authorization server MUST support the
HTTP Basic authentication scheme for authenticating clients that were HTTP Basic authentication scheme for authenticating clients that were
issued a client secret. issued a client secret.
For example (with extra line breaks for display purposes only): For example (with extra line breaks for display purposes only):
skipping to change at page 18, line 27 skipping to change at page 18, line 17
brute force attacks. brute force attacks.
2.3.2. Other Authentication Methods 2.3.2. Other Authentication Methods
The authorization server MAY support any suitable authentication The authorization server MAY support any suitable authentication
scheme matching its security requirements. When using other scheme matching its security requirements. When using other
authentication methods, the authorization server MUST define a authentication methods, the authorization server MUST define a
mapping between the client identifier (registration record) and mapping between the client identifier (registration record) and
authentication scheme. authentication scheme.
Some additional authentication methods are defined in the "OAuth Some additional authentication methods such as mTLS [RFC8705] and
Token Endpoint Authentication Methods "private_key_jwt" [OpenID] are defined in the "OAuth Token Endpoint
(https://www.iana.org/assignments/oauth-parameters/oauth- Authentication Methods (https://www.iana.org/assignments/oauth-
parameters.xhtml#token-endpoint-auth-method)" registry, and may be parameters/oauth-parameters.xhtml#token-endpoint-auth-method)"
useful as generic client authentication methods beyond the specific registry, and may be useful as generic client authentication methods
use of protecting the token endpoint. beyond the specific use of protecting the token endpoint.
2.4. Unregistered Clients 2.4. Unregistered Clients
This specification does not exclude the use of unregistered clients. This specification does not exclude the use of unregistered clients.
However, the use of such clients is beyond the scope of this However, the use of such clients is beyond the scope of this
specification and requires additional security analysis and review of specification and requires additional security analysis and review of
its interoperability impact. its interoperability impact.
3. Protocol Endpoints 3. Protocol Endpoints
skipping to change at page 19, line 41 skipping to change at page 19, line 34
Since requests to the authorization endpoint result in user Since requests to the authorization endpoint result in user
authentication and the transmission of clear-text credentials (in the authentication and the transmission of clear-text credentials (in the
HTTP response), the authorization server MUST require the use of TLS HTTP response), the authorization server MUST require the use of TLS
as described in Section 1.6 when sending requests to the as described in Section 1.6 when sending requests to the
authorization endpoint. authorization endpoint.
The authorization server MUST support the use of the HTTP "GET" The authorization server MUST support the use of the HTTP "GET"
method [RFC7231] for the authorization endpoint and MAY support the method [RFC7231] for the authorization endpoint and MAY support the
use of the "POST" method as well. use of the "POST" method as well.
Parameters sent without a value MUST be treated as if they were The authorization server MUST ignore unrecognized request parameters.
omitted from the request. The authorization server MUST ignore
unrecognized request parameters. Request and response parameters Request and response parameters defined by this specification MUST
defined by this specification MUST NOT be included more than once. NOT be included more than once. Parameters sent without a value MUST
be treated as if they were omitted from the request.
3.1.1. Response Type 3.1.1. Response Type
The authorization endpoint is used by the authorization code flow. The authorization endpoint is used by the authorization code flow.
The client informs the authorization server of the desired response The client informs the authorization server of the desired response
type using the following parameter: type using the following parameter:
"response_type": REQUIRED. The value MUST be "code" for requesting "response_type": REQUIRED. The value MUST be "code" for requesting
an authorization code as described by Section 4.1.1, or a an authorization code as described by Section 4.1.1, or a
registered extension value as described by Section 8.4. registered extension value as described by Section 8.4.
Extension response types MAY contain a space-delimited (%x20) list of Extension response types MAY contain a space-delimited (%x20) list of
values, where the order of values does not matter (e.g., response values, where the order of values does not matter (e.g., response
type "a b" is the same as "b a"). The meaning of such composite type "a b" is the same as "b a"). The meaning of such composite
response types is defined by their respective specifications. response types is defined by their respective specifications.
Some extension response types are defined by ([OpenID]).
If an authorization request is missing the "response_type" parameter, If an authorization request is missing the "response_type" parameter,
or if the response type is not understood, the authorization server or if the response type is not understood, the authorization server
MUST return an error response as described in Section 4.1.2.1. MUST return an error response as described in Section 4.1.2.1.
3.1.2. Redirection Endpoint 3.1.2. Redirection Endpoint
After completing its interaction with the resource owner, the After completing its interaction with the resource owner, the
authorization server directs the resource owner's user-agent back to authorization server directs the resource owner's user-agent back to
the client. The authorization server redirects the user-agent to the the client. The authorization server redirects the user-agent to one
client's redirection endpoint previously established with the of the client's redirection endpoints previously established with the
authorization server during the client registration process. authorization server during the client registration process.
The authorization server MUST compare the two URIs using simple
string comparison as defined in [RFC3986], Section 6.2.1.
The redirect URI MUST be an absolute URI as defined by [RFC3986] The redirect URI MUST be an absolute URI as defined by [RFC3986]
Section 4.3. The endpoint URI MAY include an "application/x-www- Section 4.3. The endpoint URI MAY include an "application/x-www-
form-urlencoded" formatted (per Appendix B) query component form-urlencoded" formatted (per Appendix B) query component
([RFC3986] Section 3.4), which MUST be retained when adding ([RFC3986] Section 3.4), which MUST be retained when adding
additional query parameters. The endpoint URI MUST NOT include a additional query parameters. The endpoint URI MUST NOT include a
fragment component. fragment component.
3.1.2.1. Endpoint Request Confidentiality 3.1.2.1. Endpoint Request Confidentiality
The redirection endpoint SHOULD require the use of TLS as described The redirection endpoint SHOULD require the use of TLS as described
skipping to change at page 21, line 15 skipping to change at page 21, line 15
3.1.2.2. Registration Requirements 3.1.2.2. Registration Requirements
The authorization server MUST require all clients to register one or The authorization server MUST require all clients to register one or
more complete redirect URIs prior to utilizing the authorization more complete redirect URIs prior to utilizing the authorization
endpoint. The client MAY use the "state" request parameter to endpoint. The client MAY use the "state" request parameter to
achieve per-request customization if needed. achieve per-request customization if needed.
The authorization server MAY allow the client to register multiple The authorization server MAY allow the client to register multiple
redirect URIs. redirect URIs.
Lack of requiring registration of redirect URIs enables an attacker Without requiring registration of redirect URIs, attackers can use
to use the authorization endpoint as an open redirector as described the authorization endpoint as an open redirector as described in
in Section 9.18. Section 9.18.
3.1.2.3. Dynamic Configuration 3.1.2.3. Dynamic Configuration
If multiple redirect URIs have been registered the client MUST If multiple redirect URIs have been registered the client MUST
include a redirect URI with the authorization request using the include a redirect URI with the authorization request using the
"redirect_uri" request parameter. "redirect_uri" request parameter.
3.1.2.4. Invalid Endpoint 3.1.2.4. Invalid Endpoint
If an authorization request fails validation due to a missing, If an authorization request fails validation due to a missing,
skipping to change at page 21, line 39 skipping to change at page 21, line 39
inform the resource owner of the error and MUST NOT automatically inform the resource owner of the error and MUST NOT automatically
redirect the user-agent to the invalid redirect URI. redirect the user-agent to the invalid redirect URI.
3.1.2.5. Endpoint Content 3.1.2.5. Endpoint Content
The redirection request to the client's endpoint typically results in The redirection request to the client's endpoint typically results in
an HTML document response, processed by the user-agent. If the HTML an HTML document response, processed by the user-agent. If the HTML
response is served directly as the result of the redirection request, response is served directly as the result of the redirection request,
any script included in the HTML document will execute with full any script included in the HTML document will execute with full
access to the redirect URI and the credentials (e.g. authorization access to the redirect URI and the credentials (e.g. authorization
code) it contains. code) it contains. Additionally, the request URL containing the
authorization code may be sent in the HTTP Referer header to any
embedded images, stylesheets and other elements loaded in the page.
The client SHOULD NOT include any third-party scripts (e.g., third- The client SHOULD NOT include any third-party scripts (e.g., third-
party analytics, social plug-ins, ad networks) in the redirection party analytics, social plug-ins, ad networks) in the redirection
endpoint response. Instead, it SHOULD extract the credentials from endpoint response. Instead, it SHOULD extract the credentials from
the URI and redirect the user-agent again to another endpoint without the URI and redirect the user-agent again to another endpoint without
exposing the credentials (in the URI or elsewhere). If third-party exposing the credentials (in the URI or elsewhere). If third-party
scripts are included, the client MUST ensure that its own scripts scripts are included, the client MUST ensure that its own scripts
(used to extract and remove the credentials from the URI) will (used to extract and remove the credentials from the URI) will
execute first. execute first.
3.2. Token Endpoint 3.2. Token Endpoint
The token endpoint is used by the client to obtain an access token by The token endpoint is used by the client to obtain an access token
presenting its authorization grant or refresh token. using a grant such as those described in Section 4 and Section 6.
The means through which the client obtains the location of the token The means through which the client obtains the location of the token
endpoint are beyond the scope of this specification, but the location endpoint are beyond the scope of this specification, but the location
is typically provided in the service documentation, or in the is typically provided in the service documentation and configured
authorization server's metadata document ([RFC8414]). during development of the client, or provided in the authorization
server's metadata document ([RFC8414]) and fetched programmatically
at runtime.
The endpoint URI MAY include an "application/x-www-form-urlencoded" The endpoint URI MAY include an "application/x-www-form-urlencoded"
formatted (per Appendix B) query component ([RFC3986] Section 3.4), formatted (per Appendix B) query component ([RFC3986] Section 3.4)
which MUST be retained when adding additional query parameters. The and MUST NOT include a fragment component.
endpoint URI MUST NOT include a fragment component.
Since requests to the token endpoint result in the transmission of Since requests to the token endpoint result in the transmission of
clear-text credentials (in the HTTP request and response), the clear-text credentials (in the HTTP request and response), the
authorization server MUST require the use of TLS as described in authorization server MUST require the use of TLS as described in
Section 1.6 when sending requests to the token endpoint. Section 1.6 when sending requests to the token endpoint.
The client MUST use the HTTP "POST" method when making access token The client MUST use the HTTP "POST" method when making access token
requests. requests.
The authorization server MUST ignore unrecognized request parameters.
Parameters sent without a value MUST be treated as if they were Parameters sent without a value MUST be treated as if they were
omitted from the request. The authorization server MUST ignore omitted from the request. Request and response parameters defined by
unrecognized request parameters. Request and response parameters this specification MUST NOT be included more than once.
defined by this specification MUST NOT be included more than once.
3.2.1. Client Authentication 3.2.1. Client Authentication
Confidential clients or other clients issued client credentials MUST Confidential clients or other clients issued client credentials MUST
authenticate with the authorization server as described in authenticate with the authorization server as described in
Section 2.3 when making requests to the token endpoint. Client Section 2.3 when making requests to the token endpoint. Client
authentication is used for: authentication is used for:
* Enforcing the binding of refresh tokens and authorization codes to * Enforcing the binding of refresh tokens and authorization codes to
the client they were issued to. Client authentication is critical the client they were issued to. Client authentication is critical
skipping to change at page 23, line 42 skipping to change at page 23, line 42
If the client omits the scope parameter when requesting If the client omits the scope parameter when requesting
authorization, the authorization server MUST either process the authorization, the authorization server MUST either process the
request using a pre-defined default value or fail the request request using a pre-defined default value or fail the request
indicating an invalid scope. The authorization server SHOULD indicating an invalid scope. The authorization server SHOULD
document its scope requirements and default value (if defined). document its scope requirements and default value (if defined).
4. Obtaining Authorization 4. Obtaining Authorization
To request an access token, the client obtains authorization from the To request an access token, the client obtains authorization from the
resource owner. The authorization is expressed in the form of an resource owner. OAuth defines two authorization grant types:
authorization grant, which the client uses to request the access authorization code and client credentials. It also provides an
token. OAuth defines two authorization grant types: authorization extension mechanism for defining additional grant types.
code and client credentials. It also provides an extension mechanism
for defining additional grant types.
4.1. Authorization Code Grant 4.1. Authorization Code Grant
The authorization code grant type is used to obtain both access The authorization code grant type is used to obtain both access
tokens and refresh tokens. tokens and refresh tokens.
Since this is a redirect-based flow, the client must be capable of Since this is a redirect-based flow, the client must be capable of
interacting with the resource owner's user-agent (typically a web initiating the flow with the resource owner's user-agent (typically a
browser) and capable of receiving incoming requests (via redirection) web browser) and capable of being redirected back to from the
from the authorization server. authorization server.
+----------+ +----------+
| Resource | | Resource |
| Owner | | Owner |
| | | |
+----------+ +----------+
^ ^
| |
(2) (2)
+----|-----+ Client Identifier +---------------+ +----|-----+ Client Identifier +---------------+
skipping to change at page 25, line 28 skipping to change at page 25, line 28
(5) The authorization server authenticates the client when possible, (5) The authorization server authenticates the client when possible,
validates the authorization code, validates the code verifier, and validates the authorization code, validates the code verifier, and
ensures that the redirect URI received matches the URI used to ensures that the redirect URI received matches the URI used to
redirect the client in step (3). If valid, the authorization server redirect the client in step (3). If valid, the authorization server
responds back with an access token and, optionally, a refresh token. responds back with an access token and, optionally, a refresh token.
4.1.1. Authorization Request 4.1.1. Authorization Request
To begin the authorization request, the client builds the To begin the authorization request, the client builds the
authorization request URI by adding parameters to the authorization authorization request URI by adding parameters to the authorization
server's authorization endpoint URI. server's authorization endpoint URI. The client will eventually
redirect the user-agent to this URI to initiate the request, as
described in Section 4.1.1.1.
Clients use a unique secret per authorization request to protect Clients use a unique secret per authorization request to protect
against code injection and CSRF attacks. The client first generates against authorization code injection and CSRF attacks. The client
this secret, which it can later use along with the authorization code first generates this secret, which it can use at the time of
to prove that the application using the authorization code is the redeeming the authorization code to prove that the client using the
same application that requested it. The properties "code_challenge" authorization code is the same client that requested it.
and "code_verifier" are adopted from the OAuth 2.0 extension known as
"Proof-Key for Code Exchange", or PKCE ([RFC7636]) where this
technique was originally developed.
Clients MUST use "code_challenge" and "code_verifier" and 4.1.1.1. Client Initiates the Authorization Request
authorization servers MUST enforce their use except under the
conditions described in Section 9.8. In this case, using and
enforcing "code_challenge" and "code_verifier" as described in the
following is still RECOMMENDED.
4.1.1.1. Client Creates a Code Verifier The client constructs the request URI by adding the following
parameters to the query component of the authorization endpoint URI
using the "application/x-www-form-urlencoded" format, per Appendix B:
The client first creates a code verifier, "code_verifier", for each "response_type": REQUIRED. Value MUST be set to "code".
Authorization Request, in the following manner:
code_verifier = high-entropy cryptographic random STRING using the "client_id": REQUIRED. The client identifier as described in
unreserved characters `[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"` Section 2.2.
from Section 2.3 of {{RFC3986}}, with a minimum length of 43 characters
and a maximum length of 128 characters. "code_challenge": REQUIRED or RECOMMENDED (see Section 9.8). Code
challenge.
"code_challenge_method": OPTIONAL, defaults to "plain" if not
present in the request. Code verifier transformation method is
"S256" or "plain".
"redirect_uri": OPTIONAL. As described in Section 3.1.2.
"scope": OPTIONAL. The scope of the access request as described by
Section 3.3.
"state": 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.
The "code_verifier" is a unique high-entropy cryptographically random
string generated for each authorization request, using the unreserved
characters "[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"", with a
minimum length of 43 characters and a maximum length of 128
characters.
The client stores the "code_verifier" temporarily, and calculates the
"code_challenge" which it uses in the authorization request.
ABNF for "code_verifier" is as follows. ABNF for "code_verifier" is as follows.
code-verifier = 43*128unreserved code-verifier = 43*128unreserved
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
ALPHA = %x41-5A / %x61-7A ALPHA = %x41-5A / %x61-7A
DIGIT = %x30-39 DIGIT = %x30-39
NOTE: The code verifier SHOULD have enough entropy to make it NOTE: The code verifier SHOULD have enough entropy to make it
impractical to guess the value. It is RECOMMENDED that the output of impractical to guess the value. It is RECOMMENDED that the output of
a suitable random number generator be used to create a 32-octet a suitable random number generator be used to create a 32-octet
sequence. The octet sequence is then base64url-encoded to produce a sequence. The octet sequence is then base64url-encoded to produce a
43-octet URL-safe string to use as the code verifier. 43-octet URL-safe string to use as the code verifier.
4.1.1.2. Client Creates the Code Challenge The client then creates a "code_challenge" derived from the code
The client then creates a code challenge derived from the code
verifier by using one of the following transformations on the code verifier by using one of the following transformations on the code
verifier: verifier:
plain
code_challenge = code_verifier
S256 S256
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
plain
code_challenge = code_verifier
If the client is capable of using "S256", it MUST use "S256", as If the client is capable of using "S256", it MUST use "S256", as
"S256" is Mandatory To Implement (MTI) on the server. Clients are "S256" is Mandatory To Implement (MTI) on the server. Clients are
permitted to use "plain" only if they cannot support "S256" for some permitted to use "plain" only if they cannot support "S256" for some
technical reason and know via out-of-band configuration or via technical reason, for example constrained environments that do not
Authorization Server Metadata ([RFC8414]) that the server supports have a hashing function available, and know via out-of-band
"plain". configuration or via Authorization Server Metadata ([RFC8414]) that
the server supports "plain".
The plain transformation is for compatibility with existing
deployments and for constrained environments that can't use the
"S256" transformation.
ABNF for "code_challenge" is as follows. ABNF for "code_challenge" is as follows.
code-challenge = 43*128unreserved code-challenge = 43*128unreserved
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
ALPHA = %x41-5A / %x61-7A ALPHA = %x41-5A / %x61-7A
DIGIT = %x30-39 DIGIT = %x30-39
4.1.1.3. Client Initiates the Authorization Request The properties "code_challenge" and "code_verifier" are adopted from
the OAuth 2.0 extension known as "Proof-Key for Code Exchange", or
The client constructs the request URI by adding the following PKCE ([RFC7636]) where this technique was originally developed.
parameters to the query component of the authorization endpoint URI
using the "application/x-www-form-urlencoded" format, per Appendix B:
"response_type": REQUIRED. Value MUST be set to "code".
"client_id": REQUIRED. The client identifier as described in
Section 2.2.
"code_challenge": REQUIRED or RECOMMENDED (see Section 9.8). Code
challenge.
"code_challenge_method": OPTIONAL, defaults to "plain" if not
present in the request. Code verifier transformation method is
"S256" or "plain".
"redirect_uri": OPTIONAL. As described in Section 3.1.2.
"scope": OPTIONAL. The scope of the access request as described by
Section 3.3.
"state": OPTIONAL. An opaque value used by the client to maintain Clients MUST use "code_challenge" and "code_verifier" and
state between the request and callback. The authorization server authorization servers MUST enforce their use except under the
includes this value when redirecting the user-agent back to the conditions described in Section 9.8. In this case, using and
client. enforcing "code_challenge" and "code_verifier" as described in the
following is still RECOMMENDED.
The client directs the resource owner to the constructed URI using an The client directs the resource owner to the constructed URI using an
HTTP redirection response, or by other means available to it via the HTTP redirection, or by other means available to it via the user-
user-agent. agent.
For example, the client directs the user-agent to make the following For example, the client directs the user-agent to make the following
HTTP request using TLS (with extra line breaks for display purposes HTTP request using TLS (with extra line breaks for display purposes
only): only):
GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY &code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY
&code_challenge_method=S256 HTTP/1.1 &code_challenge_method=S256 HTTP/1.1
Host: server.example.com Host: server.example.com
The authorization server validates the request to ensure that all The authorization server validates the request to ensure that all
required parameters are present and valid. If the request is valid, required parameters are present and valid.
the authorization server authenticates the resource owner and obtains
an authorization decision (by asking the resource owner or by In particular, the authorization server MUST validate the
establishing approval via other means). "redirect_uri" in the request if present, ensuring that it matches
one of the registered redirect URIs previously established during
client registration (Section 2). When comparing the two URIs the
authorization server MUST using simple character-by-character string
comparison as defined in [RFC3986], Section 6.2.1.
If the request is valid, the authorization server authenticates the
resource owner and obtains an authorization decision (by asking the
resource owner or by establishing approval via other means).
When a decision is established, the authorization server directs the When a decision is established, the authorization server directs the
user-agent to the provided client redirect URI using an HTTP user-agent to the provided client redirect URI using an HTTP
redirection response, or by other means available to it via the user- redirection response, or by other means available to it via the user-
agent. agent.
4.1.2. Authorization Response 4.1.2. Authorization Response
If the resource owner grants the access request, the authorization If the resource owner grants the access request, the authorization
server issues an authorization code and delivers it to the client by server issues an authorization code and delivers it to the client by
skipping to change at page 28, line 45 skipping to change at page 28, line 49
HTTP/1.1 302 Found HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA
&state=xyz &state=xyz
The client MUST ignore unrecognized response parameters. The The client MUST ignore unrecognized response parameters. The
authorization code string size is left undefined by this authorization code string size is left undefined by this
specification. The client should avoid making assumptions about code specification. The client should avoid making assumptions about code
value sizes. The authorization server SHOULD document the size of value sizes. The authorization server SHOULD document the size of
any value it issues. any value it issues.
When the server issues the authorization code in the authorization The authorization server MUST associate the "code_challenge" and
response, it MUST associate the "code_challenge" and "code_challenge_method" values with the issued authorization code so
"code_challenge_method" values with the authorization code so it can the code challenge can be verified later.
be verified later.
The "code_challenge" and "code_challenge_method" values may be stored
in encrypted form in the "code" itself, but could alternatively be
stored on the server associated with the code. The server MUST NOT
include the "code_challenge" value in client requests in a form that
other entities can extract.
The exact method that the server uses to associate the The exact method that the server uses to associate the
"code_challenge" with the issued "code" is out of scope for this "code_challenge" with the issued code is out of scope for this
specification. specification. The code challenge could be stored on the server and
associated with the code there. The "code_challenge" and
"code_challenge_method" values may be stored in encrypted form in the
code itself, but the server MUST NOT include the "code_challenge"
value in a response parameter in a form that entities other than the
AS can extract.
4.1.2.1. Error Response 4.1.2.1. Error Response
If the request fails due to a missing, invalid, or mismatching If the request fails due to a missing, invalid, or mismatching
redirect URI, or if the client identifier is missing or invalid, the redirect URI, or if the client identifier is missing or invalid, the
authorization server SHOULD inform the resource owner of the error authorization server SHOULD inform the resource owner of the error
and MUST NOT automatically redirect the user-agent to the invalid and MUST NOT automatically redirect the user-agent to the invalid
redirect URI. redirect URI.
An AS MUST reject requests without a "code_challenge" from public An AS MUST reject requests without a "code_challenge" from public
skipping to change at page 31, line 28 skipping to change at page 31, line 28
included in the authorization request as described in included in the authorization request as described in
Section 4.1.1, and their values MUST be identical. Section 4.1.1, and their values MUST be identical.
"client_id": REQUIRED, if the client is not authenticating with the "client_id": REQUIRED, if the client is not authenticating with the
authorization server as described in Section 3.2.1. authorization server as described in Section 3.2.1.
"code_verifier": REQUIRED, if the "code_challenge" parameter was "code_verifier": REQUIRED, if the "code_challenge" parameter was
included in the authorization request. MUST NOT be used included in the authorization request. MUST NOT be used
otherwise. The original code verifier string. otherwise. The original code verifier string.
If the client type is confidential or the client was issued client Confidential or credentialed clients MUST authenticate with the
credentials (or assigned other authentication requirements), the authorization server as described in Section 3.2.1.
client MUST authenticate with the authorization server as described
in Section 3.2.1.
For example, the client makes the following HTTP request using TLS For example, the client makes the following HTTP request using TLS
(with extra line breaks for display purposes only): (with extra line breaks for display purposes only):
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed &code_verifier=3641a2d12d66101249cdf7a79c000c1f8c05d2aafcf14bf146497bed
The authorization server MUST: The authorization server MUST:
* require client authentication for confidential clients or for any * require client authentication for confidential and credentialed
client that was issued client credentials (or with other clients (or clients with other authentication requirements),
authentication requirements),
* authenticate the client if client authentication is included, * authenticate the client if client authentication is included,
* ensure that the authorization code was issued to the authenticated * ensure that the authorization code was issued to the authenticated
confidential client, or if the client is public, ensure that the confidential or credentialed client, or if the client is public,
code was issued to "client_id" in the request, ensure that the code was issued to "client_id" in the request,
* verify that the authorization code is valid, * verify that the authorization code is valid,
* verify that the "code_verifier" parameter is present if and only * verify that the "code_verifier" parameter is present if and only
if a "code_challenge" parameter was present in the authorization if a "code_challenge" parameter was present in the authorization
request, request,
* if a "code_verifier" is present, verify the "code_verifier" by * if a "code_verifier" is present, verify the "code_verifier" by
calculating the code challenge from the received "code_verifier" calculating the code challenge from the received "code_verifier"
and comparing it with the previously associated "code_challenge", and comparing it with the previously associated "code_challenge",
after first transforming it according to the after first transforming it according to the
"code_challenge_method" method specified by the client, and "code_challenge_method" method specified by the client, and
* ensure that the "redirect_uri" parameter is present if the * ensure that the "redirect_uri" parameter is present if the
"redirect_uri" parameter was included in the initial authorization "redirect_uri" parameter was included in the initial authorization
request as described in Section 4.1.1.3, and if included ensure request as described in Section 4.1.1.1, and if included ensure
that their values are identical. that their values are identical.
4.1.4. Access Token Response 4.1.4. Access Token Response
If the access token request is valid and authorized, the If the access token request is valid and authorized, the
authorization server issues an access token and optional refresh authorization server issues an access token and optional refresh
token as described in Section 5.1. If the request client token as described in Section 5.1. If the request client
authentication failed or is invalid, the authorization server returns authentication failed or is invalid, the authorization server returns
an error response as described in Section 5.2. an error response as described in Section 5.2.
skipping to change at page 33, line 15 skipping to change at page 33, line 6
4.2. Client Credentials Grant 4.2. Client Credentials Grant
The client can request an access token using only its client The client can request an access token using only its client
credentials (or other supported means of authentication) when the credentials (or other supported means of authentication) when the
client is requesting access to the protected resources under its client is requesting access to the protected resources under its
control, or those of another resource owner that have been previously control, or those of another resource owner that have been previously
arranged with the authorization server (the method of which is beyond arranged with the authorization server (the method of which is beyond
the scope of this specification). the scope of this specification).
The client credentials grant type MUST only be used by confidential The client credentials grant type MUST only be used by confidential
clients. or credentialed clients.
+---------+ +---------------+ +---------+ +---------------+
| | | | | | | |
| |>--(1)- Client Authentication --->| Authorization | | |>--(1)- Client Authentication --->| Authorization |
| Client | | Server | | Client | | Server |
| |<--(2)---- Access Token ---------<| | | |<--(2)---- Access Token ---------<| |
| | | | | | | |
+---------+ +---------------+ +---------+ +---------------+
Figure 4: Client Credentials Flow Figure 4: Client Credentials Flow
skipping to change at page 35, line 36 skipping to change at page 35, line 30
If the access token request is valid and authorized, the If the access token request is valid and authorized, the
authorization server issues an access token and optional refresh authorization server issues an access token and optional refresh
token as described in Section 5.1. If the request failed client token as described in Section 5.1. If the request failed client
authentication or is invalid, the authorization server returns an authentication or is invalid, the authorization server returns an
error response as described in Section 5.2. error response as described in Section 5.2.
5.1. Successful Response 5.1. Successful Response
The authorization server issues an access token and optional refresh The authorization server issues an access token and optional refresh
token, and constructs the response by adding the following parameters token by creating an HTTP response body using the "application/json"
to the payload of the HTTP response with a 200 (OK) status code: media type as defined by [RFC8259] with the following parameters and
an HTTP 200 (OK) status code:
"access_token": REQUIRED. The access token issued by the "access_token": REQUIRED. The access token issued by the
authorization server. authorization server.
"token_type": REQUIRED. The type of the access token issued as "token_type": REQUIRED. The type of the access token issued as
described in Section 7.1. Value is case insensitive. described in Section 7.1. Value is case insensitive.
"expires_in": RECOMMENDED. The lifetime in seconds of the access "expires_in": RECOMMENDED. The lifetime in seconds of the access
token. For example, the value "3600" denotes that the access token. For example, the value "3600" denotes that the access
token will expire in one hour from the time the response was token will expire in one hour from the time the response was
skipping to change at page 36, line 11 skipping to change at page 36, line 5
the expiration time via other means or document the default value. the expiration time via other means or document the default value.
"refresh_token": OPTIONAL. The refresh token, which can be used to "refresh_token": OPTIONAL. The refresh token, which can be used to
obtain new access tokens using the same authorization grant as obtain new access tokens using the same authorization grant as
described in Section 6. described in Section 6.
"scope": OPTIONAL, if identical to the scope requested by the "scope": OPTIONAL, if identical to the scope requested by the
client; otherwise, REQUIRED. The scope of the access token as client; otherwise, REQUIRED. The scope of the access token as
described by Section 3.3. described by Section 3.3.
The parameters are included in the payload of the HTTP response using The parameters are serialized into a JavaScript Object Notation
the "application/json" media type as defined by [RFC7159]. The (JSON) structure by adding each parameter at the highest structure
parameters are serialized into a JavaScript Object Notation (JSON) level. Parameter names and string values are included as JSON
structure by adding each parameter at the highest structure level. strings. Numerical values are included as JSON numbers. The order
Parameter names and string values are included as JSON strings. of parameters does not matter and can vary.
Numerical values are included as JSON numbers. The order of
parameters does not matter and can vary.
The authorization server MUST include the HTTP "Cache-Control" The authorization server MUST include the HTTP "Cache-Control"
response header field [RFC7234] with a value of "no-store" in any response header field [RFC7234] with a value of "no-store" in any
response containing tokens, credentials, or other sensitive response containing tokens, credentials, or other sensitive
information, as well as the "Pragma" response header field [RFC7234] information, as well as the "Pragma" response header field [RFC7234]
with a value of "no-cache". with a value of "no-cache".
For example: For example:
HTTP/1.1 200 OK HTTP/1.1 200 OK
skipping to change at page 38, line 31 skipping to change at page 38, line 26
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
Pragma: no-cache Pragma: no-cache
{ {
"error":"invalid_request" "error":"invalid_request"
} }
6. Refreshing an Access Token 6. Refreshing an Access Token
Authorization servers SHOULD determine, based on a risk assessment, Authorization servers SHOULD determine, based on a risk assessment
whether to issue refresh tokens to a certain client. If the and their own policies, whether to issue refresh tokens to a certain
authorization server decides not to issue refresh tokens, the client client. If the authorization server decides not to issue refresh
MAY refresh access tokens by utilizing other grant types, such as the tokens, the client MAY obtain new access tokens by starting the OAuth
authorization code grant type. In such a case, the authorization flow over, for example initiating a new authorization code request.
server may utilize cookies and persistent grants to optimize the user In such a case, the authorization server may utilize cookies and
experience. persistent grants to optimize the user experience.
If refresh tokens are issued, those refresh tokens MUST be bound to If refresh tokens are issued, those refresh tokens MUST be bound to
the scope and resource servers as consented by the resource owner. the scope and resource servers as consented by the resource owner.
This is to prevent privilege escalation by the legitimate client and This is to prevent privilege escalation by the legitimate client and
reduce the impact of refresh token leakage. reduce the impact of refresh token leakage.
If the authorization server issued a refresh token to the client, the 6.1. Refresh Token Request
client makes a refresh request to the token endpoint by adding the
following parameters using the "application/x-www-form-urlencoded" To use a refresh token to obtain a new access token, the client makes
format per Appendix B with a character encoding of UTF-8 in the HTTP a request to the token endpoint by adding the following parameters
request payload: using the "application/x-www-form-urlencoded" format (per Appendix B)
with a character encoding of UTF-8 in the HTTP request payload:
"grant_type": REQUIRED. Value MUST be set to "refresh_token". "grant_type": REQUIRED. Value MUST be set to "refresh_token".
"refresh_token": REQUIRED. The refresh token issued to the client. "refresh_token": REQUIRED. The refresh token issued to the client.
"scope": OPTIONAL. The scope of the access request as described by "scope": OPTIONAL. The scope of the access request as described by
Section 3.3. The requested scope MUST NOT include any scope not Section 3.3. The requested scope MUST NOT include any scope not
originally granted by the resource owner, and if omitted is originally granted by the resource owner, and if omitted is
treated as equal to the scope originally granted by the resource treated as equal to the scope originally granted by the resource
owner. owner.
Because refresh tokens are typically long-lasting credentials used to Because refresh tokens are typically long-lasting credentials used to
request additional access tokens, the refresh token is bound to the request additional access tokens, the refresh token is bound to the
client to which it was issued. If the client type is confidential or client to which it was issued. Confidential or credentialed clients
the client was issued client credentials (or assigned other MUST authenticate with the authorization server as described in
authentication requirements), the client MUST authenticate with the Section 3.2.1.
authorization server as described in Section 3.2.1.
For example, the client makes the following HTTP request using For example, the client makes the following HTTP request using
transport-layer security (with extra line breaks for display purposes transport-layer security (with extra line breaks for display purposes
only): only):
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
The authorization server MUST: The authorization server MUST:
* require client authentication for confidential clients or for any * require client authentication for confidential or credentialed
client that was issued client credentials (or with other clients
authentication requirements),
* authenticate the client if client authentication is included and * authenticate the client if client authentication is included and
ensure that the refresh token was issued to the authenticated ensure that the refresh token was issued to the authenticated
client, and client, and
* validate the refresh token. * validate the refresh token.
6.1. Refresh Token Protection
Authorization servers SHOULD utilize one of these methods to detect Authorization servers SHOULD utilize one of these methods to detect
refresh token replay by malicious actors for public clients: refresh token replay by malicious actors for public clients:
* _Sender-constrained refresh tokens:_ the authorization server * _Sender-constrained refresh tokens:_ the authorization server
cryptographically binds the refresh token to a certain client cryptographically binds the refresh token to a certain client
instance by utilizing [I-D.ietf-oauth-token-binding], [RFC8705], instance by utilizing [I-D.ietf-oauth-token-binding], [RFC8705],
[I-D.ietf-oauth-dpop], or another suitable method. [I-D.ietf-oauth-dpop], or another suitable method.
* _Refresh token rotation:_ the authorization server issues a new * _Refresh token rotation:_ the authorization server issues a new
refresh token with every access token refresh response. The refresh token with every access token refresh response. The
skipping to change at page 40, line 25 skipping to change at page 40, line 17
cost of forcing the legitimate client to obtain a fresh cost of forcing the legitimate client to obtain a fresh
authorization grant. authorization grant.
Implementation note: the grant to which a refresh token belongs may Implementation note: the grant to which a refresh token belongs may
be encoded into the refresh token itself. This can enable an be encoded into the refresh token itself. This can enable an
authorization server to efficiently determine the grant to which a authorization server to efficiently determine the grant to which a
refresh token belongs, and by extension, all refresh tokens that need refresh token belongs, and by extension, all refresh tokens that need
to be revoked. Authorization servers MUST ensure the integrity of to be revoked. Authorization servers MUST ensure the integrity of
the refresh token value in this case, for example, using signatures. the refresh token value in this case, for example, using signatures.
6.2. Refresh Token Response
If valid and authorized, the authorization server issues an access If valid and authorized, the authorization server issues an access
token as described in Section 5.1. If the request failed token as described in Section 5.1. If the request failed
verification or is invalid, the authorization server returns an error verification or is invalid, the authorization server returns an error
response as described in Section 5.2. response as described in Section 5.2.
The authorization server MAY issue a new refresh token, in which case The authorization server MAY issue a new refresh token, in which case
the client MUST discard the old refresh token and replace it with the the client MUST discard the old refresh token and replace it with the
new refresh token. The authorization server MAY revoke the old new refresh token. The authorization server MAY revoke the old
refresh token after issuing a new refresh token to the client. If a refresh token after issuing a new refresh token to the client. If a
new refresh token is issued, the refresh token scope MUST be new refresh token is issued, the refresh token scope MUST be
skipping to change at page 40, line 46 skipping to change at page 40, line 40
request. request.
Authorization servers MAY revoke refresh tokens automatically in case Authorization servers MAY revoke refresh tokens automatically in case
of a security event, such as: of a security event, such as:
* password change * password change
* logout at the authorization server * logout at the authorization server
Refresh tokens SHOULD expire if the client has been inactive for some Refresh tokens SHOULD expire if the client has been inactive for some
time, i.e., the refresh token has not been used to obtain fresh time, i.e., the refresh token has not been used to obtain new access
access tokens for some time. The expiration time is at the tokens for some time. The expiration time is at the discretion of
discretion of the authorization server. It might be a global value the authorization server. It might be a global value or determined
or determined based on the client policy or the grant associated with based on the client policy or the grant associated with the refresh
the refresh token (and its sensitivity). token (and its sensitivity).
7. Accessing Protected Resources 7. Accessing Protected Resources
The client accesses protected resources by presenting the access The client accesses protected resources by presenting the access
token to the resource server. The resource server MUST validate the token to the resource server. The resource server MUST validate the
access token and ensure that it has not expired and that its scope access token and ensure that it has not expired and that its scope
covers the requested resource. The methods used by the resource covers the requested resource. The methods used by the resource
server to validate the access token (as well as any error responses) server to validate the access token (as well as any error responses)
are beyond the scope of this specification, but generally involve an are beyond the scope of this specification, but generally involve an
interaction or coordination between the resource server and the interaction or coordination between the resource server and the
skipping to change at page 58, line 25 skipping to change at page 58, line 25
refresh tokens were issued. The authorization server MUST maintain refresh tokens were issued. The authorization server MUST maintain
the binding between a refresh token and the client to whom it was the binding between a refresh token and the client to whom it was
issued. Refresh tokens MUST only be transmitted using TLS as issued. Refresh tokens MUST only be transmitted using TLS as
described in Section 1.6 with server authentication as defined by described in Section 1.6 with server authentication as defined by
[RFC2818]. [RFC2818].
The authorization server MUST verify the binding between the refresh The authorization server MUST verify the binding between the refresh
token and client identity whenever the client identity can be token and client identity whenever the client identity can be
authenticated. When client authentication is not possible, the authenticated. When client authentication is not possible, the
authorization server SHOULD issue sender-constrained refresh tokens authorization server SHOULD issue sender-constrained refresh tokens
or use refresh token rotation as described in or use refresh token rotation as described in (#refreshing-an-access-
(#refresh_token_protection). token).
The authorization server MUST ensure that refresh tokens cannot be The authorization server MUST ensure that refresh tokens cannot be
generated, modified, or guessed to produce valid refresh tokens by generated, modified, or guessed to produce valid refresh tokens by
unauthorized parties. unauthorized parties.
9.6. Client Impersonating Resource Owner 9.6. Client Impersonating Resource Owner
Resource servers may make access control decisions based on the Resource servers may make access control decisions based on the
identity of the resource owner as communicated in the "sub" claim identity of the resource owner as communicated in the "sub" claim
returned by the authorization server in a token introspection returned by the authorization server in a token introspection
skipping to change at page 76, line 41 skipping to change at page 76, line 41
<https://www.rfc-editor.org/info/rfc7595>. <https://www.rfc-editor.org/info/rfc7595>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017,
<https://www.rfc-editor.org/info/rfc8252>. <https://www.rfc-editor.org/info/rfc8252>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, Interchange Format", STD 90, RFC 8259,
<https://www.rfc-editor.org/info/rfc8446>. DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[USASCII] Institute, A.N.S., "Coded Character Set -- 7-bit American [USASCII] Institute, A.N.S., "Coded Character Set -- 7-bit American
Standard Code for Information Interchange, ANSI X3.4", Standard Code for Information Interchange, ANSI X3.4",
1986. 1986.
[W3C.REC-html401-19991224] [W3C.REC-html401-19991224]
Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01
Specification", World Wide Web Consortium Recommendation Specification", World Wide Web Consortium Recommendation
REC-html401-19991224, 24 December 1999, REC-html401-19991224, 24 December 1999,
<https://www.w3.org/TR/1999/REC-html401-19991224>. <https://www.w3.org/TR/1999/REC-html401-19991224>.
 End of changes. 60 change blocks. 
193 lines changed or deleted 188 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/