Skip to content

Web API Security

Most requests to the Domain Services Web APIs are protected using Basic Authentication. Basic authentication is an authentication scheme built into the HTTP protocol. All administrative resources, such as service connections and user accounts, are protected. Furthermore, all requests that are modifying resources (for example adding, updating or removing resources) are protected, while some simple querying requests might not be protected.

Basic Authentication is using a Base64 encoding of username and password. As the Base64 encoding is reversible, and thus easily decoded, Basic Authentication should only be used together with other security mechanisms such as HTTPS.

The Basic Authentication scheme requires that the client must authenticate itself with a username and a password for each request. The client must compute a Base64 encoding of {userName}:{password} and include the value in an Authorization header in the request:

Authorization: Basic {Base64 encoded value}

Below, an example of a request for adding a few values to a time series resource is shown:

PUT api/timeseries/waterforecast-ts/Amager-Strandpark/values
Content-Type: application/json
Authorization: Basic YWRtaW46VGhpc0lzTm90VGhlUmVhbFBhc3N3b3JkIQ==
{
    "DateTimes": [
      "2007-02-18T22:15:00",
      "2007-02-18T22:20:00",
      "2007-02-18T22:25:00"
    ],
    "Values": [
      0.22908926,
      0.229103819,
      0.229090463
    ]
}

If the requesting user is not properly authenticated, the server will return a response with HTTP status code 401 (Unauthorized).

The Web APIs are protected against brute-force attacks using a progressive delay mechanism where every failed validation attempt from a given IP address will lead to an increasingly longer response time.

User Accounts

The user and password validation of the Basic Authentication scheme is done against the registered Accounts.

User Account management can be done using the API Administrator Web site that is included in the Web API project templates.

Currently, Domain Services offers two ways for storing the user accounts. One option is to store the user accounts in a text file (accounts.json). This is useful for example if the client application does not require a user login, but will always login with the same "system" user account.

The other option is the Azure Cosmos DB provider (formerly known as DocumentDB), where the user accounts are stored in Azure Cosmos DB. This approach is more appropiate for client applications that require user login - especially if the number of user accounts is (potentially) large. Either way, the passwords are always stored as irreversible hashes.

As with any other storage in Domain Services, also the user account storage is abstracted away in the form of the IAccountRepository that serves as an extensibility point where you can plug in alternative implementations of a user account repository.

Furthermore, the Accounts API offers support for user account registration, activation and password reset.

Roles

The Web APIs are guarded by role-based security. The following 4 roles are defined:

  • Guest
  • User
  • Editor
  • Administrator

Access to administrative resource types such as Accounts and Connections obviously require Administrator privileges, while adding, updating and removing other resource types require Editor privileges.

Polymer Web Components

A number of Polymer Web Components are designed to work with the Accounts API of Domain Services. For example a login dialog and a dialog for password reset.