☰
Navigation :

Authorization

Overview

Clanforge supports AWS Signature Version 4 via the HTTP Authorization Header to provide authentication information.

The following is an example of the Authorization header value:

Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/eu-west-1/cf/aws4_request,SignedHeaders=host;range;x-amz-date,Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024

Note that there is space between the first two components, AWS4-HMAC-SHA256 and Credential, and that the subsequent components, Credential, SignedHeaders, and Signature are separated by a comma (no space).

The following table describes the various components of the Authorization header value.

Component Description
AWS4-HMAC-SHA256 The algorithm that was used to calculate the signature. You must provide this value when you use AWS Signature Version 4 for authentication. The string specifies AWS Signature Version 4 (AWS4) and the signing algorithm (HMAC-SHA256).
Credential Your Access Key and the scope information, which includes the date, region, and service that were used to calculate the signature. This string has the following form: <AccessKey>/<date>/<region>/<service>/aws4_request
SignedHeaders A semicolon-separated list of request headers that you used to compute Signature. The list includes header names only, and the header names must be in lower case e.g. host;range;x-amz-date
Signature The 256-bit signature expressed as 64 lower case hexadecimal characters e.g. fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024

Calculating a Signature

To calculate a signature, you first need a string to sign. You then calculate a HMAC-SHA256 hash of the string to sign by using a signing key. The following diagram illustrates the process, including the various components of the string that you create for signing:

When Clanforge receives an authenticated request, it computes the signature and then compares it with the signature that you provided in the request. For that reason, you must compute the signature by using the same method that is used by Clanforge. The process of putting a request in an agreed-upon form for signing is called canonicalisation.

CanonicalRequest

Component Data Notes
HTTP Verb + “\n” + “GET” or “PUT” or “POST” or “OPTIONS” …
CanonicalURI + “\n” + UriEncode() The CanonicalURI is the URI-encoded version of the absolute path component of the URI including everything starting with the “/” that follows the domain name and up to the end of the string or to the question mark character (‘?’) if you have query string parameters.For example, in the URIhttp://s3.amazonaws.com/examplebucket/myphoto.jpg/examplebucket/myphoto.jpg is the absolute path.
CanonicalQueryString + “\n” + UriEncode() + “=” + UriEncode() + “&” +UriEncode() + “=” + UriEncode() + “&” +…UriEncode() + “=” + UriEncode() Alphabetically Sorted by QueryParam
CanonicalHeaders + “\n” + Lowercase() + “:” + Trim() + “\n” +Lowercase() + “:” + Trim() + “\n” +…Lowercase() + “:” + Trim() + “\n” Alphabetically Sorted by HeaderName and must include the following:HTTP Host HeaderContent-Type Header if its present in the requestx-amz-date or Date Header
SignedHeaders + “\n” + Lowercase() + “;” +Lowercase() + “;” +…Lowercase() Alphabetically Sorted by HeaderName
HashedPayload Hex(SHA256Hash()) The hexadecimal value the SHA256 hash of the request payload.If no payload is present, such as in a GET request, you should use the hash of the empty string e.g. Hex(SHA256Hash(“”))

StringToSign

Component Data Example
“AWS4-HMAC-SHA256” + “\n” + Authorization Type
TimeStamp + “\n” + Format ISO8601 compact “201407240525T000000Z”
Scope + “\n” + <yyyymmdd>/<region>/<service>/aws4_request “20140724/eu-west-1/cf/aws4_request”
Hex(SHA256Hash(<CanonicalRequest>))

SigningKey

Component Data
DateKey HMAC-SHA256(“AWS4” + <SecretAccessKey>, “<yyyymmdd>”)
DateRegionKey HMAC-SHA256(<DateKey>, <region>)
DateRegionServiceKey HMAC-SHA256(<DateRegionKey>, <service>)
SigningKey HMAC-SHA256(<DateRegionServiceKey>, “aws4_request”)

Signature

Component Data
Signature HMAC-SHA256(, <StringToSign>)

Function Definiitions

Component Description
Lowercase() Convert the string to lower case.
Hex(<string>) Lower case base 16 encoding.
Trim(<string>) Remove any leading or trailing whitespace.
UriEncode(<string>) URI encode every byte.
HMAC-SHA256(<key>, <data>) The keyed-hash message authentication code (HMAC) of Secure Hash Algorithm (SHA) HMAC-SHA-256 digest of <data>, <key>, with the result encoded as a binary string
SHA256Hash(<data>) The Secure Hash Algorithm (SHA) SHA256 digest in binary format.

Constants & Variables

Variable Valid Values Description
<region> eu-west-1 The service region to service the request, this is always eu-west-1
<service> cf The service targeted by the request.
“\n” 0x0a The ASCII New line, hexidecimal 0x0a
<AccessKey> Hexidecimal value as created by Clanforge
<SecretKey> Hexidecimal value as created by Clanforge
Host If testing in postman this might need to be manually updated

Access / Secret Key Pair Management

A users Access / Secret Key pair can be created and managed from Dev Tools -> Key Management in Clanforge

API Authorization Failures

If your API call to Clanforge isn’t authorized then the HTTP Status code 403 will be returned. The body of the response may also contain json detailing the nature of failure e.g. 

{
    "error_code": 1,
    "_debug": [],
    "success": false,
    "messages": [],
    "error" :true,
    "error_message": "Not authorised"
}

AWS Authorisation Documentation

The official documentation to AWS Signature Version 4 which includes details and examples can be found here

Notes

If you are using the Java SDK here you will find that the SDK will sign the url with a trailing forward slash, this will cause 403’s; Reference.

For example the string to sign would be:

https://api.multiplay.co.uk/cfp/v1/server/list/?accountserviceid=<accountnumber>

However the correct url would be:

https://api.multiplay.co.uk/cfp/v1/server/list?accountserviceid=<accountnumber>

Useful References: