Merge pull request #24 from formkiq/v1.13.0

v1.13.0

diagrams/architecture/document-events-processing.py

@@ -0,0 +1,15 @@
+from diagrams import Cluster, Diagram, Edge
+from diagrams.aws.general import User
+from diagrams.aws.compute import Lambda
+from diagrams.aws.network import APIGateway
+from diagrams.aws.integration import SNS, SQS
+
+with Diagram("Document Event Processing", show=False):
+
+    api = APIGateway("Documents API")
+    lambda_processor = Lambda("Document Processor")
+    sns_documentevents = SNS("Document Events")
+    sqs_processing = SQS("Processing Queue")
+
+    staging = User("User")
+    staging - Edge(label="Create Document") - api - Edge(label="Document Event") - sns_documentevents - Edge(label="Create Event") - sqs_processing - Edge(label="Additional Document Processing") - lambda_processor

docs/platform/api_security.md

@@ -2,79 +2,80 @@
 sidebar_position: 3
 ---
 
-# API Security
+# Security
 
-![Authentication](./img/formkiq_authentication.png)
-
-The FormKiQ API is built on top of [AWS API Gateway](https://aws.amazon.com/api-gateway/). API Gateway offers the flexibility to empowers customers to choose the most suitable authentication method based on their specific application requirements. 
+## Overview
 
-The FormKiQ installation deploys multiple copies of the API, with each one using a different authentication mechanism. This allows you to choose the authentication mechanism that suits your needs.
+FormKiQ is designed with a robust security framework to safeguard user data and sensitive information. FormKiQ employs a Role-Based Access Control (RBAC) as its default security mechanism, ensuring a streamlined and efficient authorization process for all users. The RBAC system assigns roles to users based on their responsibilities, granting access only to the resources essential for their tasks.
 
-The FormKiQ API URL(s) can be found in the CloudFormation outputs of your FormKiQ stack.
-
-![CloudFormation Outputs API Urls](./img/cf-outputs-apiurls.png)
+:::note
+By default the `AdminEmail` configured during the installation process is setup as an administrator with full access
+:::
 
-:::note:
-[FormKiQ Enterprise](https://www.formkiq.com/products/formkiq-enterprise) users have additional authentication options like Security Assertion Markup Language (SAML).
+:::note
+[FormKiQ Pro/Enterprise](https://www.formkiq.com/products/formkiq-enterprise) users have the ability to use Attribute-based Access Control (ABAC) through [Open Policy Agent](https://www.openpolicyagent.org/).
 :::
 
-## JSON Web Token(JWT)
+## Groups
 
-JWT authentication, also known as [JSON Web Token](https://jwt.io/introduction) authentication, is a method used to verify the identity of users or systems accessing web applications or APIs. It is based on the use of digitally signed tokens containing encoded claims about the user's identity and permissions. 
+FormKiQ supports multi-tenancy environments by defining user group(s) and then linking these groups to the different FormKiQ site(s). Each user can be associated with one or more groups, reflecting their role or responsibilities within the platform. These groups, in turn, determine the user's access privileges across different sites within the platform.
 
-By default, FormKiQ uses [Amazon Cognito](https://aws.amazon.com/cognito) as the JWT Issuer and authorization is handled through role-based access control assigned to each user.
+The user's groups link to the FormKiQ's sites that the user will be granted access to; users can be in one or more groups, granting access to specific sites with specified roles.
 
-The API that uses the JWT authentication can be found in the CloudFormation Outputs of the FormKiQ installation under the `HttpApiUrl` key.
+| Group | Description
+| -------- | ------- |
+| Admins | Administrator group access |
+| authentication_only | Authentication only group access |
+| **site name** | Read/Write/Delete access to **site_name** |
+| **site name**_read | Read access to site **site_name** |
 
-![CloudFormation Outputs API Urls](./img/cf-outputs-apiurls.png)
 
-## AWS IAM
+FormKiQ comes with 4 groups by default. 
 
-[IAM Authentication](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-access-control-iam.html) allows customers to call the FormKiQ API by signing requests using [Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) with AWS credentials. 
+* **Admins** - Users in this group have full administrative privileges to all sites
 
-The API that uses the JWT authentication can be found in the CloudFormation Outputs of the FormKiQ installation under the `IamApiUrl` key.
+* **authentication_only** - Users in this group can authenticate and receive a access token, but do not have access to any sites. Used mainly with the Document Sharing API to share specific folders / documents with a user
 
-![CloudFormation Outputs API Urls](./img/cf-outputs-apiurls.png)
+* **default** - The "default" FormKiQ site that is created on installation. Users in this group will have read/write/delete access to the "default" site.
 
-:::note:
-You need the IAM execute-api permission to be able to use IAM Authentication and all requests will be run with administration privileges.
-:::
+* **default_read** - The "default" FormKiQ site that is created on installation. Users in this group will have read access to the "default" site.
 
-## API Key
+Here is what the groups in [Amazon Cognito](https://aws.amazon.com/cognito) looks like by default.
 
-FormKiQ allows for the generating of an API key that can be used to access the FormKiQ API for a particular `SiteId`.
+![Security Roles Example](./img/security-roles-examples.png)
 
-The API key can be generated using the `POST /configuration/apiKeys` API endpoint using credentials with `administrator` privileges.
+:::note
+The Cognito User pool can be found by visiting the [Cognito Console](https://console.aws.amazon.com/cognito) page and searching for the `AppEnvironment` name you configured during installation.
 
-The API that uses the Key authentication can be found in the CloudFormation Outputs of the FormKiQ installation under the `KeyApiUrl` key.
+![Cognito Home](./img/cognito-home.png)
+:::
 
-![CloudFormation Outputs API Urls](./img/cf-outputs-apiurls.png)
+### Add Multi-Tenant Site
 
-:::note:
-Each API key is only valid for a particular SiteId.
-:::
+Creating a new Multi-Tenant Site is as easy as creating a new group and adding users to the group.
 
-## Amazon Cognito
+To add a new group to Amazon Cognito:
 
-FormKiQ comes with a fully-functional console for interacting with documents, built using React. This console can be referenced when creating custom applications that will interact with the FormKiQ Document API. The console URL can be found in the CloudFormation outputs.
+* Open the [Amazon Cognito Console](https://console.aws.amazon.com/cognito)
+* Click on the `Group` tab and click `Create Group`
 
-![CloudFormation Outputs Console Url](./img/cf-outputs-consoleurl.png)
+![Cognito Home](./img/cognito-add-group.png)
 
-Console access is controlled through the [Amazon Cognito JWT authorizer](https://aws.amazon.com/cognito). By default the `AdminEmail` configured during the CloudFormation creation is created as an administrator user.
+* Enter a `Group Name` and click `Create Group`
 
-Additional users can be added manually through the [Cognito Console](https://console.aws.amazon.com/cognito).
+![Cognito Home](./img/cognito-create-group.png)
 
-### Create User
+The site has now been created and you can add users to this group to give them access to the finance site.
 
-To add a new user, start by visiting the [Cognito Console](https://console.aws.amazon.com/cognito). You should find the Cognito User pool with the configured `AppEnvironment` in the name.
+![Cognito Group List](./img/cognito-groups-list-finance.png)
 
-![Cognito Home](./img/cognito-home.png)
+### Add User to Site
 
-:::note:
+:::note
 If you do not see a Cognito User pool, check that the region you are in matches the region where you have installed FormKiQ.
 :::
 
-![Cognito Users Tab](./img/Cognito Create User)
+![Cognito Users Tab](./img/cognito-create-user.png)
 
 Clicking the Cognito Users tab, you should see the administrator user that was created during the installation process.
 
@@ -95,15 +96,66 @@ Click the `Create user` button to finish creating the new user. The user receive
 
 The user is now created with read / write access to the default site id.
 
-### Group Permissions
 
-FormKiQ starts with three default groups.
 
-* Admins - Group for administrators of FormKiQ
-* default - Read / Write permission for the default site id
-* default_read - Read permission for the default site id
+## API Endpoints 
+
+The FormKiQ API is built on top of [AWS API Gateway](https://aws.amazon.com/api-gateway/). API Gateway offers the flexibility to empowers customers to choose the most suitable authentication and authorization methods based on their specific application requirements. 
+
+By default FormKiQ API supports 3 different types of authorization:
 
-![Cognito Group List](./img/cognito-group-list.png)
+* JSON Web Token(JWT) Authorizers
 
-By default if a user belongs to no groups, it will be given the "default" group permissions. By clicking on any of the groups users can be easily added or removed.
+* Amazon Identity and Access Management (IAM) authorization
+
+* API Key authorization
+
+![Authentication](./img/formkiq_authentication.png)
+
+FormKiQ supports these different authorization mechanisms by deplying multiple copies of the API. This allows you to use the authentication mechanism that suits your needs.
+
+The FormKiQ API URL(s) can be found in the CloudFormation outputs of your FormKiQ stack.
+
+![CloudFormation Outputs API Urls](./img/cf-outputs-apiurls.png)
 
+:::note
+[FormKiQ Enterprise](https://www.formkiq.com/products/formkiq-enterprise) users have additional authentication options like Security Assertion Markup Language (SAML) or custom authentication mechanisms
+:::
+
+### JSON Web Token(JWT) Authorizers
+
+JWT authentication, also known as [JSON Web Token](https://jwt.io/introduction) authentication, is a method used to verify the identity of users or systems accessing web applications or APIs. It is based on the use of digitally signed tokens containing encoded claims about the user's identity and permissions. 
+
+By default, FormKiQ uses [Amazon Cognito](https://aws.amazon.com/cognito) as the JWT Issuer and authorization is handled through role-based access control assigned to each user.
+
+The API that uses the JWT authentication can be found in the CloudFormation Outputs of the FormKiQ installation under the `HttpApiUrl` key.
+
+![CloudFormation Outputs API Urls](./img/cf-outputs-apiurls.png)
+
+### Amazon Identity and Access Management (IAM) authorization
+
+[IAM Authentication](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-access-control-iam.html) allows customers to call the FormKiQ API by signing requests using [Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) with AWS credentials. 
+
+IAM Authentication is typically used for machine-to-machine authorization as there is no user information inside of the token.
+
+The API that uses the IAM authentication can be found in the CloudFormation Outputs of the FormKiQ installation under the `IamApiUrl` key.
+
+![CloudFormation Outputs API Urls](./img/cf-outputs-apiurls.png)
+
+:::note
+You need the IAM execute-api permission to be able to use IAM Authentication and all requests will be run with administration privileges.
+:::
+
+### API Key
+
+FormKiQ allows for the generating of an API key that can be used to access the FormKiQ API for a particular `SiteId`.
+
+The API key can be generated using the `POST /configuration/apiKeys` API endpoint using credentials with `administrator` privileges.
+
+The API that uses the Key authentication can be found in the CloudFormation Outputs of the FormKiQ installation under the `KeyApiUrl` key.
+
+![CloudFormation Outputs API Urls](./img/cf-outputs-apiurls.png)
+
+:::note
+Each API key is only valid for a particular SiteId.
+:::

docs/platform/building_from_source.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 # Building from Source

docs/platform/costs.md

@@ -4,8 +4,8 @@ sidebar_position: 7
 
 # Costs
 
-FormKiQ was created using [serverless technology](https://aws.amazon.com/serverless). This means that there are no servers to manage; everything is managed by AWS. All AWS services FormKiQ uses have pay-per-usage billing. You can start using FormKiQ with very little cost.
-
+FormKiQ is built using [serverless technology](https://aws.amazon.com/serverless). This means that there are no servers to manage; everything is managed by AWS. All of the AWS services FormKiQ uses have pay-per-usage billing (with only one exception, OpenSearch, an add-on module). You can start using FormKiQ with very little cost.
+ 
 In fact, AWS provides a [free tier](https://aws.amazon.com/free) to all AWS accounts. This means that some AWS services you can use for **free**, assuming you are able to stay within the usage limits. Below is the list of services FormKiQ uses and their approximate usage costs, so give you an idea on how much it costs to run FormKiQ. (All costs in USD)
 
 | Service    | Cost |
@@ -17,3 +17,63 @@ In fact, AWS provides a [free tier](https://aws.amazon.com/free) to all AWS acco
 | [Amazon CloudFront](https://aws.amazon.com/cloudfront/pricing) |   $0.085 per GB of Data Transfer Out to Internet |
 | [Amazon S3](https://aws.amazon.com/s3/pricing) |   $0.023 per GB / Month |
 | [AWS Lambda](https://aws.amazon.com/lambda/pricing) |   approx. first 400,000 requests Free per Month ($0.0000168667 per additional request) |
+
+## Cost Estimator
+
+Because of AWS' pay-per-usage model, it can be difficult to determine approximately what your hosting fees will be. The [AWS Pricing Calculator](https://calculator.aws/#/) can be useful to establish general costs. Below we have scenarios that gives you an idea of what your costs maybe.
+
+These scenarios do NOT include AWS' free tier or potential cost savings when higher usage tiers are reached.
+
+:::note
+All prices are shown in USD
+:::
+
+### Adding - 1 million documents
+
+Scenario: Adding 1 million documents, each document is 1 MB in size
+
+| Service    | Unit | Cost |
+| -------- | ------- | ------- |
+| Amazon DynamoDB Storage  | 1 GB (each document stores about 350 bytes of data) | $0.25  |
+| Amazon DynamoDB Write  | 3 million requests  | $7.00  |
+| AWS Lambda  | 2 million requests (200ms avg per document)  | $10.00   |
+| Amazon S3 PUT requests  | 2 million  | $10.00   |
+| Amazon S3 (Standard Storage)  | 1 TB  | $30.00 per month  |
+| or Amazon S3 (Glacier Instant Retrieval Storage)  | 1 TB  | $5.00 per month  |
+| |Total ($) | $57.25 or $32.25 |
+
+### Viewing - 1 million documents
+
+Scenario: Viewing 1 million documents, each document is 1 MB in size
+
+| Service    | Unit | Cost |
+| -------- | ------- | ------- |
+| Amazon DynamoDB Read Requests  | 1 million requests  | $0.13  |
+| Amazon S3 Data Transfer  | 1 TB  | $92.16   |
+| |Total ($) | $92.29 |
+
+### OCR - 1 million PDF documents
+
+Scenario: Extracting text from PDF document
+
+FormKiQ supports extracting text from a PDF document in two ways that have a different cost structure/features; many PDFs that were created electronically can have their text extracted programatically, without requiring OCR. For documents that are not fully digitized, such as documents that were scanned from paper or came from a photograph, OCR would be required.
+
+FormKiQ determines whether or not OCR is required automatically.
+
+| Service    | Unit | Cost |
+| -------- | ------- | ------- |
+| AWS Lambda (Programmatically, for fully-digital PDFs)  | 1 million requests (30 million pages)  (600ms avg per document) | $20.20  |
+| [AWS Textract](https://aws.amazon.com/pm/textract) (for PDFs that are not fully digital)  | 1 million pages (text only)  | $1500.00   |
+
+
+### OCR - 1 million images
+
+Scenario: Extracting text from images, such as PNG
+
+FormKiQ supports extracting text from a PNG document in two ways that have a different cost structure/features. 
+
+| Service    | Unit | Cost |
+| -------- | ------- | ------- |
+| [Tesseract](https://github.com/tesseract-ocr/tesseract) (using AWS Lambda) | 1 million requests (1 million pages)  (3000ms avg per document) | $100.20  |
+| [AWS Textract](https://aws.amazon.com/pm/textract)  | 1 million pages (text only)  | $1500.00   |
+