HTTP Header Authentication Mechanism

In Niagara 4.4, an authentication mechanism was implemented that utilizes HTTP headers to send and receive authentication information in order to better support machine to machine authentication.

Authentication Messages

This authentication mechanism relies on authentication messages sent between the client and server as HTTP headers. The client sends credentials in the Authorization header and the server sends challenges in the WWW-Authenticate header. Auth messages are restricted to the following syntax:

auth-scheme  = token
auth-param   = token BWS "=" BWS token

auth-message = auth-scheme [ 1*SP #auth-param ]

Token syntax is defined in [RFC7230], Section 3.2.6. If an auth-param value is not a valid token, it should be base64url encoded with no padding.

Hello Message

The first step in the authentication process is for the client to send a HELLO message to the server. This message must include a username parameter with the base64url encoding of the UTF-8 encoded username.

Authorization: HELLO username=dXNlcg

The server responds with a 401 Unauthorized response with a WWW-Authenticate header indicating what authentication mechanisms are supported for the user. If the user does not exist, the server will still return a 401 with at least one valid authentication mechanism. The server may include a handshakeToken in the response message in order to maintain state between requests. If a handshakeToken is included, the client must include the token on subsequent requests.

401 Unauthorized
WWW-Authenticate: SCRAM hash=SHA-256, handshakeToken=1234

Authentication Exchange

After the server responds to the HELLO message, the client should select an authentication mechanism and continue with the authentication exchange as defined by the selected mechanism.

If authentication fails during the exchange, the server must respond with a 403 Forbidden status.

Auth Token

Once the user has successfully authenticated, the server must respond with a 200 Ok status and an Authentication-Info header with an authToken parameter that the client will use to make future requests to the server.

200 Ok
Authentication-Info: authToken=5678

The client must use the BEARER auth scheme to pass the authToken to the server on subsequent requests.

Authorization: BEARER authToken=5678

SCRAM

The only authentication mechanism currently supported by Niagara is SCRAM (Salted Challenge Response Authentication Mechanism). Any Niagara user with the digest authentication scheme will support the SCRAM HTTP header authentication message. An example of the SCRAM authentication exchange is shown below.

Client sends `HELLO’ message

Authorization: HELLO username=dXNlcg

Server responds with SCRAM authentication scheme, the hash function as a hash parameter, and the handshake token. The hash function can either be SHA-256 or SHA-512. Currently, only SHA-256 is supported in Niagara.

401 Unauthorized
WWW-Authenticate: SCRAM hash=SHA-256, handshakeToken=1234

The client sends the base64url encoded client first message as the data parameter.

Authorization: SCRAM handshakeToken=1234, data=biwsbj11c2VyLHI9ck9wck5HZndFYmVSV2diTkVrcU8K

The server responds with the base64 encoded server first message as the data parameter.

401 Unauthorized
WWW-Authenticate: SCRAM handshakeToken=1234, hash=SHA-256,
    data=cj1yT3ByTkdmd0ViZVJXZ2JORWtxTyVodllEcFdVYTJSYVRDQWZ1eEZJ
         bGopaE5sRixzPVcyMlphSjBTTlk3c29Fc1VFamI2Z1E9PSxpPTQwOTYK

The client sends the base64url encoded client final message as the data parameter.

Authorization: SCRAM handshakeToken=1234,
    data=Yz1iaXdzLHI9ck9wck5HZndFYmVSV2diTkVrcU8laHZZRHBXVWEyUmFUQ
         0FmdXhGSWxqKWhObEYscD1kSHpiWmFwV0lrNGpVaE4rVXRlOXl0YWc5em
         pmTUhnc3FtbWl6N0FuZFZRPQo

The server responds with the base64 encoded server final message, as well as an authToken since authentication was successful.

200 Ok
Authentication-Info: authToken=5678, hash=SHA-256,
    data=dj02cnJpVFJCaTIzV3BSUi93dHVwK21NaFVaVW4vZEI1bkxUSlJzamw5NUc0PQo

The client verifies the server final message, then makes subsequent requests to the server and includes the authToken in the BEARER auth message.

Authorization: BEARER authToken=5678

Example

See Scram Sha Client Authentication Example for a sample implementation utilizing the HTTP Header Authentication Mechanism.