Beginner’s Guide to OAuth – Part IV: Signing Requests
Time to put the previously discussed concepts into action. The following explanation is designed as an interactive walkthrough with customizable inputs. Next to each set of inputs you will find an expand [+] icon allowing you to change the example and see how such changes affect the intermediate and final results. To expand the forms, click on the [+] icons which will open the form or click again to collapse. Making changes to the pre-filled values will immediately change the walkthrough content. You can also adjust the default values the example starts with by choosing from one of the pre-configured use cases. This post cannot be viewed in a feed reader.
In the following walkthrough, the Consumer would like to access a Protect Resource located at + . The Consumer has previously registered with the Service Provider and obtained the Consumer Key and Consumer Secret . It has executed the OAuth workflow and obtained a Token and Token Secret + . To sign the request, the Consumer is using the signature method + , and generated a nonce string and timestamp + .
The OAuth information such as Consumer Key and Token is included in the request using special OAuth Parameters starting with the 'oauth_' prefix, most of which are mandatory. OAuth does not allow any other parameter to use the 'oauth_' prefix.
The PLAINTEXT signature method was explicitly design to be used over secure channels, which allows the secrets to be transmitted in plain text with each request without the risk of being captured and exploited. Unlike the other two signature methods, PLAINTEXT does not require the construction of the Signature Base String. Instead, it sets the signature value to the concatenated UTF-8-encoded and URL-encoded values of the Consumer Secret and Token Secret, separated by an ‘&’ character, even if either secret is empty (per section 9.4.1):
The OAuth Parameters and request parameters are collected together in their raw, pre-encoded form. The parameters are collected from three locations: the URL query element (as defined by RFC 3986 section 3), the OAuth 'Authorization' header (excluding the 'realm' parameter), and parameters included in a single-part 'application/x-www-form-urlencoded' POST body (as defined by HTML4). The parameter locations are more relevant to the Service Provider as it needs to extract them from the incoming Consumer request. The Consumer should have all the parameters in their separated and pre-encoded form as it builds the request.
All text parameters are UTF-8 encoded (per section 5.1). Binary data is not directly handled by the OAuth specification but is assumed to be stored in an 8bit array which is not UTF-8 encoded. This step may not have any effect if the parameters are only using the ASCII character set.
After UTF-8 encoding, the parameters are URL-encoded (per section 5.1) in a specific way that is often not fully compatible with existing URL-encoding libraries. Developers should check the details of their libraries to ensure full compliance. Throughout the specification, great effort has been made to reuse as much existing code as possible but when variation in implementation were found, the specification provides detailed instructions to avoid interoperability issues. All the unreserved characters (letters, numbers, '-', '_', '.', '~') must not be encoded, while all other characters are encoded using the %XX format where XX is an uppercase representation of the character hexadecimal value:
The parameters are sorted (per section 9.1.1) first based on their encoded names, and if equal, based on their encoded values. Sort order is lexicographical byte value ordering which is the default string sort method in most languages, and means comparing the byte value of each character and sorting in an ascending order (which results in a case sensitive sort). It is important not to try and perform the sort operation on some combined string of both name and value as some known separators (such as '=') will cause the sort order to change due to their impact on the string value.
Once encoded and sorted, the parameters are concatenated together into a single string. Each parameter's name is separated from the corresponding value by an ‘=’ character (even if the value is empty), and each name-value pair is separated by an ‘&’ character (per section 9.1.1). This method is similar to how HTML form data is encoded in 'application/x-www-form-urlencoded' but due to the specific encoding and sorting requirements, is often not fully compatible with existing libraries.
After the parameters have been normalized, the other request elements are processed. While the web is built on URLs, the HTTP protocol uses the data in pieces. URLs are constructed from various elements, and take the general form of scheme://authority:port/path?query#fragment (RFC 3986 defines the authority as both host name and port but for simplicity, this tutorial will define them separately). The scheme and port are used to establish the desired connection, the authority is used in the 'Host' header and to connect to the Service Provider, and the path and query parts are used in the request itself (the fragment is used locally by the browser and is not transmitted with the request).
The request URL is normalized (per section 9.1.2) as scheme://authority:port/path as the query is already included in the list of parameters and the fragment is excluded. The scheme and authority must be in lowercase, and the port must be present except for the default HTTP(S) ports which must be omitted ('80' is omitted when the scheme is 'http' and '443' is omitted when the scheme is 'https'). The path must retain its case as some platforms are case-sensitive. The HTTP request should include the 'Host' header with the exact same host name used to create the normalized URL string. Developers should verify with the Service Provider that it does not require any special handling of the URL.
To complete the creation of the Signature Base String — the input to the signature algorithm — all the request pieces must be put together into a single string. The HTTP method (such as GET, POST, etc.) swhich is a critical part of HTTP requests is concatenated together with the normalized URL and normalized parameters. The HTTP method must be in uppercase and each of these three pieces is URL-encoded (as defined above) and separated by an '&' (per section 9.1.3). For this request, the Signature Base String is:
The HMAC-SHA1 signature method uses the two secrets — Consumer Secret and Token Secret — as the HMAC-SHA1 algorithm key. To construct the key, each secret is UTF8-encoded, URL-encoded, and concatenated into a single string using an '&' character as separator even if either secret is empty (per section 9.2). Libraries should not assume the secrets are in plain ASCII text and ensure proper UTF-8-encoding and URL-encoding prior to concatenation.
With the Signature Base String as the HMAC-SHA1 text and concatenated secrets as key, the Consumer generates the signature (per section 9.2.1). The HMAC-SHA1 algorithm will generate an octet string as the result. The octet string must be base64-encoded with '=' padding (per RFC 2045 section 6.8):
The RSA-SHA1 signature method uses the RSA Private Key to sign the value of the Signature Base String by the Consumer and uses the RSA Public Key to verify the authenticity of the signature by the Service Provider. The Signature Base String is signed using the S = RSASSA-PKCS1-V1_5-SIGN (K, M) algorithm (per RFC 3447 section 8.2.1), where K is the Consumer’s RSA private key, M the Signature Base String, and S is the result signature. The RSA-SHA1 algorithm will generate an octet string as the result. The octet string must be base64-encoded with '=' padding (per RFC 2045 section 6.8):
The calculated signature is added to the request using the 'oauth_signature' parameter. When the signature is verified by the Service Provider, this parameter is not included in the signature workflow as it was not part of the Signature Base String signed by the Consumer. When the signature is included in the HTTP request, it must be properly encoded as required by the method used to transmit the parameters.
OAuth does not directly specify how the request itself should be made and how the parameters should be delivered. But since it explicitly defines which parameters are included in the signature for verification by the Service Provider, it implicitly defines where parameters should be included in the request. OAuth Parameters can be included in either one (even simultaneously) of three locations: the URL query element (as defined by RFC 3986 section 3), the OAuth 'Authorization' header (per section 5.4.1), or in a single-part 'application/x-www-form-urlencoded' POST body (as defined by HTML4). Signed non-OAuth Parameters can be included in one or both of these locations: the URL query element or in a single-part 'application/x-www-form-urlencoded' POST body. It is highly recommended that whenever possible, the OAuth Parameters be included in the OAuth 'Authorization' header and that no other parameters will be included in that header.
Using the URL query element for the non-OAuth Parameters and the OAuth 'Authorization' header for the OAuth Parameters, the OAuth-signed HTTP request is as follows:
Posted at 04:28:32 PM in OAuth
