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( |
Alphabetically Sorted by QueryParam |
CanonicalHeaders + “\n” + | Lowercase( |
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( |
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
- Authenticating Requests Using Signature v4
- Using Signature v4 Authorisation Header
- AWS Regions and Endpoints
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:
- https://github.com/DavidMuller/aws-requests-auth/blob/master/aws_requests_auth/aws_auth.py
- http://docs.aws.amazon.com/general/latest/gr/sigv4-signed-request-examples.html
- https://docs.aws.amazon.com/AWSECommerceService/latest/DG/rest-signature.html
- https://pypi.python.org/pypi/requests-aws4auth
- https://github.com/bradclawsie/awsv4-cpp