Flo.w

# Authentication & Authorization

# Introduction

To access Flo.w Engine services and resources an API key is required. Flo.w API keys are opaque v4 UUIDs (opens new window) associated with a set of capabilities. Configuration of an API key, when it is created, confers access to specified Flo.w Engine resources and determines what level of access is granted (read, write and/or execute).

API keys are supplied when making requests to the Flo.w Engine REST API. See Making Authenticated Requests for details.

# API Key Types

Three types of API key are supported by Flo.w Engine, providing different levels of access:

# Master API Keys

Master API keys allow access to resources across any Flo.w application. They are generally only made available to system administrators or administration tools and are used to create, modify and delete Flo.w applications.

WARNING

Master keys should be treated as sensitive data and should never be distributed in a front-end web application.

# Application API Keys

Application API keys can only access resources owned by a single Flo.w application. They are used by Flo.w application developers and systems that integrate with Flo.w Engine (for example, front-end web applications).

Application keys with write-access are used by application developers to create and configure Flo.w Engine resources and upload geospatial data.

Application keys with read-only access are distributed in public-facing web applications to allow read access to Flo.w Engine resources.

WARNING

If a front-end web application or other service requires write access to Flo.w Engine resources, ensure that the key is configured with the minimal set of permissions. For example, restrict the type of resource that is writeable or restrict by resource ID.

# User API Keys

User API keys are associated with a single Flo.w User and provide restricted access to resources owned by that user.

User API keys are not currently used.

# Access Control Lists (ACLs)

In addition to the broad levels of access described above, each API key is also associated with an access control list (ACL) that provides finer grained access to classes of resources and the level of access granted (read, write and/or execute).

Access can be granted to the following resource classes:

  • auth: Authentication operations (log in, log out, change password etc.)
  • apikeys: API key CRUD operations.
  • appconfig: Application Config CRUD operations.
  • applications: Application CRUD operations.
  • users: User CRUD operations.
  • databases: Database CRUD operations.
  • datasets: Dataset CRUD and query operations.
  • uploads: Data Upload CRUD and data ingest operations.
  • tiles: Tile Source CRUD and Map Server operations.
  • styles: Map Style CRUD and Map Server operations.

Access levels:

  • read: CRUD get and getMany operations.
  • write: CRUD create, update and delete operations.
  • execute: Resource-specific 'extra' operations. For example, dataset querying or authentication operations.

# Creating and Configuring API Keys

API keys are created using the Flo.w REST API Create API Key operation. This operation, itself, requires authorization by supplying an API key that permits write access to the apikeys resource.

The ID of the API key resource is an auto-generated UUIDv4 and is used by Flo.w Engine to retrieve the associated ACL when a subsequent REST API request is authenticated with the API key.

API keys are immutable

API keys cannot be modified once created. A new API key must be generated to modify access permissions.

The permissions property of the API Key resource specifies the associated ACL. It specifies which resources are accessible when using the API key and what level of access is conferred.

The ACL is specified using JSON. The general form is shown below:

{
  <resource-class>: {
    <access-level>: [<resource-id-1>, <resource-id-2>, ...],
    <access-level>: [<resource-id-1>, <resource-id-2>, ...],
    ...
  },
  ...
}

Where:

  • <resource-class> is one of classes described above (e.g. datasets, tiles)
  • <access-level> is one of read, write or execute
  • <resource-id-n> is a Flo.w Engine resource ID

Any (or all) of the three components in an ACL entry can be the wildcard identifier *.

Note that the key type (master, app, user) has higher precedence than a key's ACL and will restrict accessible resources.

# Example ACLs

Read/write/execute access to all resources. (This is the default 'developer' ACL)

{"*": {"*": "*"}}

Read and execute access to all resources. (This is the default 'public' ACL used by web applications)

{"*": {"read": "*", "execute": "*"}}

Read and execute access to specified datasets only.

{
  "datasets": {
    "read": ["airquality", "london_boroughs"],
    "execute": ["airquality", "london_boroughs"],
  }
}

Execute access all resources and read/write access to the specified dataset.

{
  "*": {"execute": "*"},
  "datasets": {
    "read": ["airquality"],
    "write": ["airquality"]
  }
}

Note that a more-specific ACL entry has higher precedence than a less-specific entry. The following ACL allows read access to all resources, except for datasets, where only the specified dataset can be read.

{
  "*": {"read": "*"},
  "datasets": { "read": ["airquality"]}
}

Use an empty array to specify 'no resources'. The following ACL allows read access to all resources, except for datasets.

{
  "*": {"read": "*"},
  "datasets": {"read": []}
}

# Making Authenticated Requests

Unless specified otherwise in the REST API Reference, all REST requests must be authenticated. A Flo.w API key must be provided as a request header (preferred) or as a query parameter.

# Request Header Example

curl -X GET 'https://flow.emu-analytics.net/api/v1/datasets' \
  -H 'x-api-key: b6b77cc4-904a-46d1-aa0f-3bf3848ce4c7'

# Query Parameter Example

curl -X GET \
  'https://flow.emu-analytics.net/api/v1/datasets?api-key=b6b77cc4-904a-46d1-aa0f-3bf3848ce4c7'

The supplied API key must provide appropriate access (read, write or execute) to the requested resource. A '401 Unauthorized' error will be returned if the API key is missing or does not provide the required level of access.

# Token-Based Authentication

For some use cases it is not appropriate to distribute an API key in a web application, even if that API key only confers read access. Examples include web applications displaying sensitive information that should only be viewed by authorized users.

To accommodate these types of use cases, Flo.w Engine supports an alternative token-based authentication mechanism. Combined with its support for user management and authentication methods, sensitive web applications can implement secure user authentication without distributing an API key.

# How it works

Users log in to the front-end application with a username and password. These credentials are authenticated by Flo.w Engine and a short-lived access token is returned to the front-end application. Subsequent requests to Flo.w Engine by the application are authorized by passing the access token in the Authorization header of the request. Internally, Flo.w Engine exchanges the access token for an API key and request authorization proceeds as described above.

The access token uses the JWT standard (opens new window) and is digitally signed using public key encryption. It has a short expiry time (15 minutes by default). The front-end application can periodically refresh the access token by submitting a Refresh Authentication Token request using the refresh token that is provided in response to a log in request. Refresh tokens are longer-lived opaque tokens (14 days by default) and can be revoked if compromised.

# Access token/API key Exchange

When Flo.w Engine receives a REST request authenticated with an access token, it is first exchanged for an API key.

To select an API key, the following resource metadata keys are queried in order:

  • User metadata: auth.defaultApiKey
  • Application metadata: auth.defaultApiKey

The first API key found will be used to continue authorization of the request. If an API key is not found then the request will be denied with a 401 Unauthorized error.

# Authentication Flow

The sequence diagram below shows a typical user session with a Flo.w web application using token-based authentication.

← Introduction →