Chapter 06 of 11
Request Signing: OAuth 1.0, AWS SigV4 and Hawk
What request signing buys you over a bearer token, how nonces and timestamps stop replay, and where each of these four schemes still turns up.
Everything in the previous chapters sends a credential and trusts TLS to protect it in transit. The four schemes here take a different approach, called request signing. They sign the request itself with a secret that never leaves either end.
That buys two properties a bearer token does not have. The signature covers the request, so nothing between the parties can alter it unnoticed, and a captured request cannot be replayed because it carries a timestamp and a nonce.
The cost is complexity on both sides, and complexity in a signing implementation is where the bugs live.
What a signature covers, and why nonces matter
A signing scheme defines a canonical string built from the parts of the request that matter, computes a keyed hash over it, and sends the result.
Three ingredients recur.
A canonical form. Both sides must build the identical string from the same request, which means agreeing on header ordering, on how query parameters are sorted, and on how everything is encoded. Most signing bugs are canonicalisation bugs.
A timestamp. The server rejects signatures outside a narrow window, usually a few minutes, so a captured request stops working quickly. This means both ends need a reasonably correct clock.
A nonce. A value used once, remembered by the server for the length of the timestamp window. It closes the gap the timestamp leaves, since a request can otherwise be replayed freely inside the window.
Some schemes also cover a hash of the body, which extends integrity from the envelope to the payload.
OAuth 1.0
OAuth 1.0, specified in RFC 5849, solved delegated access in a world without universal TLS, so it signed every request instead of relying on the channel.
The signature covers the method, the URL, and the request parameters sorted and encoded in a defined way, using a key built from the consumer secret and the token secret. Four signature methods exist. Those are HMAC-SHA1, HMAC-SHA256, RSA-SHA1 and a plaintext mode that only makes sense over TLS.
OAuth 2.0 replaced it by dropping signing and depending on the transport, which made clients dramatically simpler. What remains is the installed base, so some established APIs still expect OAuth 1.0 and are not going to change.
The parameters can travel in the Authorization header, in the request body or in the query string, and the choice is dictated by the server and not by preference.
AWS Signature Version 4
AWS requires SigV4 on essentially every service API, so any client calling AWS implements it or uses a library that does.
Its distinguishing feature is key derivation. Instead of signing with your secret access key, you derive a signing key from that secret plus the date, the region and the service name, and sign with the derived key. A signing key that leaks is therefore useful only for that one day, in that one region, for that one service.
The canonical request covers the method, the path, the sorted query string, the signed headers, and a hash of the payload. Because the payload hash is included, the body is protected as well as the envelope.
Four values are needed to configure it. Those are the access key, the secret key, the region and the service name, plus a session token when using temporary credentials.
Hawk
Hawk was designed as a lighter successor to the OAuth 1.0 signing mechanism for cases where a bearer token over TLS is not sufficient.
It computes an HMAC over the method, the URI, the host, the port, a timestamp and a nonce, and it can optionally include a hash of the payload. Two algorithms are in common use, SHA-256 and SHA-1, and SHA-256 is the one to pick where you have the choice.
Hawk mostly appears inside systems whose authors chose it deliberately, and seldom in public APIs, so you will meet it when integrating with one of those.
NTLM
NTLM is a Microsoft challenge-response protocol from the Windows networking world, and it authenticates a user account, not an application.
The exchange is three messages, so the client announces, the server challenges, and the client responds with a hash derived from the password and the challenge. It is stateful in a way HTTP is not, because the handshake binds to a connection, and that is why NTLM behaves badly through proxies and load balancers.
Kerberos replaced it inside Active Directory environments, and NTLM persists in older intranet applications and appliances. Where you meet it, you need a username, a password, and often a domain and a workstation name.
Choosing between signing and a bearer token
| Situation | Prefer |
|---|---|
| A public API over TLS with ordinary requirements | A bearer token, because the complexity is not free |
| Requests that traverse something you do not control | Signing, because integrity is then yours and not the channel's |
| Replay is a specific concern, such as payment instructions | Signing, for the nonce and the timestamp window |
| The other side already requires a scheme | Whatever they require, since this is not a design decision |
The last row covers most real cases. Nobody picks AWS Signature V4 on its merits, because they are calling an AWS service and that is what it requires.
If you find yourself weighing a signing scheme for a new API of your own, note that these four are specified, reviewed and implemented in libraries. A scheme designed in-house has none of those properties, which the chapter on mutual TLS, cookies and custom HMAC takes up.
In Routebase
All four are in the authentication catalogue, configurable at environment, suite, case and persona level like every other scheme.
OAuth 1.0 takes the consumer key and secret, the access token and token secret, and the signature method from HMAC-SHA1, HMAC-SHA256, RSA-SHA1 and plaintext. The remaining parameters are there for servers that need them set explicitly. Those cover the realm, the verifier, the timestamp, the nonce and the version. Three switches decide whether the parameters travel in the header, the body or the URL, whether a body hash is included, and whether empty parameters enter the signature.
AWS Signature V4 takes the access key, the secret key, the region and the service name, with a session token field for temporary credentials.
Hawk Auth takes the authentication identifier and key plus the algorithm, either SHA-256 or SHA-1. The optional fields cover the user, the application and delegation identifiers, an extension value, and whether the payload hash is included.
NTLM Auth takes a username and password plus the domain and workstation.
Every field accepts a {{VARIABLE}} placeholder, so secrets live in secret variables and the configuration stays portable between environments. See Project Auth for the editor.
Frequently asked questions
What is request signing in API authentication?
Request signing computes a cryptographic signature over parts of the request, typically the method, the path, selected headers, a timestamp and a nonce, using a shared secret or a private key. The secret itself never travels, and the signature covers the whole request, doing more than identify the caller. That gives integrity and replay resistance that a bearer token does not provide on its own.
What is AWS Signature Version 4?
It is the signing scheme AWS services require, and it signs a canonical form of the request with a key derived from your secret access key, the date, the region and the service name. The derivation is what limits the damage from a leaked signing key, since a key derived for one day, one region and one service is useless elsewhere. Any client calling an AWS API has to implement it or use a library that does.
Is OAuth 1.0 still used?
Rarely for new work, and it persists in long-lived integrations that never migrated, since OAuth 2.0 replaced it. OAuth 1.0 signed every request because it was designed before TLS was universal, and OAuth 2.0 dropped signing and relies on the transport instead. The practical reason to understand OAuth 1.0 is that some established APIs still expect it.
What is Hawk authentication?
Hawk is an HTTP authentication scheme that signs a request with an HMAC over the method, the URI, the host, the port, a timestamp and a nonce, and optionally over a hash of the payload. It was designed as a lighter successor to the OAuth 1.0 signing mechanism for cases where a bearer token over TLS is not enough. It appears mostly inside systems whose authors chose it deliberately, and seldom in public APIs.
Last reviewed by The Routebase Team.