Core 1828 Docs Migration- Security: Topic and Subtopics by terraHDB · Pull Request #4 · HarperFast/documentation

terraHDB · 2022-10-06T21:59:22Z

This PR migrates Topic: Security and its subtopics. I updated operations in tables in Subtopic: users and roles.

This is the link to this page currently: https://harperdb.io/docs/security/users-roles/

DavidCockerill · 2022-10-17T20:30:47Z

@@ -0,0 +1,64 @@
+# Authentication
+
+HarperDB utilizes Basic Auth to secure our REST requests.  In the context of an HTTP transaction, **basic access authentication** is a method for an HTTP user agent to provide a user name and password when making a request.


Maybe reword this to say its one type of auth we use - we also utilize JWTs

DavidCockerill · 2022-10-17T20:32:37Z

+Below is a code sample from HarperDB Studio.  On Line 14 you will see where we are adding the authorization header to each request.  Again this needs to be added for each and every REST request for HarperDB.
+
+```bash
+function callHarperDB(call_object,operation,  callback){


Do you think we should update this code to something more modern? async/await... not use var etc

yes, whole page needs a rewrite. turning to draft

DavidCockerill · 2022-10-17T20:35:36Z

+
+
+
+## Using HarperDB Studio


Im confused by this part, why is HarperDB Studio under basic auth?

DavidCockerill · 2022-10-17T20:36:45Z

+
+1) Open the HarperDB harperdb.config file this can be found in /HDB_ROOT, the location you specified during install.
+
+2) In harperdb.config there should be 2 entries under `operationsApi.network`: cors and corsWhitelist. 


White list has been update to access list

This applies to all corsWhitelist ref

DavidCockerill · 2022-10-17T20:39:22Z

+
+
+
+HarperDB automatically generates a certificate and a privateKey file which live at `HDB_ROOT/keys/`.


we dont use HDB_ROOT anymore, maybe use <ROOTPATH>

DavidCockerill · 2022-10-17T20:41:39Z

@@ -0,0 +1,96 @@
+# JWT Authentication
+
+HarperDB introduced Token based authentication in version 2.3.0 with JWTs.


I dont think we need this line anymore

DavidCockerill · 2022-10-17T20:42:35Z

+
+## Token Expiration
+
+`operation_token` expires at a set interval. Once it expires it will no longer be accepted by HarperDB. This duration defaults to one day, and is configurable in [harperdb.conf](https://harperdb.io/docs/reference/configuration-file/). To generate a new `operation_token`, the `refresh_operation_token` operation is used, passing the `refresh_token` in the Bearer Token Authorization Header. A full cURL example can be seen here:


config file is now harperdb-config.yaml

DavidCockerill · 2022-10-17T20:43:25Z

+}
+```
+
+The `refresh_token` also expires at a set interval, but a longer interval. Once it expires it will no longer be accepted by HarperDB. This duration defaults to thirty days, and is configurable in [harperdb.conf](https://harperdb.io/docs/reference/configuration-file/). To generate a new `operation_token` and a new `refresh_token` the `create_authentication_tokensoperation` is called.


update config file name

DavidCockerill · 2022-10-17T20:43:55Z

+
+Token timeouts are configurable in [harperdb.conf](https://harperdb.io/docs/reference/configuration-file/) with the following parameters:
+
+* `OPERATION_TOKEN_TIMEOUT`: Defines the length of time until the operation_token expires (default 1d).


these params are from old config

DavidCockerill · 2022-10-17T20:45:07Z

@@ -0,0 +1,282 @@
+# Users & Roles
+
+*Role Permissions documentation below for HarperDB version 2.2.0 and above.*


I dont think you need this line, we are way past 2.2.0

kriszyp · 2022-10-17T21:17:04Z

@@ -0,0 +1,64 @@
+# Authentication
+
+HarperDB utilizes Basic Auth to secure our REST requests.  In the context of an HTTP transaction, **basic access authentication** is a method for an HTTP user agent to provide a user name and password when making a request.


"our REST requests" -> "our HTTP requests"

kriszyp · 2022-10-17T21:17:29Z

+
+
+
+A header is added to each REST request.  The header key is **“Authorization”** the header value is **“Basic <<your username and password buffer token>>”**


"each REST request" -> "each HTTP request"
Same with rest of the doc, won't tag each one.

kriszyp · 2022-10-17T21:21:23Z

+
+## Using HarperDB Studio
+
+Below is a code sample from HarperDB Studio.  On Line 14 you will see where we are adding the authorization header to each request.  Again this needs to be added for each and every REST request for HarperDB.


Can we literally just include line 14? Also, that line is node specific. The appropriate cross-platform code for the header is (that should work in browsers):
{ Authorization: "Basic " + btoa(username + ':' + password) }

I can see using the whole function for context (simplified and modernized); I can also see using a cross-platform approach and just using line 14. This whole page needs to be rewritten; I wasn't aware of that until after I sent this PR. With the rewrite, I will solve this issue.

kriszyp · 2022-10-17T21:22:13Z

+
+## CORS
+
+HarperDB allows for managing [cross-origin HTTP requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS). By default, HarperDB enables CORS for all domains if you need to disable CORS completely or set up whitelisted domains you can do the following:


"set up whitelisted domains" -> "set up an access list of domains"

kriszyp · 2022-10-17T21:23:41Z

+
+
+
+These default ports can be changed by updating the `operationsApi.network.port` value in `HDB_ROOT/harperdb.config`


HDB_ROOT/harperdb.config -> HDB_ROOT/harperdb-config.yaml

Change the root var here also

kriszyp · 2022-10-17T21:26:20Z

+
+
+
+By default, HTTPS is turned off and HTTP is turned on.


By default, HTTPS is turned off and HTTP is turned on. However, it is recommended that you never directly expose HarperDB's HTTP interface through a publicly available port. HTTP is intended for local or private network use.

kriszyp · 2022-10-17T21:28:58Z

@@ -1 +1,9 @@
 # Security
+
+HarperDB uses role-based, attribute-level security to ensure that users can only gain access to the data they’re supposed to be able to access. Our granular permissions allow for unparalleled flexibility and control, and can actually lower the Total Cost of Ownership compared to other database solutions, since you no longer have to replicate subsets of your data to isolate use cases.


I understand the effort to emphasize TCO, but total cost of ownership really isn't a proper noun, I don't think (shouldn't be capitalized).

kriszyp · 2022-10-17T21:42:04Z

+
+
+
+**Database Manipulation**:  A role defines CRUD permissions against database resources (i.e. data) in a HarperDB instance.


Probably define acronym on first use: "create, read, update, and delete (CRUD)"

kriszyp · 2022-10-17T21:56:23Z

+
+* `role` name used to easily identify the role assigned to individual users.
+
+    *Important: starting with 3.0, roles are assigned to users and altered/dropped based on the role name used in and returned from a successful `add_role` , `alter_role`, or `list_roles` operation.*


How far back do we have to mention "starting with"?

kriszyp · 2022-10-17T21:56:34Z

+
+Example JSON for `add_role` request
+
+```bash


probably json, not bash.

* added mac, added/updated windows, added/updated node version requirements, and added offline docs * go requirements * docs adjustments * testing variable usage * testing variable usage * Update other.md Update installation for other operating systems. * added link to download * node version * exact replica download button * functional download link * deleted old link * node version Co-authored-by: Kris Zyp <kriszyp@gmail.com>

* added mac, added/updated windows, added/updated node version requirements, and added offline docs * 1/3 through studio subtopics * 2/3 through studio subtopics * 3/3 through studio subtopics * corrected harperdb operations api * removed icon descriptions and fixed typos * removed icon descriptions * primary key vs hash_attribute change * primary key vs hash attribute qualifier

* testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * testing variable syntax * reverted changes from variable testing * added diagrams and clustering docs * more formatting * formatted the rest of clustering docs * Core 1828 Docs Migration- Security: Topic and Subtopics (#4) * doc migration epic branch * 3/4 progress of security * finished configuration.md, began users and roles * users and roles migrated; still needs updates * updated user and roles operations * corrections to security docs * CORE-1825 Add/Update "install harpedb" subtopics (#1) * added mac, added/updated windows, added/updated node version requirements, and added offline docs * go requirements * docs adjustments * testing variable usage * testing variable usage * Update other.md Update installation for other operating systems. * added link to download * node version * exact replica download button * functional download link * deleted old link * node version Co-authored-by: Kris Zyp <kriszyp@gmail.com> * Core 1826 add/update harperdb studio topic and subtopics (#2) * added mac, added/updated windows, added/updated node version requirements, and added offline docs * 1/3 through studio subtopics * 2/3 through studio subtopics * 3/3 through studio subtopics * corrected harperdb operations api * removed icon descriptions and fixed typos * removed icon descriptions * primary key vs hash_attribute change * primary key vs hash attribute qualifier * minor change to example function Co-authored-by: Kris Zyp <kriszyp@gmail.com> * added more context to clustering intro page; adjusted subscription behavior description Co-authored-by: Kris Zyp <kriszyp@gmail.com>

terraHDB added 5 commits September 26, 2022 10:28

doc migration epic branch

a9ebc34

3/4 progress of security

baa7f40

finished configuration.md, began users and roles

f4af55e

users and roles migrated; still needs updates

9559939

updated user and roles operations

ab9e432

terraHDB requested review from DavidCockerill, deliciousmonster, kriszyp and kylebernhardy October 6, 2022 21:59

DavidCockerill reviewed Oct 17, 2022

View reviewed changes

kriszyp reviewed Oct 17, 2022

View reviewed changes

corrections to security docs

303e35f

terraHDB marked this pull request as draft October 20, 2022 15:54

terraHDB and others added 4 commits October 28, 2022 15:31

Merge branch 'CORE-1824' into CORE-1828

c3cba50

minor change to example function

55ab36e

terraHDB marked this pull request as ready for review November 14, 2022 22:53

DavidCockerill merged commit 81c7630 into main Nov 15, 2022

Ethan-Arrowood deleted the CORE-1828 branch August 12, 2025 17:20

		@@ -0,0 +1,64 @@
		# Authentication

		HarperDB utilizes Basic Auth to secure our REST requests. In the context of an HTTP transaction, basic access authentication is a method for an HTTP user agent to provide a user name and password when making a request.


		1) Open the HarperDB harperdb.config file this can be found in /HDB_ROOT, the location you specified during install.

		2) In harperdb.config there should be 2 entries under `operationsApi.network`: cors and corsWhitelist.




		HarperDB automatically generates a certificate and a privateKey file which live at `HDB_ROOT/keys/`.

		@@ -0,0 +1,96 @@
		# JWT Authentication

		HarperDB introduced Token based authentication in version 2.3.0 with JWTs.


		## Token Expiration

		`operation_token` expires at a set interval. Once it expires it will no longer be accepted by HarperDB. This duration defaults to one day, and is configurable in [harperdb.conf](https://harperdb.io/docs/reference/configuration-file/). To generate a new `operation_token`, the `refresh_operation_token` operation is used, passing the `refresh_token` in the Bearer Token Authorization Header. A full cURL example can be seen here:


		Token timeouts are configurable in [harperdb.conf](https://harperdb.io/docs/reference/configuration-file/) with the following parameters:

		* `OPERATION_TOKEN_TIMEOUT`: Defines the length of time until the operation_token expires (default 1d).

		@@ -0,0 +1,282 @@
		# Users & Roles

		Role Permissions documentation below for HarperDB version 2.2.0 and above.




		A header is added to each REST request. The header key is “Authorization” the header value is “Basic <<your username and password buffer token>>”


		## Using HarperDB Studio

		Below is a code sample from HarperDB Studio. On Line 14 you will see where we are adding the authorization header to each request. Again this needs to be added for each and every REST request for HarperDB.


		## CORS

		HarperDB allows for managing [cross-origin HTTP requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS). By default, HarperDB enables CORS for all domains if you need to disable CORS completely or set up whitelisted domains you can do the following:




		These default ports can be changed by updating the `operationsApi.network.port` value in `HDB_ROOT/harperdb.config`

		@@ -1 +1,9 @@
		# Security

		HarperDB uses role-based, attribute-level security to ensure that users can only gain access to the data they’re supposed to be able to access. Our granular permissions allow for unparalleled flexibility and control, and can actually lower the Total Cost of Ownership compared to other database solutions, since you no longer have to replicate subsets of your data to isolate use cases.




		Database Manipulation: A role defines CRUD permissions against database resources (i.e. data) in a HarperDB instance.


		* `role` name used to easily identify the role assigned to individual users.

		Important: starting with 3.0, roles are assigned to users and altered/dropped based on the role name used in and returned from a successful `add_role` , `alter_role`, or `list_roles` operation.

Uh oh!

Conversation

terraHDB commented Oct 6, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!