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": ["COGNITO", "IAM", "CUSTOM"]
    },
    "authorizerArn": {
      "type": "string"
    },
    "allowedAccounts": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    }
  }
}

You can use the following types for authentication and authorization:

  • 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 the API calls with valid JWT tokens 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.

Examples

Here is the example of using IAM type authorization, which restricts access to Node1 to signed requests made from 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"]
                    }
                }
            }
        }
    ]
}

Here is the example of using Cognito type authorization, which restricts access to Node1 to signed requests made from Cognito User Pool 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 generated token will need to be passed in to the Vendia Share node using the AUTHORIZATION header.

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