Skip to main content

Application firewall

Background​

Due to the generic nature of Akkess Actor & Node API which allows for storing any kind of data, it is important to ensure that only valid data is stored in the actors and nodes. This includes both custom parts like customStatus and customAttributes it can be good to add an Internet facing layer in-between where a system can validate the data before it is stored in Akkess.

Like a facade that ensure that no data is stored in Akkess that is not valid according to your business rules.

In this facade you can also add additional security layers like rate limiting, IP filtering, etc.

The Application Firewall​

Akkess supports with an Application Firewall that can be used to ensure that only data from and authorized relay service is allowed to do ab certain task.

The firewall can be configured to allow direct calls without using a firewall key or for specific Actor roles.

The firewall configurations belong to an Akkess Application. One Akkess Application can have several firewall configurations.

The configuration can be enabled or disabled.

Example of use-case​

Only let callers that supply firewall key 'YYZ' excute action A, B, C

Only let callers with the role 'XYZ' excute action A, B, C

Application Firewall Key​

The firewall key is entered or system generated key that belongs to an Akkess Firewall Configuration. There can be zero and up to five keys per firewall configuration.

The firewall key is supplied as an HTTP header when calling the Akkess API - Application-Firewall-Key

The firewall is normally used in combination with an Akkess token. The firewall adds a layer of security:

  1. The application firewall ensures the API only can be called by callers using a valid key. The firewall does not evaluate any other kind of permissions than that the caller is allowed to call the API.
  2. Akkess Token is used to evaluate the permission and its rules on the API. Example: "Are you allowed to update the explicit actor?".
Application-Firewall-Key: <Firewall Key>
Authorization: Bearer <Akkess Token>

Actor role​

The application firewall can also be configured to only allow calls from callers with a specific role.

The is typically used to allow a support role to call the Akkess APIs directly without the need of a firewall key.

Services and Permissions​

Akkess supports Application Firewall on Actor and Node API. When enabled the firewall will protect all APIs.

If some APIs need to be open for all callers, the firewall can be disabled on the specific API.

Management​

The Application Firewall can be managed using Akkess IAM Console or via Firewall API.

Example firewall configuration​

const firewallRule = {
  "name": "Firewall",
  "status": "ENABLED",
  "description": "Limit access to everything except actor create",
  "authorizationKeys": [
    "0e1bfda4-8413-4b62-9b2c-f65740016e8d"
  ],
  "authorizedRoles": [
    {
      "key": "SUPPORT_ROLE"
    }
  ],
  "unprotectedServices": [
    {
      "unprotectedPermissions": [
        "permission.actor.access.create",
        "permission.actor.access.delete"
      ],
      "serviceDefinitionKey": "iam.actor",
      "serviceDefinitionSource": "CATALOG"
    }
  ]
}

Setting the firewall key using the client SDK​

info

The firewall key shall be kept safe and is not intended to be used in a client application. The firewall key is intended to be used in a secure backend service that acts as a relay service between the client application and Akkess.

// The firewall key is configured for the application in the IAM console
const firewallKey = '1905d96e-4f59-4a67-b1af-fd3e16acd60d'; 


// Central setup of the firewall key and IAM token

// Set the IAM token in JWT format to be used by the SDK - singleton
IamTokenService.setClientToken(iamTokenStr);

// Set the firewall key to be used by the SDK - singleton
ApplicationFirewallKeyService.setKey(firewallKey);

// Will pick both the IAM token and the firewall key from the central setup
const iamApiOptionsCentral = ApiUtil.iam();

// Example of a call
await ActorRestServiceV1.getSelf(iamApiOptionsCentral); 


// Set the firewall key and IAM token per usage

// Pick both the IAM token and the firewall key from the options
const iamApiOptions = ApiUtil.iam({ token: iamTokenStr, applicationFirewallKey: firewallKey });

// Example of a call
await ActorRestServiceV1.getSelf(iamApiOptions); 

/* 
  The call will look something like this
  
  "url": "https://api.akkess.io/actor/v1/actors/myself",
  "headers": {
    "Accept": "application/json, text/plain",
    "If-Modified-Since": "0",
    "Cache-Control": "no-store, no-cache, must-revalidate",
    "application-firewall-key": "1905d96e-4f59-4a67-b1af-fd3e16acd60d",
    "Authorization": "BEARER eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImM0YjMwM2FmOThkZGU2OWQxNWJmMDlhZGU3OWM2NDA0IiwiY3R5IjoidDEifQ.eyJqdGkiOiI1YmVhNjkxYi05MjY2LTRmYWMtYWI1ZC00MmVmMzZkZjBiZjEiLCJpc3MiOiJodHRwczovL2FwaS5kZXYuYWtrZXNzLmlvL2F1dGhvcml6YXRpb24vdjEiLCJzdWIiOiI2NjRlMmJlN2JlNDEzZDA5MDU4YjQzOGUiLCJhdWQiOiJ0ZW5hbnQtNjY0NzNlZWUzYzQ5NTQzM2MwM2FiNjA2IiwiZXhwIjoyMjI4OTgzNjM4LCJpYXQiOjE3Mjg5ODAwMzgsImFjYyI6ImFjY291bnQtNjNjNjVkZWU4M2FiZDQxYmU5ZjYxMTA0IiwiYXBwIjoiYXBwLTY2NDczZWI2MmM2MmQ0NjNmMjYyYjk4MiIsInRpZCI6InRlbmFudC02NjQ3M2VlZTNjNDk1NDMzYzAzYWI2MDYiLCJhcnMiOlt7InIiOlsiRFJJVkVSIl0sImMiOlsiVklOPVZJTi0xMjM0NTY3ODkwIl19XX0.Qynp-cMasiKnqsRJFJrem-3X9MfMOsaqr5MO_XjaHpbQ06zwCHW7jIQ0sus8i7V10CwzwxCP5V4E_qfDnMmAhxzKph-vb9LmKx9WOW4jVnPFtlfpzlVmI_EB0cgKa4uwuPE4lAXGAYkIH5TsDnGvvjcVpCY7jBU2wT0qe_CYTooKZhP6zvXnXGSp_YobL6Assrezs1SEYbRAD4qqUrZKjz0MzJiIu3Ru26ARqjE0DLQYTSe5IBl9Nxc1UmWhEQ87TYv5MJt74jEgbYey0A4Cb_1RlI1VWnJFnQJVmQTnuiom8G_7mZDsFYhDUVN9sG9R-6zDe8K9nZmurMaUhtGia69mglu3ADRwXqnS2tgMKX8mWvcrOk8RJxHF8zXA2QtewyRhD3lW6F9f8iFqB6GBewrzW1mEcvbVDOAO5h7waXrjyLRqtvki8y_DAkQRfftmTwKvOh7CWL-7KPSVJtRXkNGmdu2HSHAXqlaYL6JgjsenCzBjTM1ZYZdnMUOgCP9J"
  }
 */
Copyright © 2019 Akkess