Cext 5791 - IMS authentication for ABDB

src/pages/config.md

@@ -90,8 +90,8 @@
                 - [State and Files](guides/app_builder_guides/storage/application-state.md)
                 - [Database (Beta)](guides/app_builder_guides/storage/database.md)
                     - [aio app db Commands](guides/app_builder_guides/storage/db-commands.md)
-                    - [MongoDB Compatibility](guides/app_builder_guides/storage/db-mongo-compatibility.md)
                     - [Runtime Actions](guides/app_builder_guides/storage/db-runtime-actions.md)
+                    - [MongoDB Compatibility](guides/app_builder_guides/storage/db-mongo-compatibility.md)
                     - [Best Practices](guides/app_builder_guides/storage/db-best-practices.md)
             - [Telemetry](guides/app_builder_guides/telemetry.md) 
         - [Runtime Guides](guides/runtime_guides/index.md) 

src/pages/guides/app_builder_guides/index.md

@@ -17,7 +17,7 @@ Welcome to the App Builder Guides section. Here you'll find comprehensive docume
 * [Development](development.md)
 * [Distribution](distribution.md)
 * [Optimization](optimization.md)
-* [Storage](./storage/application-state.md)
+* [Storage](./storage/index.md)
 * [Telemetry](telemetry.md)
 
 ## Configuration and Deployment

src/pages/guides/app_builder_guides/storage/database.md

@@ -18,6 +18,12 @@ Database Storage for App Builder provides document-style database persistence fo
 
 There is a strict one-to-one relationship between an AIO project workspace and a workspace database, and each workspace database is entirely isolated from all other workspace databases.
 
+## App Builder Data Services API
+
+In order to use App Builder Database Storage in an AIO project workspace, you must add the **App Builder Data Services** API, which provides the necessary authentication between runtime actions and the App Builder Database Storage service.
+
+You can add the **App Builder Data Services** API in the developer console like any other API. It does not require any special license or subscription beyond the App Builder license.
+
 ## Provision a workspace database
 
 Before using Database Storage in an AIO project workspace, a workspace database must be provisioned. This is a self-service operation requiring no special permissions.
@@ -79,13 +85,48 @@ Run the following command in the root of your AIO project workspace to install t
 npm install @adobe/aio-lib-db
 ```
 
+### Initialization and authentication
+
+You must always initialize **aio-lib-db** with an IMS Access Token. The simplest way to generate a token is by using the **@adobe/aio-sdk** library as demonstrated in the following example:
+
+```javascript
+const {generateAccessToken} = require('@adobe/aio-sdk').Core.AuthClient;
+const libDb = require('@adobe/aio-lib-db');
+
+async function main(params) {
+  const token = await generateAccessToken(params);
+  const db = await libDb.init({token: token.access_token});
+}
+```
+
+This example has the following requirements:
+
+- The AIO project workspace must include the **App Builder Data Services** API. See [App Builder Data Services API](#app-builder-data-services-api) for details.
+- The `include-ims-credentials` annotation for the runtime action must be set to `true` in the `app.config.yaml` application manifest.
+
+The `include-ims-credentials` annotation will look similar to the following example:
+
+```yaml
+  actions:
+    action:
+      function: actions/generic/action.js
+      annotations:
+        include-ims-credentials: true
+```
+
+The **@adobe/aio-sdk** library transparently manages caching and refreshing tokens as needed, so you do not need to implement caching or refreshing tokens yourself.
+
 ### Region selection
 
 **aio-lib-db** must be initialized in the region the workspace database was provisioned. Otherwise, the connection will fail.
 
-To explicitly initialize the library in a specific region, pass the `{region: "<region>"}` arguement to the `libDb.init()` method.
+To explicitly initialize the library in a specific region, pass the `{region: "<region>"}` argument to the `libDb.init()` method.
+
+Called without an explicit region, `libDb.init()` will initialize the library either in the default `amer` region or in the region defined in the `AIO_DB_REGION` environment variable.
+
+### General use
 
-Called with no arguments, `libDb.init()` will initialize the library either in the default `amer` region or in the region defined in the `AIO_DB_REGION` environment variable.
+Using `aio-lib-db` in a runtime action is documented at [Runtime actions with Database Storage](./db-runtime-actions.md).
 
 ## Usage quotas and limits
 

src/pages/guides/app_builder_guides/storage/db-commands.md

@@ -18,11 +18,18 @@ The following is only a brief introduction to the DB Plugin. For more thorough d
 
 ## Installation
 
-To install the pre-GA plugin for the AIO CLI:
+The DB plugin for the AIO CLI requires `@adobe/aio-cli-plugin-app` version 14.5.1 or higher and `@adobe/aio-cli-plugin-app-storage` version 1.3.0 or higher.
 
+These are install automatically by updating `@adobe/aio-cli` to the latest version:
 ```bash
-aio plugins:install @adobe/aio-cli-plugin-app@next
-aio plugins:install @adobe/aio-cli-plugin-app-storage@next
+npm install -g @adobe/aio-cli
+```
+
+In case you installed the pre-GA plugin during early access, these should be uninstalled before updating `@adobe/aio-cli`:
+
+```bash
+aio plugins:uninstall @adobe/aio-cli-plugin-app
+aio plugins:uninstall @adobe/aio-cli-plugin-app-storage
 ```
 
 ## Region selection

src/pages/guides/app_builder_guides/storage/db-runtime-actions.md

@@ -19,17 +19,21 @@ Connecting to App Builder Database Storage is where `aio-lib-db` most differs fr
 The following is the general pattern for loading and using `aio-lib-db`:
 
 ```javascript
-const libDb = require('@adobe/aio-lib-db')
+const {generateAccessToken} = require('@adobe/aio-sdk').Core.AuthClient;
+const libDb = require('@adobe/aio-lib-db');
 
-async function main() {
+async function main(params) {
   let client
   try {
 
+    // Generate IMS access token
+    const token = await generateAccessToken(params);
+
     // Implicit region initialization
-    const db = await libDb.init()
-      
+    const db = await libDb.init({token: token.access_token})
+
     // Explicit region initialization
-    // const db = await libDb.init({region: "emea"})
+    // const db = await libDb.init({token: token.access_token, region: "emea"})
 
     // Set up a connection
     client = await db.connect()
@@ -57,8 +61,8 @@ async function main() {
 
 A few things to note in comparison with the MongoDB Node Driver:
 
-- You do not need to specify connection credentials because they are taken from the runtime context, specifically the runtime namespace and auth.
 - You do not need to specify the database URL because all requests go through the App Builder Storage Database Service.
+- Authentication depends on IMS Tokens, which requires setting the `include-ims-credentials` flag for the runtime action. See [Initialization and Authentication](./database.md#initialization-and-authentication) for details.
 - The library must be initialized in the same region the database was provisioned in.
 - There is no option to select a different database because there is always a one-to-one relationship between an AIO Project Workspace and Workspace Database.
 

src/pages/guides/app_builder_guides/storage/index.md

@@ -191,4 +191,6 @@ npm install @adobe/aio-lib-db
 aio app db provision
 ```
 
-No additional configuration is needed. The libraries automatically use your App Builder credentials for authentication and authorization.
+For State and Files no additional configuration is needed. These libraries automatically use your App Builder credentials for authentication and authorization.
+
+The Database library does require some additional configuration, but does not require any special entitlements beyond App Builder itself. See the [App Builder Data Services API](./database.md#app-builder-data-services-api) documentation for details.