Vendia Node Access Controls

On each Uni node, users can access the underlying resources - data, files, etc. through a GraphQL API with HTTPS transport. Vendia allows node owners to control the API access and usage through API settings.

API Access

The node owner controls who can access the API endpoint through the authorization settings during node creation. Unlike other settings, the authorization settings are immutable and cannot be modified once the node is created.

How to set

Under node setting, node owners can set up API authorization, which is defined in the JSON schema:

"auth": {
  "type": "object",
  "properties": {
    "authorizerType": {
      "type": "string",
      "enum": ["API_KEY", "VENDIA_USER", "COGNITO", "IAM", "CUSTOM"]
    },
    "authorizerArn": {
      "type": "string"
    },
    "allowedAccounts": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    }
  }
}

You can use the following types for authentication and authorization:

  • API_KEY is not recommended for production Unis. An API Key helps to track or meter API usage, and is commonly combined with a secure authorization mechanism, but is not a secure authorization mechanism by itself.

  • VENDIA_USER allows you to use your Vendia credentials for authentication. Only API calls with valid a JWT, issued upon authentication, can access the API.

  • IAM limits the API access to allowed cloud accounts, specified in allowedAccounts fields. For AWS based nodes, the incoming API call needs to have the AWS V4 signature.

  • COGNITO allows you to attach pre-existed AWS Cognito user pools. Only API calls with a valid JWT can access the API. Cognito ARN must be set in authorizerArn field.

  • CUSTOM allows you to write and attach a customized authorizer, which enables you to integrate with any identity management solutions, such as LDAP, Active Directory(AD), Okta and etc. For AWS based nodes, authorizers can be developed with AWS Lambda. Lambda function ARN must be set in authorizerArn field.

API_KEY Example

The API_KEY authorizer type is not a secure authorization mechanism and should not be used for production Unis. It restricts access to Node1 to requests that include the API_KEY value.

{
  "name": "test-iam-authentication",
  "schema": "schema.json",
  "initState": "initial-state.json",
  "nodes": [{
    "name": "Node1",
    "userId": "user@domain.com",
    "region": "aws-region",
    "settings": {
      "apiSettings": {
        "auth": {
          "authorizerType": "API_KEY"
        }
      }
    }
  }]
}

The API_KEY should be submitted with every request to your Vendia Share node using the X-API-KEY header.

VENDIA_USER Example

The VENDIA_USER authorizer type allows you to make use of your existing Vendia credentials for authentication. It restricts access to Node1 to requests that include a valid JWT issued by Vendia Share.

{
  "name": "test-vendia_user-authentication",
  "schema": "schema.json",
  "initState": "initial-state.json",
  "nodes": [{
    "name": "Node1",
    "userId": "user@domain.com",
    "region": "aws-region",
    "settings": {
      "apiSettings": {
        "auth": {
          "authorizerType": "VENDIA_USER"
        }
      }
    }
  }]
}

The JWT should be submitted with every request to your Vendia Share node using the AUTHORIZATION header.

Cognito Example

The Cognito authorizer type allows you to make use of an existing Amazon Cognito User Pool. It restricts access to Node1 to requests that include a valid JWT issued by arn:aws:cognito-idp:aws_region:123456789012:userpool/aws_region_someid.

{
  "name": "test-cognito-authentication",
  "schema": "schema.json",
  "initState": "initial-state.json",
  "nodes": [{
    "name": "Node1",
    "userId": "user@domain.com",
    "region": "aws-region",
    "settings": {
      "apiSettings": {
        "auth": {
          "authorizerType": "COGNITO",
          "authorizerArn": "arn:aws:cognito-idp:aws_region:123456789012:userpool/aws_region_someid"
        }
      }
    }
  }]
}

The JWT should be submitted with every request to your Vendia Share node using the AUTHORIZATION header.

IAM Example

The IAM authorizer type allows you to control access through AWS Identity and Access Management (IAM). It restricts access to Node1 to signed requests made from the AWS account 1234567890.

{
  "name": "test-iam-authentication",
  "schema": "schema.json",
  "initState": "initial-state.json",
  "nodes": [{
    "name": "Node1",
    "userId": "user@domain.com",
    "region": "aws-region",
    "settings": {
      "apiSettings": {
        "auth": {
          "authorizerType": "IAM",
          "allowedAccounts": ["1234567890"]
        }
      }
    }
  }]
}

API Usage Control

In addition to authentication-based settings, Vendia also provides the node's owner with operational controls. These are expressed through usage plans that describe API request limits in the form of a throttle, quota, or both. The usage plan that applies is determined by the caller's API Key.

Node owners can create multiple API keys and usage plans to control the API usage. Each API key is associated with one usage plan that limits who the API being used.

How to set

Under settings->apiSettings, owners can create an array of API key objects. Each API key object contains two fields: value and usage plan.

Key Value

Node owners must provide the API key value, which is at least 20 characters long. The API key is scoped per node. The final API value is: {Uni-Name}{Node-Name}{Value}

Usage Plan

In a usage plan, node owners can set two limits:

  • Quota: how many total API calls allowed during a specific time period.

  • Throttle Rate: how fast you can call the API. This is expressed as two rates: the average rate limit and the burst rate limit.

Examples

Here is an example node setting with one usage plan that specifies a 100 calls per second and 10,000 calls per day calling limit.

"settings": {
  "apiSettings": {
    "apiKeys": [{
      "value": "USER-Provided",
      "usagePlan": {
        "throttleSettings": {
          "rateLimit": 100,
          "burstLimit": 100
        },
        "quotaSettings": {
          "limit": 10000,
          "offset": 0,
          "period": "DAY"
        }
      }
    }]
  }
}

Default API Key

One API key will be generated by default to protect the API endpoint. The default API key does not associate with a usage plan.

Show table of contents
Edit this page