The OAuth protocol enables websites or applications (Consumers) to access Protected Resources from a web service (Service Provider) via an API, without requiring Users to disclose their Service Provider credentials to the Consumers. An example use case is allowing printing service printer-example.com (the Consumer), to access private photos stored on photos-example.com (the Service Provider) without requiring Users to provide their photos-example.com credentials to printer-example.com.
More generally, OAuth creates a freely-implementable and generic methodology for API authentication, benefitting developers who want their Consumer product to interact with various Service Providers.
OAuth does not require a specific user interface or interaction pattern, nor does it specify how Service Providers authenticate Users, making the protocol ideally suited for cases where authentication credentials are unavailable to the Consumer, such as with OpenID.
OAuth aims to unify the experience and implementation of delegated web service authentication into a single, community-driven protocol. OAuth builds on existing protocols and best practices that have been independently implemented by various websites. An open standard, supported by large and small providers alike, promotes a consistent and trusted experience for both application developers and the users of those applications.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119].
oauth_.OAuth includes a Consumer Key and matching Consumer Secret that together authenticate the Consumer (as opposed to the User) to the Service Provider. Consumer-specific identification allows the Service Provider to vary access levels to Consumers (such as un-throttled API access or other resources).
Service Providers MUST NOT rely on the Consumer Secret as a method to verify the Consumer identity, unless the Consumer Secret is known to be inaccessible to anyone other than the Consumer and the Service Provider.
Consumer Secrets MAY be an empty string when no Consumer verification is needed. Consumer Keys SHOULD NOT be an empty string, but if they are, the Service Provider MUST specify the default Consumer type for such Consumer Keys.
All Endpoint URLs for both Service Providers and Consumers MUST include scheme, authority, and path, and MAY include query and fragment as defined by [RFC 3986] section 3. The Endpoint URL query MUST NOT contain any Protocol Parameter.
Service Providers MUST enable Consumer Developers to establish a Consumer Key and Consumer Secret. The process and requirements for provisioning these are entirely up to the Service Providers.
The Service Provider MUST also provide documentation to specify:
oauth_.The Consumer Developer MUST establish a Consumer Key and a Consumer Secret with the Service Provider.
Consumers are categorized based on their ability to accept incoming HTTP(S) requests. OAuth defines two Consumer types:
When registering a Consumer Key, the Consumer Developer MUST identify the Consumer type (web-based or limited). If the Consumer is web-based, the Consumer Developer MUST provide the Callback Endpoint URL which the Service Provider uses to notify the Consumer when the User grants or denies access.
Protocol Parameters' names and values are case sensitive. Each Protocol Parameter MUST NOT appear more than once per request.
All parameter names and values are escaped using the [RFC 3986] percent-encoding (%xx) mechanism. Characters not in the unreserved character set ([RFC 3986] section 2.3) MUST be encoded. Characters in the unreserved character set MUST NOT be encoded. Hexadecimal characters in encodings MUST be upper case. Text names and values MUST be encoded as UTF-8 octets before percent-encoding them per [RFC 3629].
Protocol Parameters are sent from the Consumer to the Service Provider in one of two methods:
Authorization header as defined in "Using HTTP-Authorization Headers".Response parameters are sent by the Service Provider to return Tokens and other information to the Consumer in the HTTP response body. The parameters are first encoded and then sent as a sequence of lines. Each line begins with a parameter name, followed by an = character (ASCII code 61), and the parameter value. The line is terminated by a single newline character (ASCII code 10). Additional characters, including whitespace, MUST NOT be added before or after the = or newline characters.
This section defines an [RFC 2617] extension to support OAuth. It uses the standard HTTP Authorization and WWW-Authenticate headers to pass Protocol Parameters rather than using URL parameters.
It is RECOMMENDED that Service Providers accept the HTTP Authorization header. For the remainder of this section, we assume that the Service Provider has chosen to support this extension. Consumers SHOULD be able to supply an OAuth Authorization header as an alternative to passing URL parameters.
The extension auth-scheme (as defined by [RFC 2617]) is OAuth and is case-insensitive.
When using an HTTP Authorization header, the Protocol Parameters are not included in the request URL. Rather they are included as the value of the header. Parameters are included in the header the following way:
= character (ASCII code 61), a " character (ASCII code 34), the parameter value (MAY be empty), and another " character (ASCII code 34).For example:
Authorization: OAuth oauth_token="540ad18" oauth_consumer_key="0685bd91" oauth_signature_method="PLAINTEXT" oauth_signature="2d047740b53,bb5c2a0f398f30"
Consumers MAY also include an OAuth Authorization header without any parameters on any HTTP request to inform a Service Provider they support OAuth. The Service Provider MUST then respond with the appropriate WWW-Authenticate header for the requested resource in the response. For example, a Consumer could inquire using HEAD and then adjust its user interface if the Service Provider supports OAuth.
Service Providers MUST indicate their support for the extension by returning the OAuth HTTP WWW-Authenticate header upon all API Endpoint URL requests for Protected Resources.
Such a response MUST include at least one OAuth HTTP WWW-Authenticate header and MAY include additional HTTP WWW-Authenticate headers:
WWW-Authenticate: OAuth realm="https://sp.example.com/oauth/authorize"
The realm parameter defines a protection realm per [RFC 2617], section 1.2. The parameter MAY specify the Authorization Endpoint URL to be used by the Consumer to obtain authorization for the accessed resource.
OAuth authentication is the process in which Users grant access to their Protected Resources without sharing their credentials with the Consumer. OAuth uses Tokens generated by the Service Provider instead of the User’s credentials in API requests. The process uses two Token types:
OAuth Authentication is done in two broad steps. First, the Consumer obtains an authorized Request Token. Second, the Consumer exchanges the Request Token for an Access Token. Only the Access Token SHALL be used to access the Protect Resources.
Service Providers SHOULD be prepare to handle the case in which Consumers fail to use the Request Token (to request User access grant or exchange it for an Access Token).
The Consumer obtains an authorized Request Token by asking the Service Provider to issue a Token, and having the User to authorize it. The Request Token’s sole purpose is to receive User approval and can only be used to obtain an Access Token. The Request Token process goes as follows:
To obtain a Request Token, the Consumer sends an HTTP GET request to the Service Provider's API Endpoint URL for Request Token requests. The request MUST be signed per "Signing API Requests", and contains the following parameters:
oauth_consumer_key
: The Consumer Key.oauth_signature_method
: The signature method the Consumer used to sign the request.oauth_signature
: The signature as defined in "Signing API Requests".oauth_version
: OPTIONAL. If present, value MUST be 1.0. Service Providers MUST assume the protocol version to be 1.0 if this parameter is not present. Service Providers’ response to non-1.0 value is left undefined.The Service Provider verifies the Consumer Key and if successful, generates a Request Token and Token Secret and returns them to the Consumer in the HTTP response body as defined in "Response Parameters". The Service Provider MUST ensure the Request Token cannot be exchanged for an Access Token until the User successfully grants access in step 4 below.
The response contains the following parameters:
oauth_token
: The Request Token.oauth_token_secret
: The Token Secret.If the request fails verification or is rejected for other reasons, the Service Provider MUST respond with the appropriate response code as defined in "HTTP Response Codes". The Service Provider MAY include some further details about why the request was rejected in the HTTP response body as defined in "Response Parameters".
In order for the Consumer to be able to exchange the Request Token for an Access Token, the Consumer MUST obtain approval from the User by directing the User to the Service Provider. The Consumer constructs an HTTP GET request to the Service Provider's Authorization Endpoint URL with the following parameter:
oauth_token
: OPTIONAL. The Request Token obtained in the previous step. The Service Provider MAY declare this parameter as REQUIRED, or accept requests to the Authorization Endpoint URL without it, in which case it will prompt the User to enter it manually.oauth_state
: OPTIONAL. This parameter will be returned unmodified to the Consumer. This parameter is only available to web-based Consumers, and SHOULD only be used in the case of stateless Consumers. The value is returned via the Callback Endpoint URL.Once the request URL has been constructed the Consumer redirects the User to the URL via the User's web browser. If the Consumer is incapable of automatic HTTP redirection, the Consumer SHALL notify the User how to manually go to the constructed request URL.
Note: If a Service Provider knows a Consumer to be running on a mobile device or set-top box, the Service Provider SHOULD ensure that the Authorization Endpoint URL and Request Token are suitable for manual entry.
The Service Provider verifies the User's identity and asks for consent as detailed. OAuth does not specify how the Service Provider authenticates the User. However, it does define a set of REQUIRED steps:
When displaying any identifying information about the Consumer to the User based on the Consumer Key, the Service Provider MUST inform the User if it is unable to assure the Consumer’s true identity. The method in which the Service Provider informs the User and the quality of the identity assurance is beyond the scope of this specification.
For example, the Consumer Key and Consumer Secret of a desktop application running on a User desktop can be extracted and abused, while a Consumer Key and Consumer Secret stored on a web server behind a firewall can be assumed safe.
After the User authenticates with the Service Provider and grants permission for Consumer access, the Consumer MUST be notified that the Request Token has been authorized and ready to be exchanged for an Access Token. If the User denies access, the Consumer MAY be notified that the Request Token has been revoked.
The Consumer notification method is based on the Consumer type as follows:
The Service Provider constructs an HTTP GET request to the Consumer's Callback Endpoint URL with the following parameters:
oauth_token
: The Request Token the User authorized or denied.oauth_result
: true if the User grants access, false if the User denies access.oauth_state
: REQUIRED if one was provided in the Consumer step 3.Once the request URL has been constructed the Service Provider redirects the User to the URL via the User's web browser.
The Service Provider instructs the User to inform the Consumer that authorization has completed. Since Limited Consumers cannot accept incoming HTTP(S) requests, the User will need to manually notify the Consumer when they are done.
The Service Provider MAY include two machine-readable tags in its human-readable instructions to the User. If included, both tags MUST be added in the
element of the HTML document:<meta name="oauth_result" content="true" />
<meta name="oauth_token" content="request_token" />
In the oauth_result tag, the content attribute indicates whether access was granted, true if the User grants access, false if the User denies access. In the oauth_token tag, the content attributes is the Request Token approved or denied.
Obtaining an Access Token follows the same process for all Consumer types:
The Request Token and Token Secret MUST be exchanged for an Access Token and Token Secret.
To request as Access Token, the Consumer makes an HTTP request to Service Provider API Endpoint URL for Token exchange. The Service Provider documentation MUST specify either HTTP GET or POST for this endpoint. It is RECOMMENDED that this be a POST request. The request MUST be signed per "Signing API Requests".
The request contains the following parameters:
oauth_consumer_key
: The Consumer Key.oauth_token
: The Request Token obtained previously.oauth_signature_method
: The signature method the Consumer used to sign the request.oauth_signature
: The signature as defined in "Signing API Requests".No additional Service Provider specific parameters are allowed when requesting an Access Token to ensure all Token related information is present prior to seeking User approval.
The Service Provider exchanges the Consumer's Authorization for a new Access Token and Token Secret. The Service Provider MUST verify that:
On successful verification, the Service Provider returns an Access Token and a Token Secret in the HTTP response body as defined in "Response Parameters". The Access Token and Token Secret are stored by the Consumer to use when signing future API requests.
The response contains the following parameters:
oauth_token
: The Access Token.oauth_token_secret
: The Token Secret.If the request fails verification or is rejected for other reasons, the Service Provider MUST respond with the appropriate response code as defined in "HTTP Response Codes". The Service Provider MAY include some further details about why the request was rejected in the HTTP response body as defined in "Response Parameters".
After successfully receiving the Access Token and Token Secret, the Consumer is able to access the Protected Resources on behalf of the User.
The request contains the following parameters:
oauth_consumer_key
: The Consumer Key.oauth_token
: The Access Token.oauth_signature_method
: The signature method the Consumer used to sign the request.oauth_signature
: The signature as defined in "Signing API Requests".The purpose of signing API requests is to prevent unauthorized parties from using the Consumer Key and Tokens when making API Endpoint URL requests. The signature process encodes the Consumer Secret and Token Secret into a verifiable value which is included with the request.
OAuth does not require a particular signature method, as each API implementation can have its own unique requirements. The protocol defines three signature methods: PLAINTEXT, HMAC-SHA1, and RSA-SHA1, but Service Providers are free to implement and document their own methods. Recommending any particular method is beyond the scope of this specification.
All API Endpoint URL requests MUST be signed by the Consumer and verified by the Service Provider. Both the Consumer and Service Provider follow the same process to generate the request signature.
The Consumer declares a signature method in the oauth_signature_method parameter, and generates a signature which is included in the oauth_signature parameter. The Service Provider verifies the request by generating a new request signature based on the Consumer specified method, and compares it to the signature provided by the Consumer.
The signature process MUST NOT change the request parameter names or values. It is a read-only process on the request. All request parameters MUST be encoded as described in "Parameter Encoding" prior to applying the signature process.
The PLAINTEXT method does not provide any security protection and SHOULD be used over a secure channel such as HTTPS. The signature Protocol Parameters are set with the following values unencrypted:
oauth_signature_method
: Set to PLAINTEXT.oauth_signature
: Set to the concatenated encoded value of the oauth_consumer_secret parameter and the value of the oauth_token_secret parameter. If the values contain a . character (ASCII code 46), it must be encoded as %2E. The values are separated by a . character (ASCII code 46), even if empty. The result MUST not be encoded again.For example, if the Consumer Key is dj.9rj$0jd78jf88 and Token Secret is jjd999(j88ui.hs3, the encoded values are:
dj%2E9rj%240jd78jf88jjd999%28j88ui%2Ehs3And the oauth_signature value is dj%2E9rj%240jd78jf88.jjd999%28j88ui%2Ehs3. This value is not encoded anymore and is used as it in the HTTP request. If the Token Secret is empty, the value is dj%2E9rj%240jd78jf88. (the separator . is retained).
The HMAC-SHA1 method includes the following steps:
All non-Protocol Parameters SHALL be normalized before used for signing. If a request Endpoint contains a query, it is broken into individual parameters which are treated like any other non-Protocol Parameter. The parameters are normalized into a single string as follows:
a=1, c=hi%20there, f=25, f=50, z=10.= character (ASCII code 61), even if the value is empty. Each name-value pair is separated by an & character (ASCII code 38). For example: a=1&c=hi%20there&f=25&f=50&z=10.A nonce is a random string, uniquely generated for each request. The nonce allows the Service Provider to verify that a request has never been made before and helps prevent replay attacks when requests are made over a non-secure channel (such as HTTP).
The Consumer SHALL first calculate the request timestamp expressed in the number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value MUST be equal or greater than the timestamp used in previous requests. The Consumer SHALL then generate a Nonce values that is unique for each request with the same timestamp value.
When verifying a Consumer signature, the Service Provider SHOULD check the request nonce to ensure it has not been used in a previous Consumer request. Since the nonce is unique per timestamp, and timestamps are always equal or greater, the Service Provider only needs to keep track of nonces with the most up-to-date timestamps. Service Providers May also skip checking the nonce in Consumer requests for Access Token, as the Request Token can only be used once already.
The Protocol Parameters and values generated in the previous two steps are concatenated into a single string used as the input to the signature algorithm. The request parameters MUST be concatenated in the following order:
oauth_consumer_key.oauth_token.oauth_token_secret.HEAD, GET, POST, etc.The above request parameters and generated values are concatenated in order into a single string. Each signature item is separated by an & character (ASCII code 38), even if empty.
The HMAC-SHA1 value of the concatenated string from step 3 (concatenated_string) is calculated using the Consumer Secret (oauth_consumer_secret, not encoded) as defined in [RFC 2104]:
hmac_sha1(oauth_consumer_secret, concatenated_string)
The calculated value is used in HEX string format.
The signature Protocol Parameters are set with the following values:
oauth_signature_method
: Set to HMAC-SHA1.oauth_signature
: Set to the concatenated encoded values of the timestamp from step 2, the nonce from step 2, and the calculated HMAC from step 4. Each value is separated by an . character (ASCII code 46). If the values contain a . character (ASCII code 46), it must be encoded as %2E. The result MUST not be encoded again.The RSA-SHA1 signature method requires the Consumer to establish a public key pair with the Service Provider. The Consumer MUST retain the private key part (private_key) while the Service provider MUST retain the public key part (public_key). The process and requirements for establishing the public key are left to the Service Provider.
The RSA-SHA1 method includes the following steps:
Follow steps 1-3 of the HMAC-SHA1 signature method.
The Consumer signed the concatenated string from step 1 (concatenated_string) using:
RSA_sign(SHA1, private_key, concatenated_string)
The Service Provider verifies the Consumer signature of the concatenated string from step 1 (concatenated_string) using:
RSA_verify(SHA1, public_key, concatenated_string)
oauth_signature_method
: Set to RSA-SHA1.oauth_signature
: Set to the concatenated encoded values of the timestamp from step 1, the nonce from step 1, and the RSA signature from step 2. Each value is separated by an . character (ASCII code 46). If the values contain a . character (ASCII code 46), it must be encoded as %2E. The result MUST not be encoded again.The Service Provider MUST respond with HTTP 200 OK for all successful Consumer requests. When the Service Provider rejects a Consumer API Endpoint URL request, it MUST respond with HTTP 400 Bad Request or HTTP 401 Unauthorized.
HTTP 400 Bad Request
HTTP 401 Unauthorized
In this example, the Service Provider photos-example.com is a photo sharing website, and the Consumer printer-example.com is a photo printing website. Jane, the User, would like printer-example.com to print the private photo vacation.jpg stored at photos-example.com.
When Jane signs-into photos-example.com using her username and password, she can access the photo by going to the URL http://photos-example.com/file=vacation.jpg. Other Users cannot access that photo, and Jane does not want to share her username and password with printer-example.com.
The Service Provider documentation explains how to register for a Consumer Key and Consumer Secret, and declares the following Endpoint URLs:
file and optional parameter sizeThe Service Provider declares support for the HMAC-SHA1 signature method for all requests, and PLAINTEXT only for secure (HTTPS) requests.
The Consumer printer-example.com already established a Consumer Key and Consumer Secret (as a web-based Consumer) with photos-example.com and advertizes its printing services for photos stored on photos-example.com. The Consumer registration is:
dpf43:3p2l4k3l03kd94hf93k#23kf44http://printer-example.com/request_token_readyAfter Jane informs printer-example.com that she would like to print her vacation photo at photos-example.com, the printer website tries to access the photo and receives HTTP 401 Unauthorized. The Consumer send the following HTTP GET request to the Service Provider:
https://photos-example.com/request_token?oauth_consumer_key=dpf43 %3A3p2l4k3l03&oauth_signature_method=PLAINTEXT&oauth_signature=kd94hf93k%2323kf44.&oauth_version=1.0
The Service Provider checks the signature and replies with an unauthorized Request Token in the body of the HTTP response:
oauth_token=hh%5Ds93j4hdidpola
oauth_token_secret=hdhd0%2F44k9j7ao03
The Consumer redirects Jane’s browser to the Service Provider Authorization Endpoint URL to obtain Jane’s approval for accessing her private photos.
http://photos-example.com/authorize?oauth_token=hh%5Ds93j4hdidpola
The Service Provider asks Jane to sign-in using her username and password and if successful, asks her if she approves granting printer-example.com access to her private photos. If Jane approves the request, the Service Provider redirects her back to the Consumer’s Callback Endpoint URL:
http://printer-example.com/request_token_ready?oauth_token=hh%5Ds93j4hdidpola&oauth_result=true
Now that the Consumer knows Jane approved the Request Token, it asks the Service Provider to exchange it for an Access Token:
https://photos-example.com/access_token?oauth_consumer_key=dpf43 %3A3p2l4k3l03&oauth_token=hh%5Ds93j4hdidpola&oauth_signature_method=PLAINTEXT&oauth_signature=kd94hf93k%2323kf44.hdhd0%2F44k9j7ao03&oauth_version=1.0
The Service Provider checks the signature and replies with an Access Token in the body of the HTTP response:
oauth_token=nnch73%40d00sl2jdk
oauth_token_secret=%2B%24kkdhi9sl%28r.s00
The Consumer is now ready to request the private photo. Since the photo API Endpoint URL is not secure (HTTP), it must use HMAC-SHA1. To generate the signature, the following inputs are used:
oauth_consumer_key
: dpf43:3p2l4k3l03kd94hf93k#23kf44oauth_token
: nnch73@d00sl2jdkoauth_token_secret
: +$kkdhi9sl(r.s00GEThttp://photos-example.com/file%3Dvacation.jpg%2Csize%3Doriginal11912420968392048:97482910The concatenated string is:
dpf43%3A3p2l4k3l03&kd94hf93k%2323kf44& nnch73%40d00sl2jdk& %2B%24kkdhi9sl%28r.s00&GET&http%3A%2F%2Fphotos-example.com%2F&file%3Dvacation.jpg%2Csize%3Doriginal&&1191242096&8392048%3A97482910
Using HMAC-SHA1 with the concatenated string and Consumer Secret the hash value in HEX string is:
3443483bd0365b9985c038220ef65b4d230afcf6
The oauth_signature is constructed from the timestamp, encoded nonce, and hash value, period-seperated:
1191242096.8392048%3A97482910.3443483bd0365b9985c038220ef65b4d230afcf6
All together, the Consumer request for the photo is:
http://photos-example.com/file=vacation.jpg&size=original&oauth_consumer_key=dpf43%3A3p2l4k3l03&oauth_token=nnch73%40d00sl2jdk&oauth_signature_method=HMAC-SHA1&oauth_signature=1191242096.8392048%3A97482910.3443483bd0365b9985c038220ef65b4d230afcf6
If the Service Provider supports the HTTP Authorization Headers extension, the Consumer can make the following request instead:
http://photos-example.com/file=vacation.jpg&size=original
Authorization: OAuth oauth_consumer_key="dpf43%3A3p2l4k3l03" oauth_token="nnch73%40d00sl2jdk" oauth_signature_method="HMAC-SHA1" oauth_signature="1191242096.8392048%3A97482910.3443483bd0365b9985c038220ef65b4d230afcf6"
To which photos-example.com responds (after checking the signature) with the requested photo.