new push

joshhus · Dec 14, 2018 · 3e40165 · 3e40165
1 parent 3040860
commit 3e40165
Show file tree

Hide file tree

Showing 38 changed files with 2,063 additions and 329 deletions.
diff --git a/FAQ.md b/FAQ.md
@@ -19,23 +19,35 @@ Before contacting Blockchain Document Store support, you can search the
 FAQs below. You can also review the [Troubleshooting](troubleshooting.md)
 information, which includes error messages and corrective actions.
 
+FAQs: [APIs](APIs) | [Tokens](Tokens) |
+
 ----------
 
-**APIs**: What **APIs** are available for me to interact with the service and network?
+## APIs
+
+**Q:** What **APIs** are available for me to interact with the service and network?
 
-To initiate, join or manage an IBM Blockchain Solution on IBM Cloud (various levels of
+**A:** To initiate, join or manage an IBM Blockchain Solution on IBM Cloud (various levels of
 administrator access required):
 [Blockchain Solution Manager API ![External link icon](images/launch-glyph.svg "External link icon")](https://dev.pbsa-dev1.us-south.containers.mybluemix.net/onboarding/swagger/#/){:new_window}.
 
-To manage documents with Blockchain Document Store:
+**A:** To manage documents with Blockchain Document Store:
 [Blockchain Document Store API ![External link icon](images/launch-glyph.svg "External link icon")](https://stage.pbsa-dev1.us-south.containers.mybluemix.net/docstore/swagger-ui.html.){:new_window}.
 
 ----------
 
+## Tokens
+
+**Q:** How do I exchange a Cloud IAM token for a service Onboarding token?
+
+**A:** 
+
+----------
+
 **Users**: How do I add a new user to an instance of Blockchain Document Store?
 
 **Add a human user**: Log in, with **Organization Administrator** access, to the
-applicable solution and channel. Then initiate a PUT call to the **/v1/organizations/{organizationId}/users** endpoint,
+applicable solution<!-- and channel -->. Then initiate a PUT call to the **/v1/organizations/{organizationId}/users** endpoint,
 at https://dev.pbsa-dev1.us-south.containers.mybluemix.net/onboarding/swagger/#/Users.
 
 **Add a system user**: Log in, with **Organization Administrator** access, to the

diff --git a/about-federated.md b/about-federated.md
@@ -0,0 +1,37 @@
+---
+
+copyright:
+  years: 2018
+lastupdated: "2018-11-27"
+
+---
+
+{:new_window: target="_blank"}
+{:shortdesc: .shortdesc}
+{:screen: .screen}
+{:codeblock: .codeblock}
+{:pre: .pre}
+
+# About federated solutions
+The **IBM Blockchain Document Store** service enables organizations to run federated
+instances of any IBM Blockchain Solution. A federated instance is essentially a clone
+of the master solution instance, which allows organizations to manage their solution
+users and applications privately and confidentially on the federated instance.
+
+Support for federated solutions facilitates what is otherwise a complex architectural
+challenge for blockchain network administrators, as follows:
+
+- A solution defined as a master instance is shared by multiple federated instances
+- A single user login provides access to all federated instances
+- Organizations within the federation store blockchain credentials on their own instance, rather than on the master.
+- Organizations can be migrated from any wallet manager in the federated solution to any other wallet manager in the federated solution
+
+Figure 1. below depicts the concept of federated solutions. The organization is
+running a clone (federated instance) of the master solution and managing users and
+applications on their federated instance.
+
+Figure 1. Federated solutions  
+![Federated solutions](images/federated-solutions.png "Federated solutions")
+
+## What's next?
+To federate an IBN Blockchain Solution, contact [Support](support.html).
diff --git a/access-app.md b/access-app.md
@@ -0,0 +1,90 @@
+---
+
+copyright:
+  years: 2018
+lastupdated: "2018-12-06"
+
+---
+
+{:new_window: target="_blank"}
+{:shortdesc: .shortdesc}
+{:screen: .screen}
+{:codeblock: .codeblock}
+{:pre: .pre}
+
+{:shortdesc}
+
+# Access as application
+
+Accessing your instance of the **Blockchain Document Store** service as an
+**application** is recommended for organizations that use a single entity, such
+as a third-party broker, to execute blockchain transactions on behalf of their
+organization. Under this **application model**, all transactions executed and recorded on
+blockchain for the organization are attributed to the broker. In this case,
+your organization must have **no** requirement for distinguishing blockchain
+transactions between individual or group user IDs.
+
+To configure access to **Blockchain Document Store** as an **application**,
+complete the following steps:
+
+1.  Using the [Blockchain Solution Manager API ![External link icon](images/launch-glyph.svg "External link icon")](https://dev.pbsa-dev1.us-south.containers.mybluemix.net/onboarding/swagger/#/UI%20OAUTH%20Login%20Flow/get_v1_logins){:new_window}, execute a **GET** call to the  *service-onboarding-basepath*/onboarding/v1/logins endpoint. Copy your Blockchain Document Store **Onboarding Token** (JSON Web Token - JWT).
+
+**Attention**: The *service-onboarding-basepath* is unique per organization; see your blockchain network service provider.  
+
+2. Using the [Blockchain Solution Manager API ![External link icon](images/launch-glyph.svg "External link icon")](https://dev.pbsa-dev1.us-south.containers.mybluemix.net/onboarding/swagger/#/Apps/put_v1_apps){:new_window}, execute a **PUT** call to the *service-onboarding-basepath*/onboarding/v1/apps endpoint, and paste your **Onboarding Token** into the **Authorization Header**.
+
+3. Create your application definition in JSON, and paste it into the **Body** of a **PATCH** call to the /onboarding/v1/apps** endpoint. For example:
+    ```
+    {
+    "applications": [
+      {
+        "appId": "string",
+        "appName": "string",
+        "roles": [
+          "SM_SOLUTION_READER"
+        ],
+        "services": [
+          {
+            "serviceId": "string",
+            "isBlockchainClient": true
+          }
+        ]
+      }
+    ]
+  }
+    ```
+
+## Query an application
+
+You can query an application to check the application definitions. To return a list
+of all defined applications, leave the appId parameter blank. For an application to
+be searchable, it must include the SM_SOLUTION_READER role definition:
+
+1. From the [Blockchain Solution Manager API ![External link icon](images/launch-glyph.svg "External link icon")](https://dev.pbsa-dev1.us-south.containers.mybluemix.net/onboarding/swagger/#/Apps/get_v1_apps){:new_window},
+execute a **GET** call to the *service-onboarding-basepath*/onboarding/v1/apps endpoint, and paste your **Onboarding Token** into the **Authorization Header**.
+
+**Attention**: The *service-onboarding-basepath* is unique per organization; see your blockchain network service provider.  
+
+2. Paste the application *appId* into the **Body** of the GET request, for example:
+    ```
+    {
+"ok": true,
+"statusCode": 0,
+"response": {
+  "appId": "string",
+  "appName": "string",
+  "roles": [
+    "SM_SOLUTION_READER"
+  ],
+  "services": [
+    {
+      "serviceId": "string",
+      "isBlockchainClient": true
+    }
+  ]
+}
+}
+    ```
+
+## What's next?
+Proceed to [Manage users](manage-users.html).
diff --git a/access-solution.md b/access-solution.md
@@ -0,0 +1,95 @@
+---
+
+copyright:
+  years: 2018
+lastupdated: "2018-12-07"
+
+---
+
+{:new_window: target="_blank"}
+{:shortdesc: .shortdesc}
+{:screen: .screen}
+{:codeblock: .codeblock}
+{:pre: .pre}
+
+{:shortdesc}
+
+# Access as solution
+
+Accessing your **Blockchain Document Store** instance as an **IBM Blockchain solution**
+is recommended for organizations that require individual, user-level attribution for
+each blockchain transaction. Under this **solution model**, each transaction recorded on
+the blockchain ledger is attributed to an authorized user of a registered organization.
+
+To configure access to **Blockchain Document Store** as an **IBM Blockchain solution**,
+complete the following steps:
+
+1.  Retrieve your service **Onboarding Token** by executing a **GET** call to the [Blockchain Solution Manager API ![External link icon](images/launch-glyph.svg "External link icon")](https://dev.pbsa-dev1.us-south.containers.mybluemix.net/onboarding/swagger/#/){:new_window} ** *service-onboarding-basepath*/onboarding/v1/logins ** endpoint. Copy your **Onboarding Token** from the returned message. **Attention**: The ** *service-onboarding-basepath* ** is unique per organization; see your blockchain network service provider.
+
+2. Using the [Blockchain Solution Manager API ![External link icon](images/launch-glyph.svg "External link icon")](https://dev.pbsa-dev1.us-south.containers.mybluemix.net/onboarding/swagger/#/Solution/patch_v1_solutions){:new_window},
+execute a **PATCH** call to the ** *service-onboarding-basepath*/onboarding/v1/solutions ** endpoint. Paste your **Onboarding Token** from Step 1 into the **Authorization Header** of the request. Continue with Step 3 to complete this **PATCH** call.
+
+3. Continuing with the same **PATCH** call from Step 2, to the ** *service-onboarding-basepath*/onboarding/v1/solutions ** endpoint, create your **solution definition JSON**, and paste it into the **Body** of the request. For example:
+    ```
+    {
+  "onboardingdata": {
+    "solution": {
+      "id": "string",
+      "name": "string",
+      "metadata": {}
+    },
+    "organizationTypes": [
+      {
+        "id": "org_id1",
+        "name": "string",
+        "solutionId": "string",
+        "onboardedBy": "string",
+        "metadata": {},
+        "roles": [
+          "role_id234"
+        ]
+      }
+    ],
+    "roles": [
+      {
+        "id": "role_id234",
+        "name": "string",
+        "solutionId": "string",
+        "onboardedBy": "string",
+        "isBlockchainRole": true,
+        "policies": {}
+      }
+    ],
+    "organizations": [
+      {
+        "id": "org_id1",
+        "name": "string",
+        "solutionId": "string",
+        "blockchainUserMode": "user | organization | role",
+        "organizationTypes": [
+          "list of organizationType Ids"
+        ],
+        "walletManagerURL": "string",
+        "metadata": {}
+      }
+    ],
+    "users": [
+      {
+        "name": "string",
+        "id": "string",
+        "userId": "user1@ibm.com",
+        "organizationId": "string",
+        "solutionId": "string",
+        "roles": [
+          "A list of role Ids"
+        ],
+        "onboardedBy": "string"
+      }
+    ]
+  }
+}
+    ```
+
+
+## What's next?
+Proceed to [Manage users](manage-users.html).
diff --git a/auth-app.md b/auth-app.md
@@ -0,0 +1,37 @@
+---
+
+copyright:
+  years: 2018
+lastupdated: "2018-12-14"
+
+---
+
+{:new_window: target="_blank"}
+{:shortdesc: .shortdesc}
+{:screen: .screen}
+{:codeblock: .codeblock}
+{:pre: .pre}
+
+
+# Application authentication
+
+The **Blockchain Document Store** service authenticates an application with an IBM Cloud IAM Service ID through the following interactions. Applications authenticate through the IBM Cloud IAM **iam.ng.bluemix.net/oidc/token** endpoint, and then exchange the returned **IBM Cloud IAM Token** for a service **Onboarding Token**, as follows:
+
+1. A **Network Administrator** <a href="register-app.html#createsvcid">creates an IBM Cloud IAM Service ID</a> for the application.
+
+2. The application Service ID authenticates through the IBM Cloud IAM **iam.ng.bluemix.net/oidc/token** endpoint, and requests an **IBM Cloud IAM Token**:
+
+    ```
+    curl -v -u "demo:demo" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$USER_API_KEY" "https://iam.ng.bluemix.net/oidc/token"   > iam.apikey.token
+    ```
+3. The application adds the returned **IBM Cloud IAM Token** to the **Authorization Header** of an API request for a service **Onboarding Token**, which it passes to Blockchain Solution Manager for verification and decoding into human-readable strings:
+    ```
+    curl -k  -H "Content-Type: application/json" --data-binary @iam.apikey.token -X POST "/v1/iam/exchange_token/apps/{appId}"
+    ```
+
+4. If verified, the application receives an **Onboarding Token** from Blockchain Solution Manager.
+
+**Note**: The default **Onboarding Token** timeout is three hours.
+
+## What's next?
+Proceed to [Manage documents](manage-documents.html).
diff --git a/auth-apps.md b/auth-apps.md
@@ -0,0 +1,57 @@
+---
+
+copyright:
+  years: 2018
+lastupdated: "2018-12-06"
+
+---
+
+{:new_window: target="_blank"}
+{:shortdesc: .shortdesc}
+{:screen: .screen}
+{:codeblock: .codeblock}
+{:pre: .pre}
+
+
+# Application authentication (programmatic)
+
+**Blockchain Solution Manager** authenticates applications only (not other system users) through
+the following interactions. Applications authenticate through the [IBM Cloud IAM endpoint ![External link icon](images/launch-glyph.svg "External link icon")](https://iam.ng.bluemix.net/oidc/token,){:new_window}
+and then exchange their **Cloud IAM Token** for a service **Onboarding Token**, as follows:
+
+1. A Solution Administrator for the organization creates a Service ID (ServiceId) for the
+application, as described previously in [Creating Service IDs](#creating-service-ids).
+
+2. The application (ServiceId) authenticates through the IBM Cloud IAM endpoint
+and requests a **Cloud IAM Token** by API key:
+    ```
+    curl -v -u "demo:demo" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$USER_API_KEY" "https://iam.ng.bluemix.net/oidc/token"   > iam.apikey.token
+    ```
+3. The application adds the received **IAM Token** to the authorization header of a
+request for an **Onboarding Token**, which it passes to Blockchain Solution Manager for
+verification and decoding into human-readable strings:
+    ```
+    curl -k  -H "Content-Type: application/json" --data-binary @iam.apikey.token -X POST "/v1/iam/exchange_token/apps/{appId}"
+    ```
+
+4. If verified, the application receives an **Onboarding Token** from Blockchain Solution Manager.
+
+5. Blockchain Document Store verifies the **Onboarding Token** by using the public key
+of Blockchain Solution Manager.
+
+6. If the **Onboarding Token** has not been altered since it was initially signed,
+verification of the identity is successful and the application can proceed to using the
+service. **Note**: The Environment Variable **DREF_TOKEN_MAX_TIMEOUT**=3h can be used to
+override the default **Reference Token** timeout of 3 hours.
+
+Applications can submit an **Onboarding Token** on behalf of another user. In
+this case, the application receives a **Reference Token**, which has a longer TTLs
+(time to live) than an **Onboarding Token**. All **Reference Tokens** are intended for
+applications to use when performing long-running transactions on behalf of a user. Only applications can use the
+**Reference Token** endpoint. **Note:** The Environment Variable **JWT_TOKEN_EXPIRES_IS**=3h
+can be used to override the default **Onboarding Token** expiration time of 3 hours.
+
+Applications can include a policy definition, via the  [/v1/apps/{appId}/policy](https://dev.pbsa-dev1.us-south.containers.mybluemix.net/onboarding/swagger/#/) endpoint, to grant access to users, roles, organizations and other applications. Any application accessing Blockchain Solution Manager must include the **SM_SOLUTION_READER** static variable.
+
+## What's next?
+Proceed to [Manage documents](manage-documents.html).