DMDS APISection: Help: Signing and Authenticating REST RequestsTopics
IntroAuthentication is the process of proving your identity to the system. Identity is an important factor in DMDS API access control decisions. Requests are allowed or denied in part based on the identity of the requester. As a developer, you'll be making requests that invoke these privileges so you'll need to prove your identity to the system by authenticating your requests. This section shows you how. The DMDS REST API uses a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. To authenticate a request, you first concatenate selected elements of the request to form a string. You then use your DMDS Secret Access Key to calculate the HMAC of that string. Informally, we call this process "signing the request," and we call the output of the HMAC algorithm the "signature" because it simulates the security properties of a real signature. Finally, you add this signature as a parameter of the request, using the syntax described in this section. When the system receives an authenticated request, it fetches the DMDS Secret Access Key that you claim to have, and uses it in the same way to compute a "signature" for the message it received. It then compares the signature it calculated against the signature presented by the requester. If the two signatures match, then the system concludes that the requester must have access to the DMDS Secret Access Key, and therefore acts with the authority of the principal to whom the key was issued. If the two signatures do not match, the request is dropped and the system responds with an error message. Example Authenticated DMDS REST API RequestGET /api/v1/orders/12345 HTTP/1.1 Host: api.dmds.com x-dmds-date: 2012-01-01T18:01:31 Authorization: DMDS-API E018F632-5D05-4068-A5E7-11F3161F1AD2:frJIUN8DYpKDtOLCwo//yllqDzg= Authentication HeaderThe DMDS REST API uses the standard HTTPAuthorization header to pass authentication information. (The name of the standard header is unfortunate because it carries authentication information, not authorization). Under the DMDS API authentication scheme, the Authorization header has the following form: Authorization: DMDS-API DMDS_Access_API_Key:Signature Developers are issued an DMDS Access/API Key ID and DMDS Secret Access Key when they register. For request authentication, DMDS_Access_API_Key element identifies the secret key that was used to compute the signature, and (indirectly) the developer making the request. The Signature element is the RFC 2104HMAC-SHA1 of selected elements from the request, and so the Signature part of the Authorization header will vary from request to request. If the request signature calculated by the system matches the Signature included with the request, then the requester will have demonstrated possession to the DMDS Secret Access Key. The request will then be processed under the identity, and with the authority, of the developer to whom the key was issued. Following is pseudo-grammar that illustrates the construction of the Authorization request header ('\n' means the Unicode code point U+000A commonly called newline).
Authorization = "DMDS-API" + " " + DMDS_Access_API_KeyID + ":" + Signature Signature = Base64( HMAC-SHA1( YourDMDSSecretAccessKeyID , UTF-8-Encoding-Of( StringToSign ) ) ) StringToSign = UPPERCASE( HTTP-Verb ) + "\n" + UPPERCASE( Date ) + "\n" + CanonicalizedResource CanonicalizedResource = UPPERCASE( [ "/" ] + <HTTP-Request-URI, from the protocol name up to the query string> ) HMAC-SHA1 is an algorithm defined by RFC 2104 (go to RFC 2104 - Keyed-Hashing for Message Authentication ). The algorithm takes as input two byte-strings: a key and a message. For DMDS API Request authentication, use your DMDS Secret Access Key (YourDMDSSecretAccessKeyID) as the key, and the UTF-8 encoding of the StringToSign as the message. The output of HMAC-SHA1 is also a byte string, called the digest. The Signature request parameter is constructed by Base64 encoding this digest. Time Stamp Requirement
A valid time stamp (using either the HTTP Date header or an x-dmds-date alternative) is mandatory for authenticated requests.
Furthermore, the client time-stamp included with an authenticated request must be within 15 minutes of the
DMDS API system time when the request is received.
Some HTTP client libraries do not expose the ability to set the Date header for a request. If you have trouble including the value of the 'Date' header in the canonicalized headers, you can set the time-stamp for the request using an 'x-dmds-date' header instead. The value of the x-dmds-date header must either be in one of the RFC 2616 formats (http://www.ietf.org/rfc/rfc2616.txt) or UTC format (see examples below). When a x-dmds-date header is present in a request, the system will ignore any Date header when computing the request signature.
[ RFC 2616 Formats ] Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format [ UTC Format ] YYYY-MM-DDTHH:MM:SS ; Supported UTC format 2012-01-01T19:34:55 ; Jan 01, 2012, 19:34:55 Authentication ExamplesThe examples in this section use the (non-working) credentials in the following table:
In the example StringToSign(s), formatting is not significant and \n means the Unicode code point U+000A commonly called newline. Example #1: GET ORDERThis example gets an order with orderID: 123
Example #2: GET ORDER REDUXThis example gets an order with orderID: 123, but uses the custom x-dmds-date header
Example #3: GET FILESThis example gets video files
Code Examples
REST Request Signing ProblemsWhen REST request authentication fails, the system responds to the request with an XML error document. The information contained in this error document is meant to help developers diagnose the problem. |