adobeGH-55 doc update

francoisledroff · Apr 1, 2022 · 6863feb · 6863feb
1 parent 43493b2
commit 6863feb
Show file tree

Hide file tree

Showing 5 changed files with 125 additions and 50 deletions.
diff --git a/aem/core_aem/README.md b/aem/core_aem/README.md
@@ -3,6 +3,60 @@
 `com.adobe.aio.aem.core` is a Java OSGI bundle hosting OSGI Components
 wrapping [`aio-lib-java-core`](../../core) and [`aio-lib-java-ims`](../../ims)
 
+## Expected `Workspace` osgi configuration
+
+This bundle expects a [`Workspace Configuration`](src/main/java/com/adobe/aio/aem/workspace/ocd/WorkspaceConfig.java)
+defined as an OSGI configuration.  
+* for more details about the `Worskspace` configuration: check our [`aio-lib-java-core` documentation](../../core/README.md).
+* for more details about the `aio.encoded.pkcs8` private key configuration: check our [`aio-lib-java-ims` documentation](../../ims/README.md)
+
+Please [choose the appropriate OSGi configuration value types](https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/implementing/deploying/configuring-osgi.html%3Flang%3Den#how-to-choose-the-appropriate-osgi-configuration-value-type), 
+use environment variables for the following:
+* `aio.consumer.org.id` 
+* `aio.ims.org.id`
+* `aio.meta.scopes`
+* `aio.project.id`
+* `aio.workspace.id`
+* `aio.api.key`
+* `aio.credential.id`
+* `aio.technical.account.id`
+
+Use secret environment variables for the following:
+* `aio.client.secret`
+* `aio.encoded.pkcs8`
+
+## Status Check
+
+This bundle comes with a status servlet: 
+ from [/bin/aio/workspace.json](http://localhost:4502/bin/aio/workspace.json)
+you can `GET` the status of your workspace configuration.
+
+If valid, the status json payload should like that :
+
+    {
+        "status": "up",
+        "details": {
+            "workspace": {
+                "imsUrl": "https://ims-na1.adobelogin.com",
+                "imsOrgId": "...@AdobeOrg",
+                "apiKey": "...",
+                "credentialId": "...",
+                "technicalAccountId": "...@techacct.adobe.com",
+                "metascopes": [
+                "...",
+                "/s/ent_adobeio_sdk"
+                ],
+                "consumerOrgId": "...",
+                "projectId": "...",
+                "workspaceId": "...",
+                "projectUrl": "https://developer.adobe.com/console/projects/.../.../overview",
+                "clientSecretDefined": true,
+                "privateKeyDefined": true
+                }
+        },
+        "error": null
+    }
+
 ## Builds
 
 This Library is build with [maven](https://maven.apache.org/)

diff --git a/core/README.md b/core/README.md
@@ -9,12 +9,26 @@ It also holds the core `Adobe Developer Console` Workspace Builder.
 This library holds a [`Workspace`](./src/main/java/com/adobe/aio/Workspace.java) POJO modeling
 your [Adobe Developer Console Project Workspace](https://www.adobe.io/apis/experienceplatform/console/docs.html#!AdobeDocs/adobeio-console/master/projects.md),
 
-To get you started quickly you could use a `.properties` file, 
-see our [sample config file](./src/test/resources/workspace.properties) and our JUnit Test
+To get you started quickly use a `.properties` file,
+* see our [sample config file](./src/test/resources/workspace.properties) in our jUnit Test.
+* download your `project` configurations file from your Adobe Developer Console Project overview page
+* map your `project` configurations with this properties
 
-For now, you have a bit of copy and paste to do, but we have a plan to streamline the process:
+For now, you do have a bit of copy and paste to do, but we have a plan to streamline the process:
 * https://github.com/adobe/aio-lib-java/issues/5
 
+The `Workspace` POJO holds your Adobe Developer Console Project configurations
+  (download your `project` configurations file from your Adobe Developer Console Project overview page):
+* `aio_project_id`  your Adobe Developer Console project id (`project.id`)
+* `aio_consumer_org_id`  your Adobe Developer Console consumer orgnaization id (`project.org.id`)
+* `aio_ims_org_id` your Adobe Developer Console IMS Organization ID (`project.org.ims_org_id`)
+* `aio_workspace_id` your Adobe Developer Console workspace Id (`project.workspace.id`)
+* `aio_credential_id` your Adobe Developer Console jwt credential id (`project.workspace.details.credentials[i].id`)
+* `aio_client_secret` your Adobe Developer Console jwt credential client secret (`project.workspace.details.credentials[i].jwt.client_secret`)
+* `aio_api_key` your Adobe Developer Console jwt credential API Key (or Client ID) (`project.workspace.details.credentials[i].jwt.client_id`)
+* `aio_meta_scopes` a comma separated list of metascopes associated with your API, see your Adobe Developer Console jwt credential metascopes (`project.workspace.details.credentials[i].jwt.meta_scopes`)
+* `aio_technical_account_id` your Adobe Developer Console jwt credential technical account id (`project.workspace.details.credentials[i].jwt.technical_account_id`)
+
 ## Builds
 
 This Library is build with [maven](https://maven.apache.org/) (it also runs the unit tests):

diff --git a/core/src/test/resources/workspace.properties b/core/src/test/resources/workspace.properties
@@ -10,24 +10,24 @@
 # governing permissions and limitations under the License.
 #
 
-# aio_meta_scopes : comma separated list of metascopes associated with your API
-# sample aio_meta_scopes: /s/ent_user_sdk,/s/ent_marketing_sdk,/s/creative_sdk
-aio_meta_scopes=aio_meta_scopes_changeMe
-# aio_ims_org_id = your IMS Organization ID as shown in your Adobe Developer Console workspace
-aio_ims_org_id=aio_ims_org_id_changeMe
-# aio_consumer_org_id = your consumer Org Id as shown in your Adobe Developer Console workspace (project.org.id)
-aio_consumer_org_id=aio_consumer_org_id_changeMe
-# aio_project_id = your project Id as shown in your Adobe Developer Console workspace (project.id)
+# aio_project_id = your Adobe Developer Console project id (project.id)
 aio_project_id=aio_project_id_changeMe
-# aio_workspace_id = your workspace Id as shown in your Adobe Developer Console workspace (project.workspace.id)
+# aio_consumer_org_id = your Adobe Developer Console consumer orgnaization id (project.org.id)
+aio_consumer_org_id=aio_consumer_org_id_changeMe
+# aio_ims_org_id = your Adobe Developer Console IMS Organization ID (project.org.ims_org_id)
+aio_ims_org_id=aio_ims_org_id_changeMe
+# aio_workspace_id = your Adobe Developer Console workspace Id (project.workspace.id)
 aio_workspace_id=aio_workspace_id_changeMe
-# aio_api_key = your credential API Key (Client ID) as shown in in your Adobe Developer Console workspace
-aio_api_key=aio_api_key_changeMe
-# aio_credential_id = your credential id as shown in your Adobe Developer Console workspace
+# aio_credential_id = your Adobe Developer Console jwt credential id (project.workspace.details.credentials[i].id)
 aio_credential_id=aio_credential_id_changeMe
-# aio_client_secret = your credential Client secret as shown in in your Adobe Developer Console workspace
+# aio_client_secret = your Adobe Developer Console jwt credential client secret (project.workspace.details.credentials[i].jwt.client_secret)
 aio_client_secret=aio_client_secret_changeMe
-# aio_technical_account_id = your credential Technical account ID as shown in your Adobe Developer Console workspace
+# aio_api_key = your Adobe Developer Console jwt credential API Key (or Client ID) (project.workspace.details.credentials[i].jwt.client_id
+aio_api_key=aio_api_key_changeMe
+# aio_meta_scopes : comma separated list of metascopes associated with your API, see your Adobe Developer Console jwt credential metascopes (project.workspace.details.credentials[i].jwt.meta_scopes)
+# sample aio_meta_scopes: /s/ent_user_sdk,/s/ent_marketing_sdk,/s/creative_sdk (project.workspace.details.credentials[i].jwt.meta_scopes)
+aio_meta_scopes=aio_meta_scopes_changeMe
+# aio_technical_account_id = your Adobe Developer Console jwt credential technical account id (project.workspace.details.credentials[i].jwt.technical_account_id)
 aio_technical_account_id=aio_technical_account_id_changeMe
 
 
diff --git a/ims/README.md b/ims/README.md
@@ -19,32 +19,11 @@ token and must be signed with the private key that is associated with a public k
 This Java library will help you implement this JWT exchange token flow, to get a valid access token
 and start interacting with the many Adobe I/O API that support such authentication.
 
-### Test Drive
-
-    PrivateKey privateKey = new PrivateKeyBuilder().systemEnv().build(); // [1]
-    Workspace workspace = Workspace.builder()
-        .systemEnv()
-        .privateKey(privateKey)
-        .build(); // [2]
-    ImsService imsService = ImsService.builder().workspace(workspace).build(); // [3]
-
-    AccessToken accessToken = imsService.getJwtExchangeAccessToken(); // [4]
-
-    // [1] Build your PrivateKey looking up the key indicated by you System Environment variables
-    // [2] build your `Workspace` (a Java POJO representation of your `Adobe Developer Console` Workspace)
-    //     looking up other System Environment variables. 
-    //     Note that our fluent workspace and private Key builders offers many ways to have your workspace configured,
-    //     we are showing here the most concise
-    // [3] build the Ims Service wrapper and have it use this workspace context
-    // [4] use this service to retrieve an access token using a jwt exchange token flow
-       
-                      
-Have a look at our [ImsService `main()` Test Drive](./src/test/java/com/adobe/aio/ims/ImsServiceTestDrive.java)
-
 ### Configurations
 
 Browse our [Service Account Integration (JWT authentication flow) doc](https://www.adobe.io/authentication/auth-methods.html#!AdobeDocs/adobeio-auth/master/AuthenticationOverview/ServiceAccountIntegration.md), 
 our fluent workspace builder offers many ways to have your `Workspace` (a Java POJO representation of your `Adobe Developer Console` Workspace) configured.
+
 To get you started quickly you could use a `.properties` file, 
 see our [sample config file](./src/test/resources/workspace.properties)
 
@@ -82,6 +61,29 @@ It can be leverage to add the authentication headers expected by many Adobe APIs
   * renewing it only when expired (after 24 hours) or when not present in memory yet
 * a `x-api-key` header matching your JWT token
 
+### Test Drive
+
+    PrivateKey privateKey = new PrivateKeyBuilder().systemEnv().build(); // [1]
+    Workspace workspace = Workspace.builder()
+        .systemEnv()
+        .privateKey(privateKey)
+        .build(); // [2]
+    ImsService imsService = ImsService.builder().workspace(workspace).build(); // [3]
+
+    AccessToken accessToken = imsService.getJwtExchangeAccessToken(); // [4]
+
+    // [1] Build your PrivateKey looking up the key indicated by you System Environment variables
+    // [2] build your `Workspace` (a Java POJO representation of your `Adobe Developer Console` Workspace)
+    //     looking up other System Environment variables. 
+    //     Note that our fluent workspace and private Key builders offers many ways to have your workspace configured,
+    //     we are showing here the most concise
+    // [3] build the Ims Service wrapper and have it use this workspace context
+    // [4] use this service to retrieve an access token using a jwt exchange token flow
+
+
+Have a look at our [ImsService `main()` Test Drive](./src/test/java/com/adobe/aio/ims/ImsServiceTestDrive.java)
+
+
 ## Builds
 
 This Library is build with [maven](https://maven.apache.org/) (it also runs the unit tests):

diff --git a/ims/src/test/resources/workspace.properties b/ims/src/test/resources/workspace.properties
@@ -10,21 +10,26 @@
 # governing permissions and limitations under the License.
 #
 
-# meta_scopes : comma separated list of metascopes associated with your API
-# sample meta_scopes: /s/ent_user_sdk,/s/ent_marketing_sdk,/s/creative_sdk
-aio_meta_scopes=aio_meta_scopes_changeMe
-# ims_org_id = your IMS Organization ID as shown in your Adobe Developer Console workspace
-aio_ims_org_id=aio_ims_org_id_changeMe
-# consumer_org_id = your consumer Org Id as shown in your Adobe Developer Console workspace
+# aio_project_id = your Adobe Developer Console project id (project.id)
+aio_project_id=aio_project_id_changeMe
+# aio_consumer_org_id = your Adobe Developer Console consumer orgnaization id (project.org.id)
 aio_consumer_org_id=aio_consumer_org_id_changeMe
-# api_key = your credential API Key (Client ID) as shown in in your Adobe Developer Console workspace
-aio_api_key=aio_api_key_changeMe
-# credential_id = your credential id as shown in your Adobe Developer Console workspace
+# aio_ims_org_id = your Adobe Developer Console IMS Organization ID (project.org.ims_org_id)
+aio_ims_org_id=aio_ims_org_id_changeMe
+# aio_workspace_id = your Adobe Developer Console workspace Id (project.workspace.id)
+aio_workspace_id=aio_workspace_id_changeMe
+# aio_credential_id = your Adobe Developer Console jwt credential id (project.workspace.details.credentials[i].id)
 aio_credential_id=aio_credential_id_changeMe
-# client_secret = your credential Client secret as shown in in your Adobe Developer Console workspace
+# aio_client_secret = your Adobe Developer Console jwt credential client secret (project.workspace.details.credentials[i].jwt.client_secret)
 aio_client_secret=aio_client_secret_changeMe
-# technical_account_id = your credential Technical account ID as shown in your Adobe Developer Console workspace
+# aio_api_key = your Adobe Developer Console jwt credential API Key (or Client ID) (project.workspace.details.credentials[i].jwt.client_id
+aio_api_key=aio_api_key_changeMe
+# aio_meta_scopes : comma separated list of metascopes associated with your API, see your Adobe Developer Console jwt credential metascopes (project.workspace.details.credentials[i].jwt.meta_scopes)
+# sample aio_meta_scopes: /s/ent_user_sdk,/s/ent_marketing_sdk,/s/creative_sdk (project.workspace.details.credentials[i].jwt.meta_scopes)
+aio_meta_scopes=aio_meta_scopes_changeMe
+# aio_technical_account_id = your Adobe Developer Console jwt credential technical account id (project.workspace.details.credentials[i].jwt.technical_account_id)
 aio_technical_account_id=aio_technical_account_id_changeMe
+
 # You then have 3 options to configure the privateKey (associated with the public key set in your Adobe Developer Console workspace):
 # * Option 1: use a pcks8 file (using the `aio_pkcs8_file_path` config)
 # * Option 2: use base 64 encoded pcks8 key (using the `aio_encoded_pkcs8` config)