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.
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.
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
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.
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
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
See Scram Sha Client Authentication Example for a sample implementation utilizing the HTTP Header Authentication Mechanism.
Copyright © 2000-2019 Tridium Inc. All rights reserved.