tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 6749

 
 
 

The OAuth 2.0 Authorization Framework

Part 3 of 4, p. 43 to 68
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 43 
5.  Issuing an Access Token

   If the access token request is valid and authorized, the
   authorization server issues an access token and optional refresh
   token as described in Section 5.1.  If the request failed client
   authentication or is invalid, the authorization server returns an
   error response as described in Section 5.2.

5.1.  Successful Response

   The authorization server issues an access token and optional refresh
   token, and constructs the response by adding the following parameters
   to the entity-body of the HTTP response with a 200 (OK) status code:

   access_token
         REQUIRED.  The access token issued by the authorization server.

   token_type
         REQUIRED.  The type of the token issued as described in
         Section 7.1.  Value is case insensitive.

   expires_in
         RECOMMENDED.  The lifetime in seconds of the access token.  For
         example, the value "3600" denotes that the access token will
         expire in one hour from the time the response was generated.
         If omitted, the authorization server SHOULD provide the
         expiration time via other means or document the default value.

Top      Up      ToC       Page 44 
   refresh_token
         OPTIONAL.  The refresh token, which can be used to obtain new
         access tokens using the same authorization grant as described
         in Section 6.

   scope
         OPTIONAL, if identical to the scope requested by the client;
         otherwise, REQUIRED.  The scope of the access token as
         described by Section 3.3.

   The parameters are included in the entity-body of the HTTP response
   using the "application/json" media type as defined by [RFC4627].  The
   parameters are serialized into a JavaScript Object Notation (JSON)
   structure by adding each parameter at the highest structure level.
   Parameter names and string values are included as JSON strings.
   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"
   response header field [RFC2616] with a value of "no-store" in any
   response containing tokens, credentials, or other sensitive
   information, as well as the "Pragma" response header field [RFC2616]
   with a value of "no-cache".

   For example:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"example",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

   The client MUST ignore unrecognized value names in the response.  The
   sizes of tokens and other values received from the authorization
   server are left undefined.  The client should avoid making
   assumptions about value sizes.  The authorization server SHOULD
   document the size of any value it issues.

Top      Up      ToC       Page 45 
5.2.  Error Response

   The authorization server responds with an HTTP 400 (Bad Request)
   status code (unless specified otherwise) and includes the following
   parameters with the response:

   error
         REQUIRED.  A single ASCII [USASCII] error code from the
         following:

         invalid_request
               The request is missing a required parameter, includes an
               unsupported parameter value (other than grant type),
               repeats a parameter, includes multiple credentials,
               utilizes more than one mechanism for authenticating the
               client, or is otherwise malformed.

         invalid_client
               Client authentication failed (e.g., unknown client, no
               client authentication included, or unsupported
               authentication method).  The authorization server MAY
               return an HTTP 401 (Unauthorized) status code to indicate
               which HTTP authentication schemes are supported.  If the
               client attempted to authenticate via the "Authorization"
               request header field, the authorization server MUST
               respond with an HTTP 401 (Unauthorized) status code and
               include the "WWW-Authenticate" response header field
               matching the authentication scheme used by the client.

         invalid_grant
               The provided authorization grant (e.g., authorization
               code, resource owner credentials) or refresh token is
               invalid, expired, revoked, does not match the redirection
               URI used in the authorization request, or was issued to
               another client.

         unauthorized_client
               The authenticated client is not authorized to use this
               authorization grant type.

         unsupported_grant_type
               The authorization grant type is not supported by the
               authorization server.

Top      Up      ToC       Page 46 
         invalid_scope
               The requested scope is invalid, unknown, malformed, or
               exceeds the scope granted by the resource owner.

         Values for the "error" parameter MUST NOT include characters
         outside the set %x20-21 / %x23-5B / %x5D-7E.

   error_description
         OPTIONAL.  Human-readable ASCII [USASCII] text providing
         additional information, used to assist the client developer in
         understanding the error that occurred.
         Values for the "error_description" parameter MUST NOT include
         characters outside the set %x20-21 / %x23-5B / %x5D-7E.

   error_uri
         OPTIONAL.  A URI identifying a human-readable web page with
         information about the error, used to provide the client
         developer with additional information about the error.
         Values for the "error_uri" parameter MUST conform to the
         URI-reference syntax and thus MUST NOT include characters
         outside the set %x21 / %x23-5B / %x5D-7E.

   The parameters are included in the entity-body of the HTTP response
   using the "application/json" media type as defined by [RFC4627].  The
   parameters are serialized into a JSON structure by adding each
   parameter at the highest structure level.  Parameter names and string
   values are included as JSON strings.  Numerical values are included
   as JSON numbers.  The order of parameters does not matter and can
   vary.

   For example:

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

Top      Up      ToC       Page 47 
6.  Refreshing an Access Token

   If the authorization server issued a refresh token to the client, the
   client makes a refresh request to the token endpoint by adding the
   following parameters using the "application/x-www-form-urlencoded"
   format per Appendix B with a character encoding of UTF-8 in the HTTP
   request entity-body:

   grant_type
         REQUIRED.  Value MUST be set to "refresh_token".

   refresh_token
         REQUIRED.  The refresh token issued to the client.

   scope
         OPTIONAL.  The scope of the access request as described by
         Section 3.3.  The requested scope MUST NOT include any scope
         not originally granted by the resource owner, and if omitted is
         treated as equal to the scope originally granted by the
         resource owner.

   Because refresh tokens are typically long-lasting credentials used to
   request additional access tokens, the refresh token is bound to the
   client to which it was issued.  If the client type is confidential or
   the client was issued client credentials (or assigned other
   authentication requirements), the client MUST authenticate with the
   authorization server as described in Section 3.2.1.

   For example, the client makes the following HTTP request using
   transport-layer security (with extra line breaks for display purposes
   only):

     POST /token HTTP/1.1
     Host: server.example.com
     Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
     Content-Type: application/x-www-form-urlencoded

     grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Top      Up      ToC       Page 48 
   The authorization server MUST:

   o  require client authentication for confidential clients or for any
      client that was issued client credentials (or with other
      authentication requirements),

   o  authenticate the client if client authentication is included and
      ensure that the refresh token was issued to the authenticated
      client, and

   o  validate the refresh token.

   If valid and authorized, the authorization server issues an access
   token as described in Section 5.1.  If the request failed
   verification or is invalid, the authorization server returns an error
   response as described in Section 5.2.

   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
   new refresh token.  The authorization server MAY revoke the old
   refresh token after issuing a new refresh token to the client.  If a
   new refresh token is issued, the refresh token scope MUST be
   identical to that of the refresh token included by the client in the
   request.

7.  Accessing Protected Resources

   The client accesses protected resources by presenting the access
   token to the resource server.  The resource server MUST validate the
   access token and ensure that it has not expired and that its scope
   covers the requested resource.  The methods used by the resource
   server to validate the access token (as well as any error responses)
   are beyond the scope of this specification but generally involve an
   interaction or coordination between the resource server and the
   authorization server.

   The method in which the client utilizes the access token to
   authenticate with the resource server depends on the type of access
   token issued by the authorization server.  Typically, it involves
   using the HTTP "Authorization" request header field [RFC2617] with an
   authentication scheme defined by the specification of the access
   token type used, such as [RFC6750].

Top      Up      ToC       Page 49 
7.1.  Access Token Types

   The access token type provides the client with the information
   required to successfully utilize the access token to make a protected
   resource request (along with type-specific attributes).  The client
   MUST NOT use an access token if it does not understand the token
   type.

   For example, the "bearer" token type defined in [RFC6750] is utilized
   by simply including the access token string in the request:

     GET /resource/1 HTTP/1.1
     Host: example.com
     Authorization: Bearer mF_9.B5f-4.1JqM

   while the "mac" token type defined in [OAuth-HTTP-MAC] is utilized by
   issuing a Message Authentication Code (MAC) key together with the
   access token that is used to sign certain components of the HTTP
   requests:

     GET /resource/1 HTTP/1.1
     Host: example.com
     Authorization: MAC id="h480djs93hd8",
                        nonce="274312:dj83hs9s",
                        mac="kDZvddkndxvhGRXZhvuDjEWhGeE="

   The above examples are provided for illustration purposes only.
   Developers are advised to consult the [RFC6750] and [OAuth-HTTP-MAC]
   specifications before use.

   Each access token type definition specifies the additional attributes
   (if any) sent to the client together with the "access_token" response
   parameter.  It also defines the HTTP authentication method used to
   include the access token when making a protected resource request.

7.2.  Error Response

   If a resource access request fails, the resource server SHOULD inform
   the client of the error.  While the specifics of such error responses
   are beyond the scope of this specification, this document establishes
   a common registry in Section 11.4 for error values to be shared among
   OAuth token authentication schemes.

   New authentication schemes designed primarily for OAuth token
   authentication SHOULD define a mechanism for providing an error
   status code to the client, in which the error values allowed are
   registered in the error registry established by this specification.

Top      Up      ToC       Page 50 
   Such schemes MAY limit the set of valid error codes to a subset of
   the registered values.  If the error code is returned using a named
   parameter, the parameter name SHOULD be "error".

   Other schemes capable of being used for OAuth token authentication,
   but not primarily designed for that purpose, MAY bind their error
   values to the registry in the same manner.

   New authentication schemes MAY choose to also specify the use of the
   "error_description" and "error_uri" parameters to return error
   information in a manner parallel to their usage in this
   specification.

8.  Extensibility

8.1.  Defining Access Token Types

   Access token types can be defined in one of two ways: registered in
   the Access Token Types registry (following the procedures in
   Section 11.1), or by using a unique absolute URI as its name.

   Types utilizing a URI name SHOULD be limited to vendor-specific
   implementations that are not commonly applicable, and are specific to
   the implementation details of the resource server where they are
   used.

   All other types MUST be registered.  Type names MUST conform to the
   type-name ABNF.  If the type definition includes a new HTTP
   authentication scheme, the type name SHOULD be identical to the HTTP
   authentication scheme name (as defined by [RFC2617]).  The token type
   "example" is reserved for use in examples.

     type-name  = 1*name-char
     name-char  = "-" / "." / "_" / DIGIT / ALPHA

8.2.  Defining New Endpoint Parameters

   New request or response parameters for use with the authorization
   endpoint or the token endpoint are defined and registered in the
   OAuth Parameters registry following the procedure in Section 11.2.

   Parameter names MUST conform to the param-name ABNF, and parameter
   values syntax MUST be well-defined (e.g., using ABNF, or a reference
   to the syntax of an existing parameter).

     param-name  = 1*name-char
     name-char   = "-" / "." / "_" / DIGIT / ALPHA

Top      Up      ToC       Page 51 
   Unregistered vendor-specific parameter extensions that are not
   commonly applicable and that are specific to the implementation
   details of the authorization server where they are used SHOULD
   utilize a vendor-specific prefix that is not likely to conflict with
   other registered values (e.g., begin with 'companyname_').

8.3.  Defining New Authorization Grant Types

   New authorization grant types can be defined by assigning them a
   unique absolute URI for use with the "grant_type" parameter.  If the
   extension grant type requires additional token endpoint parameters,
   they MUST be registered in the OAuth Parameters registry as described
   by Section 11.2.

8.4.  Defining New Authorization Endpoint Response Types

   New response types for use with the authorization endpoint are
   defined and registered in the Authorization Endpoint Response Types
   registry following the procedure in Section 11.3.  Response type
   names MUST conform to the response-type ABNF.

     response-type  = response-name *( SP response-name )
     response-name  = 1*response-char
     response-char  = "_" / DIGIT / ALPHA

   If a response type contains one or more space characters (%x20), it
   is compared as a space-delimited list of values in which the order of
   values does not matter.  Only one order of values can be registered,
   which covers all other arrangements of the same set of values.

   For example, the response type "token code" is left undefined by this
   specification.  However, an extension can define and register the
   "token code" response type.  Once registered, the same combination
   cannot be registered as "code token", but both values can be used to
   denote the same response type.

8.5.  Defining Additional Error Codes

   In cases where protocol extensions (i.e., access token types,
   extension parameters, or extension grant types) require additional
   error codes to be used with the authorization code grant error
   response (Section 4.1.2.1), the implicit grant error response
   (Section 4.2.2.1), the token error response (Section 5.2), or the
   resource access error response (Section 7.2), such error codes MAY be
   defined.

Top      Up      ToC       Page 52 
   Extension error codes MUST be registered (following the procedures in
   Section 11.4) if the extension they are used in conjunction with is a
   registered access token type, a registered endpoint parameter, or an
   extension grant type.  Error codes used with unregistered extensions
   MAY be registered.

   Error codes MUST conform to the error ABNF and SHOULD be prefixed by
   an identifying name when possible.  For example, an error identifying
   an invalid value set to the extension parameter "example" SHOULD be
   named "example_invalid".

     error      = 1*error-char
     error-char = %x20-21 / %x23-5B / %x5D-7E

9.  Native Applications

   Native applications are clients installed and executed on the device
   used by the resource owner (i.e., desktop application, native mobile
   application).  Native applications require special consideration
   related to security, platform capabilities, and overall end-user
   experience.

   The authorization endpoint requires interaction between the client
   and the resource owner's user-agent.  Native applications can invoke
   an external user-agent or embed a user-agent within the application.
   For example:

   o  External user-agent - the native application can capture the
      response from the authorization server using a redirection URI
      with a scheme registered with the operating system to invoke the
      client as the handler, manual copy-and-paste of the credentials,
      running a local web server, installing a user-agent extension, or
      by providing a redirection URI identifying a server-hosted
      resource under the client's control, which in turn makes the
      response available to the native application.

   o  Embedded user-agent - the native application obtains the response
      by directly communicating with the embedded user-agent by
      monitoring state changes emitted during the resource load, or
      accessing the user-agent's cookies storage.

   When choosing between an external or embedded user-agent, developers
   should consider the following:

   o  An external user-agent may improve completion rate, as the
      resource owner may already have an active session with the
      authorization server, removing the need to re-authenticate.  It
      provides a familiar end-user experience and functionality.  The

Top      Up      ToC       Page 53 
      resource owner may also rely on user-agent features or extensions
      to assist with authentication (e.g., password manager, 2-factor
      device reader).

   o  An embedded user-agent may offer improved usability, as it removes
      the need to switch context and open new windows.

   o  An embedded user-agent poses a security challenge because resource
      owners are authenticating in an unidentified window without access
      to the visual protections found in most external user-agents.  An
      embedded user-agent educates end-users to trust unidentified
      requests for authentication (making phishing attacks easier to
      execute).

   When choosing between the implicit grant type and the authorization
   code grant type, the following should be considered:

   o  Native applications that use the authorization code grant type
      SHOULD do so without using client credentials, due to the native
      application's inability to keep client credentials confidential.

   o  When using the implicit grant type flow, a refresh token is not
      returned, which requires repeating the authorization process once
      the access token expires.

10.  Security Considerations

   As a flexible and extensible framework, OAuth's security
   considerations depend on many factors.  The following sections
   provide implementers with security guidelines focused on the three
   client profiles described in Section 2.1: web application,
   user-agent-based application, and native application.

   A comprehensive OAuth security model and analysis, as well as
   background for the protocol design, is provided by
   [OAuth-THREATMODEL].

10.1.  Client Authentication

   The authorization server establishes client credentials with web
   application clients for the purpose of client authentication.  The
   authorization server is encouraged to consider stronger client
   authentication means than a client password.  Web application clients
   MUST ensure confidentiality of client passwords and other client
   credentials.

Top      Up      ToC       Page 54 
   The authorization server MUST NOT issue client passwords or other
   client credentials to native application or user-agent-based
   application clients for the purpose of client authentication.  The
   authorization server MAY issue a client password or other credentials
   for a specific installation of a native application client on a
   specific device.

   When client authentication is not possible, the authorization server
   SHOULD employ other means to validate the client's identity -- for
   example, by requiring the registration of the client redirection URI
   or enlisting the resource owner to confirm identity.  A valid
   redirection URI is not sufficient to verify the client's identity
   when asking for resource owner authorization but can be used to
   prevent delivering credentials to a counterfeit client after
   obtaining resource owner authorization.

   The authorization server must consider the security implications of
   interacting with unauthenticated clients and take measures to limit
   the potential exposure of other credentials (e.g., refresh tokens)
   issued to such clients.

10.2.  Client Impersonation

   A malicious client can impersonate another client and obtain access
   to protected resources if the impersonated client fails to, or is
   unable to, keep its client credentials confidential.

   The authorization server MUST authenticate the client whenever
   possible.  If the authorization server cannot authenticate the client
   due to the client's nature, the authorization server MUST require the
   registration of any redirection URI used for receiving authorization
   responses and SHOULD utilize other means to protect resource owners
   from such potentially malicious clients.  For example, the
   authorization server can engage the resource owner to assist in
   identifying the client and its origin.

   The authorization server SHOULD enforce explicit resource owner
   authentication and provide the resource owner with information about
   the client and the requested authorization scope and lifetime.  It is
   up to the resource owner to review the information in the context of
   the current client and to authorize or deny the request.

   The authorization server SHOULD NOT process repeated authorization
   requests automatically (without active resource owner interaction)
   without authenticating the client or relying on other measures to
   ensure that the repeated request comes from the original client and
   not an impersonator.

Top      Up      ToC       Page 55 
10.3.  Access Tokens

   Access token credentials (as well as any confidential access token
   attributes) MUST be kept confidential in transit and storage, and
   only shared among the authorization server, the resource servers the
   access token is valid for, and the client to whom the access token is
   issued.  Access token credentials MUST only be transmitted using TLS
   as described in Section 1.6 with server authentication as defined by
   [RFC2818].

   When using the implicit grant type, the access token is transmitted
   in the URI fragment, which can expose it to unauthorized parties.

   The authorization server MUST ensure that access tokens cannot be
   generated, modified, or guessed to produce valid access tokens by
   unauthorized parties.

   The client SHOULD request access tokens with the minimal scope
   necessary.  The authorization server SHOULD take the client identity
   into account when choosing how to honor the requested scope and MAY
   issue an access token with less rights than requested.

   This specification does not provide any methods for the resource
   server to ensure that an access token presented to it by a given
   client was issued to that client by the authorization server.

10.4.  Refresh Tokens

   Authorization servers MAY issue refresh tokens to web application
   clients and native application clients.

   Refresh tokens MUST be kept confidential in transit and storage, and
   shared only among the authorization server and the client to whom the
   refresh tokens were issued.  The authorization server MUST maintain
   the binding between a refresh token and the client to whom it was
   issued.  Refresh tokens MUST only be transmitted using TLS as
   described in Section 1.6 with server authentication as defined by
   [RFC2818].

   The authorization server MUST verify the binding between the refresh
   token and client identity whenever the client identity can be
   authenticated.  When client authentication is not possible, the
   authorization server SHOULD deploy other means to detect refresh
   token abuse.

   For example, the authorization server could employ refresh token
   rotation in which a new refresh token is issued with every access
   token refresh response.  The previous refresh token is invalidated

Top      Up      ToC       Page 56 
   but retained by the authorization server.  If a refresh token is
   compromised and subsequently used by both the attacker and the
   legitimate client, one of them will present an invalidated refresh
   token, which will inform the authorization server of the breach.

   The authorization server MUST ensure that refresh tokens cannot be
   generated, modified, or guessed to produce valid refresh tokens by
   unauthorized parties.

10.5.  Authorization Codes

   The transmission of authorization codes SHOULD be made over a secure
   channel, and the client SHOULD require the use of TLS with its
   redirection URI if the URI identifies a network resource.  Since
   authorization codes are transmitted via user-agent redirections, they
   could potentially be disclosed through user-agent history and HTTP
   referrer headers.

   Authorization codes operate as plaintext bearer credentials, used to
   verify that the resource owner who granted authorization at the
   authorization server is the same resource owner returning to the
   client to complete the process.  Therefore, if the client relies on
   the authorization code for its own resource owner authentication, the
   client redirection endpoint MUST require the use of TLS.

   Authorization codes MUST be short lived and single-use.  If the
   authorization server observes multiple attempts to exchange an
   authorization code for an access token, the authorization server
   SHOULD attempt to revoke all access tokens already granted based on
   the compromised authorization code.

   If the client can be authenticated, the authorization servers MUST
   authenticate the client and ensure that the authorization code was
   issued to the same client.

10.6.  Authorization Code Redirection URI Manipulation

   When requesting authorization using the authorization code grant
   type, the client can specify a redirection URI via the "redirect_uri"
   parameter.  If an attacker can manipulate the value of the
   redirection URI, it can cause the authorization server to redirect
   the resource owner user-agent to a URI under the control of the
   attacker with the authorization code.

   An attacker can create an account at a legitimate client and initiate
   the authorization flow.  When the attacker's user-agent is sent to
   the authorization server to grant access, the attacker grabs the
   authorization URI provided by the legitimate client and replaces the

Top      Up      ToC       Page 57 
   client's redirection URI with a URI under the control of the
   attacker.  The attacker then tricks the victim into following the
   manipulated link to authorize access to the legitimate client.

   Once at the authorization server, the victim is prompted with a
   normal, valid request on behalf of a legitimate and trusted client,
   and authorizes the request.  The victim is then redirected to an
   endpoint under the control of the attacker with the authorization
   code.  The attacker completes the authorization flow by sending the
   authorization code to the client using the original redirection URI
   provided by the client.  The client exchanges the authorization code
   with an access token and links it to the attacker's client account,
   which can now gain access to the protected resources authorized by
   the victim (via the client).

   In order to prevent such an attack, the authorization server MUST
   ensure that the redirection URI used to obtain the authorization code
   is identical to the redirection URI provided when exchanging the
   authorization code for an access token.  The authorization server
   MUST require public clients and SHOULD require confidential clients
   to register their redirection URIs.  If a redirection URI is provided
   in the request, the authorization server MUST validate it against the
   registered value.

10.7.  Resource Owner Password Credentials

   The resource owner password credentials grant type is often used for
   legacy or migration reasons.  It reduces the overall risk of storing
   usernames and passwords by the client but does not eliminate the need
   to expose highly privileged credentials to the client.

   This grant type carries a higher risk than other grant types because
   it maintains the password anti-pattern this protocol seeks to avoid.
   The client could abuse the password, or the password could
   unintentionally be disclosed to an attacker (e.g., via log files or
   other records kept by the client).

   Additionally, because the resource owner does not have control over
   the authorization process (the resource owner's involvement ends when
   it hands over its credentials to the client), the client can obtain
   access tokens with a broader scope than desired by the resource
   owner.  The authorization server should consider the scope and
   lifetime of access tokens issued via this grant type.

   The authorization server and client SHOULD minimize use of this grant
   type and utilize other grant types whenever possible.

Top      Up      ToC       Page 58 
10.8.  Request Confidentiality

   Access tokens, refresh tokens, resource owner passwords, and client
   credentials MUST NOT be transmitted in the clear.  Authorization
   codes SHOULD NOT be transmitted in the clear.

   The "state" and "scope" parameters SHOULD NOT include sensitive
   client or resource owner information in plain text, as they can be
   transmitted over insecure channels or stored insecurely.

10.9.  Ensuring Endpoint Authenticity

   In order to prevent man-in-the-middle attacks, the authorization
   server MUST require the use of TLS with server authentication as
   defined by [RFC2818] for any request sent to the authorization and
   token endpoints.  The client MUST validate the authorization server's
   TLS certificate as defined by [RFC6125] and in accordance with its
   requirements for server identity authentication.

10.10.  Credentials-Guessing Attacks

   The authorization server MUST prevent attackers from guessing access
   tokens, authorization codes, refresh tokens, resource owner
   passwords, and client credentials.

   The probability of an attacker guessing generated tokens (and other
   credentials not intended for handling by end-users) MUST be less than
   or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160).

   The authorization server MUST utilize other means to protect
   credentials intended for end-user usage.

10.11.  Phishing Attacks

   Wide deployment of this and similar protocols may cause end-users to
   become inured to the practice of being redirected to websites where
   they are asked to enter their passwords.  If end-users are not
   careful to verify the authenticity of these websites before entering
   their credentials, it will be possible for attackers to exploit this
   practice to steal resource owners' passwords.

   Service providers should attempt to educate end-users about the risks
   phishing attacks pose and should provide mechanisms that make it easy
   for end-users to confirm the authenticity of their sites.  Client
   developers should consider the security implications of how they
   interact with the user-agent (e.g., external, embedded), and the
   ability of the end-user to verify the authenticity of the
   authorization server.

Top      Up      ToC       Page 59 
   To reduce the risk of phishing attacks, the authorization servers
   MUST require the use of TLS on every endpoint used for end-user
   interaction.

10.12.  Cross-Site Request Forgery

   Cross-site request forgery (CSRF) is an exploit in which an attacker
   causes the user-agent of a victim end-user to follow a malicious URI
   (e.g., provided to the user-agent as a misleading link, image, or
   redirection) to a trusting server (usually established via the
   presence of a valid session cookie).

   A CSRF attack against the client's redirection URI allows an attacker
   to inject its own authorization code or access token, which can
   result in the client using an access token associated with the
   attacker's protected resources rather than the victim's (e.g., save
   the victim's bank account information to a protected resource
   controlled by the attacker).

   The client MUST implement CSRF protection for its redirection URI.
   This is typically accomplished by requiring any request sent to the
   redirection URI endpoint to include a value that binds the request to
   the user-agent's authenticated state (e.g., a hash of the session
   cookie used to authenticate the user-agent).  The client SHOULD
   utilize the "state" request parameter to deliver this value to the
   authorization server when making an authorization request.

   Once authorization has been obtained from the end-user, the
   authorization server redirects the end-user's user-agent back to the
   client with the required binding value contained in the "state"
   parameter.  The binding value enables the client to verify the
   validity of the request by matching the binding value to the
   user-agent's authenticated state.  The binding value used for CSRF
   protection MUST contain a non-guessable value (as described in
   Section 10.10), and the user-agent's authenticated state (e.g.,
   session cookie, HTML5 local storage) MUST be kept in a location
   accessible only to the client and the user-agent (i.e., protected by
   same-origin policy).

   A CSRF attack against the authorization server's authorization
   endpoint can result in an attacker obtaining end-user authorization
   for a malicious client without involving or alerting the end-user.

   The authorization server MUST implement CSRF protection for its
   authorization endpoint and ensure that a malicious client cannot
   obtain authorization without the awareness and explicit consent of
   the resource owner.

Top      Up      ToC       Page 60 
10.13.  Clickjacking

   In a clickjacking attack, an attacker registers a legitimate client
   and then constructs a malicious site in which it loads the
   authorization server's authorization endpoint web page in a
   transparent iframe overlaid on top of a set of dummy buttons, which
   are carefully constructed to be placed directly under important
   buttons on the authorization page.  When an end-user clicks a
   misleading visible button, the end-user is actually clicking an
   invisible button on the authorization page (such as an "Authorize"
   button).  This allows an attacker to trick a resource owner into
   granting its client access without the end-user's knowledge.

   To prevent this form of attack, native applications SHOULD use
   external browsers instead of embedding browsers within the
   application when requesting end-user authorization.  For most newer
   browsers, avoidance of iframes can be enforced by the authorization
   server using the (non-standard) "x-frame-options" header.  This
   header can have two values, "deny" and "sameorigin", which will block
   any framing, or framing by sites with a different origin,
   respectively.  For older browsers, JavaScript frame-busting
   techniques can be used but may not be effective in all browsers.

10.14.  Code Injection and Input Validation

   A code injection attack occurs when an input or otherwise external
   variable is used by an application unsanitized and causes
   modification to the application logic.  This may allow an attacker to
   gain access to the application device or its data, cause denial of
   service, or introduce a wide range of malicious side-effects.

   The authorization server and client MUST sanitize (and validate when
   possible) any value received -- in particular, the value of the
   "state" and "redirect_uri" parameters.

10.15.  Open Redirectors

   The authorization server, authorization endpoint, and client
   redirection endpoint can be improperly configured and operate as open
   redirectors.  An open redirector is an endpoint using a parameter to
   automatically redirect a user-agent to the location specified by the
   parameter value without any validation.

   Open redirectors can be used in phishing attacks, or by an attacker
   to get end-users to visit malicious sites by using the URI authority
   component of a familiar and trusted destination.  In addition, if the
   authorization server allows the client to register only part of the
   redirection URI, an attacker can use an open redirector operated by

Top      Up      ToC       Page 61 
   the client to construct a redirection URI that will pass the
   authorization server validation but will send the authorization code
   or access token to an endpoint under the control of the attacker.

10.16.  Misuse of Access Token to Impersonate Resource Owner in Implicit
        Flow

   For public clients using implicit flows, this specification does not
   provide any method for the client to determine what client an access
   token was issued to.

   A resource owner may willingly delegate access to a resource by
   granting an access token to an attacker's malicious client.  This may
   be due to phishing or some other pretext.  An attacker may also steal
   a token via some other mechanism.  An attacker may then attempt to
   impersonate the resource owner by providing the access token to a
   legitimate public client.

   In the implicit flow (response_type=token), the attacker can easily
   switch the token in the response from the authorization server,
   replacing the real access token with the one previously issued to the
   attacker.

   Servers communicating with native applications that rely on being
   passed an access token in the back channel to identify the user of
   the client may be similarly compromised by an attacker creating a
   compromised application that can inject arbitrary stolen access
   tokens.

   Any public client that makes the assumption that only the resource
   owner can present it with a valid access token for the resource is
   vulnerable to this type of attack.

   This type of attack may expose information about the resource owner
   at the legitimate client to the attacker (malicious client).  This
   will also allow the attacker to perform operations at the legitimate
   client with the same permissions as the resource owner who originally
   granted the access token or authorization code.

   Authenticating resource owners to clients is out of scope for this
   specification.  Any specification that uses the authorization process
   as a form of delegated end-user authentication to the client (e.g.,
   third-party sign-in service) MUST NOT use the implicit flow without
   additional security mechanisms that would enable the client to
   determine if the access token was issued for its use (e.g., audience-
   restricting the access token).

Top      Up      ToC       Page 62 
11.  IANA Considerations

11.1.  OAuth Access Token Types Registry

   This specification establishes the OAuth Access Token Types registry.

   Access token types are registered with a Specification Required
   ([RFC5226]) after a two-week review period on the
   oauth-ext-review@ietf.org mailing list, on the advice of one or more
   Designated Experts.  However, to allow for the allocation of values
   prior to publication, the Designated Expert(s) may approve
   registration once they are satisfied that such a specification will
   be published.

   Registration requests must be sent to the oauth-ext-review@ietf.org
   mailing list for review and comment, with an appropriate subject
   (e.g., "Request for access token type: example").

   Within the review period, the Designated Expert(s) will either
   approve or deny the registration request, communicating this decision
   to the review list and IANA.  Denials should include an explanation
   and, if applicable, suggestions as to how to make the request
   successful.

   IANA must only accept registry updates from the Designated Expert(s)
   and should direct all requests for registration to the review mailing
   list.

11.1.1.  Registration Template

   Type name:
      The name requested (e.g., "example").

   Additional Token Endpoint Response Parameters:
      Additional response parameters returned together with the
      "access_token" parameter.  New parameters MUST be separately
      registered in the OAuth Parameters registry as described by
      Section 11.2.

   HTTP Authentication Scheme(s):
      The HTTP authentication scheme name(s), if any, used to
      authenticate protected resource requests using access tokens of
      this type.

   Change controller:
      For Standards Track RFCs, state "IETF".  For others, give the name
      of the responsible party.  Other details (e.g., postal address,
      email address, home page URI) may also be included.

Top      Up      ToC       Page 63 
   Specification document(s):
      Reference to the document(s) that specify the parameter,
      preferably including a URI that can be used to retrieve a copy of
      the document(s).  An indication of the relevant sections may also
      be included but is not required.

11.2.  OAuth Parameters Registry

   This specification establishes the OAuth Parameters registry.

   Additional parameters for inclusion in the authorization endpoint
   request, the authorization endpoint response, the token endpoint
   request, or the token endpoint response are registered with a
   Specification Required ([RFC5226]) after a two-week review period on
   the oauth-ext-review@ietf.org mailing list, on the advice of one or
   more Designated Experts.  However, to allow for the allocation of
   values prior to publication, the Designated Expert(s) may approve
   registration once they are satisfied that such a specification will
   be published.

   Registration requests must be sent to the oauth-ext-review@ietf.org
   mailing list for review and comment, with an appropriate subject
   (e.g., "Request for parameter: example").

   Within the review period, the Designated Expert(s) will either
   approve or deny the registration request, communicating this decision
   to the review list and IANA.  Denials should include an explanation
   and, if applicable, suggestions as to how to make the request
   successful.

   IANA must only accept registry updates from the Designated Expert(s)
   and should direct all requests for registration to the review mailing
   list.

11.2.1.  Registration Template

   Parameter name:
      The name requested (e.g., "example").

   Parameter usage location:
      The location(s) where parameter can be used.  The possible
      locations are authorization request, authorization response, token
      request, or token response.

   Change controller:
      For Standards Track RFCs, state "IETF".  For others, give the name
      of the responsible party.  Other details (e.g., postal address,
      email address, home page URI) may also be included.

Top      Up      ToC       Page 64 
   Specification document(s):
      Reference to the document(s) that specify the parameter,
      preferably including a URI that can be used to retrieve a copy of
      the document(s).  An indication of the relevant sections may also
      be included but is not required.

11.2.2.  Initial Registry Contents

   The OAuth Parameters registry's initial contents are:

   o  Parameter name: client_id
   o  Parameter usage location: authorization request, token request
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: client_secret
   o  Parameter usage location: token request
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: response_type
   o  Parameter usage location: authorization request
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: redirect_uri
   o  Parameter usage location: authorization request, token request
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: scope
   o  Parameter usage location: authorization request, authorization
      response, token request, token response
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: state
   o  Parameter usage location: authorization request, authorization
      response
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: code
   o  Parameter usage location: authorization response, token request
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

Top      Up      ToC       Page 65 
   o  Parameter name: error_description
   o  Parameter usage location: authorization response, token response
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: error_uri
   o  Parameter usage location: authorization response, token response
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: grant_type
   o  Parameter usage location: token request
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: access_token
   o  Parameter usage location: authorization response, token response
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: token_type
   o  Parameter usage location: authorization response, token response
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: expires_in
   o  Parameter usage location: authorization response, token response
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: username
   o  Parameter usage location: token request
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: password
   o  Parameter usage location: token request
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Parameter name: refresh_token
   o  Parameter usage location: token request, token response
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

Top      Up      ToC       Page 66 
11.3.  OAuth Authorization Endpoint Response Types Registry

   This specification establishes the OAuth Authorization Endpoint
   Response Types registry.

   Additional response types for use with the authorization endpoint are
   registered with a Specification Required ([RFC5226]) after a two-week
   review period on the oauth-ext-review@ietf.org mailing list, on the
   advice of one or more Designated Experts.  However, to allow for the
   allocation of values prior to publication, the Designated Expert(s)
   may approve registration once they are satisfied that such a
   specification will be published.

   Registration requests must be sent to the oauth-ext-review@ietf.org
   mailing list for review and comment, with an appropriate subject
   (e.g., "Request for response type: example").

   Within the review period, the Designated Expert(s) will either
   approve or deny the registration request, communicating this decision
   to the review list and IANA.  Denials should include an explanation
   and, if applicable, suggestions as to how to make the request
   successful.

   IANA must only accept registry updates from the Designated Expert(s)
   and should direct all requests for registration to the review mailing
   list.

11.3.1.  Registration Template

   Response type name:
      The name requested (e.g., "example").

   Change controller:
      For Standards Track RFCs, state "IETF".  For others, give the name
      of the responsible party.  Other details (e.g., postal address,
      email address, home page URI) may also be included.

   Specification document(s):
      Reference to the document(s) that specify the type, preferably
      including a URI that can be used to retrieve a copy of the
      document(s).  An indication of the relevant sections may also be
      included but is not required.

Top      Up      ToC       Page 67 
11.3.2.  Initial Registry Contents

   The OAuth Authorization Endpoint Response Types registry's initial
   contents are:

   o  Response type name: code
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

   o  Response type name: token
   o  Change controller: IETF
   o  Specification document(s): RFC 6749

11.4.  OAuth Extensions Error Registry

   This specification establishes the OAuth Extensions Error registry.

   Additional error codes used together with other protocol extensions
   (i.e., extension grant types, access token types, or extension
   parameters) are registered with a Specification Required ([RFC5226])
   after a two-week review period on the oauth-ext-review@ietf.org
   mailing list, on the advice of one or more Designated Experts.
   However, to allow for the allocation of values prior to publication,
   the Designated Expert(s) may approve registration once they are
   satisfied that such a specification will be published.

   Registration requests must be sent to the oauth-ext-review@ietf.org
   mailing list for review and comment, with an appropriate subject
   (e.g., "Request for error code: example").

   Within the review period, the Designated Expert(s) will either
   approve or deny the registration request, communicating this decision
   to the review list and IANA.  Denials should include an explanation
   and, if applicable, suggestions as to how to make the request
   successful.

   IANA must only accept registry updates from the Designated Expert(s)
   and should direct all requests for registration to the review mailing
   list.

Top      Up      ToC       Page 68 
11.4.1.  Registration Template

   Error name:
      The name requested (e.g., "example").  Values for the error name
      MUST NOT include characters outside the set %x20-21 / %x23-5B /
      %x5D-7E.

   Error usage location:
      The location(s) where the error can be used.  The possible
      locations are authorization code grant error response
      (Section 4.1.2.1), implicit grant error response
      (Section 4.2.2.1), token error response (Section 5.2), or resource
      access error response (Section 7.2).

   Related protocol extension:
      The name of the extension grant type, access token type, or
      extension parameter that the error code is used in conjunction
      with.

   Change controller:
      For Standards Track RFCs, state "IETF".  For others, give the name
      of the responsible party.  Other details (e.g., postal address,
      email address, home page URI) may also be included.

   Specification document(s):
      Reference to the document(s) that specify the error code,
      preferably including a URI that can be used to retrieve a copy of
      the document(s).  An indication of the relevant sections may also
      be included but is not required.



(page 68 continued on part 4)

Next RFC Part