Skip to content

AUTHORIZATION Header

Clemens Lode edited this page Sep 1, 2015 · 4 revisions

Introduction

Many requests demand the existence of an Authorization Header in the HTTP Header of a request. The following sections describe how to build and sign the header with a secret. The most important steps are:

  • Gather request method (GET, POST)
  • Compile the JSON string with the data if needed (e.g. for POST requests)
  • Gather POST data (e.g. the JSON string with the data if needed)
  • Gather OAuth parameters (secrets, tokens, timestamp, nonce etc.)
  • Gather GET parameters (max, start, date_since etc.)
  • Sort parameters alphabetically and URLencode them
  • URLencode POST data (if needed)
  • Compile Request URL and URLencode it
  • Concatenate all elements
  • Calculate signature (HMAC-SHA256, Base64)
  • Construct Authorization Header out of OAuth parameters and signature
  • Construct HTTP Request out of Authorization header (and POST data if needed)

HTTP Request

  • All HTTP requests with an Authorization Header need to be
    • single-part
    • Content-Type: application/x-www-form-urlencoded
    • Content-Type: application/json;charset=utf-8 (for JSON array calls)
  • Parameter names and values are case sensitive
  • Parameters must not appear more than once per request
  • All parameters are required unless otherwise noted

Nonce and Timestamp

  • The oauth_nonce in combination with the oauth_timestamp allows VitaDock Online to verify that a request has never been made before and helps prevent replay attacks.
  • A oauth_nonce is a random string (36 characters, e.g. a UUID), uniquely generated for each request.
  • The oauth_timestamp is expressed in the number of milliseconds since January 1, 1970 00:00:00 UTC.
  • The oauth_timestamp value MUST be a positive integer and MUST be equal or greater than the oauth_timestamp used in previous requests.
  • For each request the Consumer must generate a nonce value that is unique in combination with that oauth_timestamp.

Encoding

  • Hexadecimal characters in encodings must be upper case
  • Text names and values must be encoded as UTF-8 octets before percent-encoding them per RFC3629
  • All characters except ([A-Z,a-z,0-9,’-‘,’.’,’_’,’~’]) must be encoded

Please note that there are existing libraries that do the encoding (e.g. java.net.URLEncoder) but that their implementations might differ. For example some libraries do not encode apostrophe (‘) into %27. E.g. “I’m sick” needs to be encoded into “I%27m+sick”. Please note that for oauth_version 1.0, we use '+' as encoding for space. This is fixed in other versions (%20).

Base Parameter String**

The parameters are normalized into a single string as follows:

  • HTTP GET parameters are sorted by name, using lexicographical byte value ordering
  • All parameters are concatenated in their sorted order into a single string.
  • For each parameter, the name is separated from the corresponding value by an ‘=’ character (ASCII code 61), even if the value is empty.
  • Each name-value pair is separated by an ‘&’ character (ASCII code 38).

The following parameters are used (ordered alphabetically!):

  • date_since (optional, for loading/syncing entries)
  • id (for changing entries)
  • max (optional, for loading/syncing entries)
  • oauth_consumer_key (Application Token or Device Token respectively)
  • oauth_nonce
  • oauth_signature_method
  • oauth_timestamp
  • oauth_token (Unauthorized Access Token or Access Token respectively)
  • oauth_verifier (Verifier Token for Request Access POSTs)
  • oauth_version (1.0)
  • start (optional, for loading/syncing entries)

Finally the string is encoded (see above).

Request URL

  • The URL used in the Signature Base String MUST include the scheme, authority, and path, and MUST exclude the query and fragment as defined by [RFC3986] section 3.
  • The URL scheme and authority MUST be lowercase and include the port number; http default port 80 and https default port 443 MUST be excluded.
  • Finally the string is URL encoded

Example: The request https://cloud.vitadock.com/data/thermodocks/sync?max=100&date_since=0 would be included in the Signature Base String as https%3A%2F%2Fcloud.vitadock.com%2Fdata%2Fthermodocks%2Fsync

Signature Base String

The following items MUST be concatenated in order into a single string. Each item is separated by an ‘&’ character (ASCII code 38), even if empty:

  • The HTTP request method used to send the request. The value MUST be uppercase, i.e. “GET” or “POST”.
  • The encoded request URL
  • The base parameter string

Signature

The oauth_signature is constructed from the Signature Base String and encrypted using strings only known to the Consumer and VitaDock Online (the secrets) as follows:

  • The oauth_signature is calculated using the HMAC-SHA256 signature method (as defined in RFC2104).
    • text: Base Signature String
    • key: Concatenated values (each first encoded per parameter encoding) of the _Application Secret _(or the Device Secret respectively) and the (Unauthorized) Access Secret, separated by an ‘&’ character (ASCII code 38)
    • For Unauthorized Access Token request calls (i.e. for calls where there is no (Unauthorized) Access Token available yet) the secret string consists of the Application Secret (or the Device Secret respectively) ending with a ‘&’ character (ASCII code 38)
    • oauth_signature is set to the calculated digest octet string, base64-encoded per RFC2045, then URL-encoded (see above).

Authorization Header

  • Finally all values need to be put into the OAuth Authorization header.
  • The Authorization header has to start with “OAuth” and has to be put into a HTTP header variable called "Authorization"
  • For each parameter, the name is immediately followed by an ‘=’ character (ASCII code 61), a ‘"’ character (ASCII code 34), the parameter value (MAY be empty), and another ‘"’ character (ASCII code 34).
  • Parameters are separated by a comma character (ASCII code 44) and OPTIONAL linear whitespace per [RFC2617].
  • Other parameters (e.g. GET parameters) MUST NOT be used the HTTP Authorization header (they are used for the signature calculation, though)

Example (data storage) with encoding

Example data

  • oauth_consumer_key: wqR6Tu245t1VVPViJTJGvcf2AkW3G06niYsn655AG3umZS3s6E6fAXvSkiEhrYTm
  • Application secret: WSc3hplyunPa4SgLncJFKthZWZTdsJy4uZFXEgJ308GCnZq3eY1xGeJVJWUePGhp
  • oauth_token: K8evlEFc0W3PntZfuF23Jx9tB8qc0u5q6yztX0Xq4n5irDsxbwAvdyv0TxjZ0A3S
  • oauth_token_secret: V7yPZ3JLLGqsTsBBGrxkSwpbMkZ1pnKP0rmzxkEhkZ3d4n0Pkvofux9XDqFE5V8J
  • oauth_nonce: k4VdSylUXSZs4OCsOGlaazDTte89Jkwg3Mzw
  • oauth_timestamp: 1355927338155
  • JSON data: [{"activityStatus":1,"bodyTemperature":36.8,"bodyTemperatureTargetMax":37.8,"bodyTemperatureTargetMin":35.9,"id":null,"measurementDate":1355840936967,"moduleSerialId":"[Autogenerated Item]","mood":0,"note":""},{"activityStatus":1,"bodyTemperature":36.91555,"bodyTemperatureTargetMax":37.8,"bodyTemperatureTargetMin":35.9,"id":null,"measurementDate":1355927336968,"moduleSerialId":"[Autogenerated Item]","mood":1,"note":""}]

Base Parameter String (before encoding)

oauth_consumer_key=wqR6Tu245t1VVPViJTJGvcf2AkW3G06niYsn655AG3umZS3s6E6fAXvSkiEhrYTm&oauth_nonce=k4VdSylUXSZs4OCsOGlaazDTte89Jkwg3Mzw&oauth_signature_method=HMAC-SHA256&oauth_timestamp=1355927338155&oauth_token=K8evlEFc0W3PntZfuF23Jx9tB8qc0u5q6yztX0Xq4n5irDsxbwAvdyv0TxjZ0A3S&oauth_version=1.0&[{"activityStatus":1,"bodyTemperature":36.8,"bodyTemperatureTargetMax":37.8,"bodyTemperatureTargetMin":35.9,"id":null,"measurementDate":1355840936967,"moduleSerialId":"[Autogenerated Item]","mood":0,"note":""},{"activityStatus":1,"bodyTemperature":36.91555,"bodyTemperatureTargetMax":37.8,"bodyTemperatureTargetMin":35.9,"id":null,"measurementDate":1355927336968,"moduleSerialId":"[Autogenerated Item]","mood":1,"note":""}]

Base Signature String

POST&https%3A%2F%2Fcloud.vitadock.com%2Fdata%2Fthermodocks%2Farray&oauth_consumer_key%3DwqR6Tu245t1VVPViJTJGvcf2AkW3G06niYsn655AG3umZS3s6E6fAXvSkiEhrYTm%26oauth_nonce%3Dk4VdSylUXSZs4OCsOGlaazDTte89Jkwg3Mzw%26oauth_signature_method%3DHMAC-SHA256%26oauth_timestamp%3D1355927338155%26oauth_token%3DK8evlEFc0W3PntZfuF23Jx9tB8qc0u5q6yztX0Xq4n5irDsxbwAvdyv0TxjZ0A3S%26oauth_version%3D1.0%26%5B%7B%22activityStatus%22%3A1%2C%22bodyTemperature%22%3A36.8%2C%22bodyTemperatureTargetMax%22%3A37.8%2C%22bodyTemperatureTargetMin%22%3A35.9%2C%22id%22%3Anull%2C%22measurementDate%22%3A1355840936967%2C%22moduleSerialId%22%3A%22%5BAutogenerated+Item%5D%22%2C%22mood%22%3A0%2C%22note%22%3A%22%22%7D%2C%7B%22activityStatus%22%3A1%2C%22bodyTemperature%22%3A36.91555%2C%22bodyTemperatureTargetMax%22%3A37.8%2C%22bodyTemperatureTargetMin%22%3A35.9%2C%22id%22%3Anull%2C%22measurementDate%22%3A1355927336968%2C%22moduleSerialId%22%3A%22%5BAutogenerated+Item%5D%22%2C%22mood%22%3A1%2C%22note%22%3A%22%22%7D%5D

HTTP Request

Request POST URL: https://cloud.vitadock.com/data/thermodocks/array

Authorization : OAuth oauth_consumer_key="wqR6Tu245t1VVPViJTJGvcf2AkW3G06niYsn655AG3umZS3s6E6fAXvSkiEhrYTm",oauth_signature_method="HMAC-SHA256",oauth_timestamp="1355927338155",oauth_nonce="k4VdSylUXSZs4OCsOGlaazDTte89Jkwg3Mzw",oauth_token="K8evlEFc0W3PntZfuF23Jx9tB8qc0u5q6yztX0Xq4n5irDsxbwAvdyv0TxjZ0A3S",oauth_version="1.0",oauth_signature="z0OnBosGbIa0pnO2cCFw2%2BgZF2bIhkCWEmggnazDzQU%3D"
Content-Type : application/json;charset=utf-8

Response: ["487d252e-d60c-4e3f-ac49-e350ed175160","15fab1f9-4c78-444d-953f-23c33dee7838"]
Clone this wiki locally
You can’t perform that action at this time.