Authentication - AquaticInformatics/aquarius-sdk-net GitHub Wiki

The Aquarius SDK supports two modes of token-based authentication: 1) Session Token (i.e., credentials users); and 2) OpenID Connect Access Token (i.e., OpenID Connect, or AQI Identity).

Session Token

An authenticated client is created by passing a server name and credentials to the IAquariusClient AquariusClient.CreateConnectedClient(server, user, password) static method.

using(var client = AquariusClient.CreateConnectedClient("myserver", "myuser", "mypassword"))
{
    // Make AQTS public API requests here
}

OpenID Connect Access Token

Access Tokens generated by supported OpenID Connect (OAuth 2.0) authentication providers can be used to authenticate with any Time-Series REST APIs. An authenticated client is created by passing a server name and access token to the IAquariusClient AquariusClient.CreateConnectedClient(server, accessToken) static method.

using(var client = AquariusClient.CreateConnectedClient("myserver", "myaccesstoken"))
{
    // Make AQTS public API requests here
}

Authenticated clients generated using OpenID Connect token-based authentication do not have a re-authentication mechanism. The lifetime of access tokens differ between OpenID Connect providers. Once your access token is invalidated, you can "re-authenticate" by issuing another login request against the client.

client.UpdateAccessToken(accessToken);
// Continue AQTS public API requests here

Aquarius Client

The IAquariusClient interface implements IDisposable, so wrapping it in a using(...) statement is the preferred method to ensure proper resource handling. The authenticated session will be deleted by a DELETE /session request when the Dispose() method is invoked.

If the supplied credentials or access token are not valid, or are unknown to the AQTS server, the CreateConnectedClient() method will throw a 401 Unauthorized exception.

Hostname format

The hostname string parameter of the CreateConnectedClient() method accepts a variety of string formats to specify the AQTS server.

  • Supports http:// and https:// URL schemes. If no URL scheme is specified, http:// is used.
  • Supports non-standard ports. If no port is specified, the default port for the URL scheme is used.
  • Supports dns names, IPv4, or IPv6 addresses.

The above rules mean that the "myserver", "http://myserver", and "http://myserver:80" string values are all functionally-equivalent hostname parameters values.

Password encryption

For Session Token-based authentication, the CreateConnectedClient() method will encrypt the password using the server's public key before POSTing the authentication request. While this will prevent the password from being transmitted in plain text over an HTTP connection, the POST request itself is still vulnerable to a replay-attack.

For OpenID Connect Access Token-based authentication, consider the OAuth Access Tokens as a private secret similar to a user password. When security is important to your deployment, please install a TLS certificate on your AQTS server and use HTTPS connections to secure all the API traffic.