deploy.md

title	description	ms.date	ms.topic	ms.reviewer	ms.custom
Deploy Azure Blockchain Workbench Preview	How to deploy Azure Blockchain Workbench Preview	02/18/2022	how-to	ravastra	references_regions

Deploy Azure Blockchain Workbench Preview

[!INCLUDE Retirement note]

Azure Blockchain Workbench Preview is deployed using a solution template in the Azure Marketplace. The template simplifies the deployment of components needed to create blockchain applications. Once deployed, Blockchain Workbench provides access to client apps to create and manage users and blockchain applications.

For more information about the components of Blockchain Workbench, see Azure Blockchain Workbench architecture.

[!INCLUDE Preview note]

Prepare for deployment

Blockchain Workbench allows you to deploy a blockchain ledger along with a set of relevant Azure services most often used to build a blockchain-based application. Deploying Blockchain Workbench results in the following Azure services being provisioned within a resource group in your Azure subscription.

• App Service Plan (Standard)
• Application Insights
• Event Grid
• Azure Key Vault
• Service Bus
• SQL Database (Standard S0)
• Azure Storage account (Standard LRS)
• Virtual machine scale set with capacity of 1
• Virtual Network resource group (with Load Balancer, Network Security Group, Public IP Address, Virtual Network)
• Azure Blockchain Service. If you are using a previous Blockchain Workbench deployment, consider redeploying Azure Blockchain Workbench to use Azure Blockchain Service.

The following is an example deployment created in myblockchain resource group.

The cost of Blockchain Workbench is an aggregate of the cost of the underlying Azure services. Pricing information for Azure services can be calculated using the pricing calculator.

Prerequisites

Azure Blockchain Workbench requires Azure AD configuration and application registrations. You can choose to do the Azure AD configurations manually before deployment or run a script post deployment. If you are redeploying Blockchain Workbench, see Azure AD configuration to verify your Azure AD configuration.

Important

Workbench does not have to be deployed in the same tenant as the one you are using to register an Azure AD application. Workbench must be deployed in a tenant where you have sufficient permissions to deploy resources. For more information on Azure AD tenants, see How to get an Active Directory tenant and Integrating applications with Azure Active Directory.

Deploy Blockchain Workbench

Once the prerequisite steps have been completed, you are ready to deploy the Blockchain Workbench. The following sections outline how to deploy the framework.

1. Sign in to the Azure portal.

2. Select your account in the top-right corner, and switch to the desired Azure AD tenant where you want to deploy Azure Blockchain Workbench.

3. Select Create a resource in the upper left-hand corner of the Azure portal.

4. Select Blockchain > Azure Blockchain Workbench (preview).

   

   Setting	Description
   Resource prefix	Short unique identifier for your deployment. This value is used as a base for naming resources.
   VM user name	The user name is used as administrator for all virtual machines (VM).
   Authentication type	Select if you want to use a password or key for connecting to VMs.
   Password	The password is used for connecting to VMs.
   SSH	Use an RSA public key in the single-line format beginning with ssh-rsa or use the multi-line PEM format. You can generate SSH keys using ssh-keygen on Linux and OS X, or by using PuTTYGen on Windows. More information on SSH keys, see How to use SSH keys with Windows on Azure.
   Database and Blockchain password	Specify the password to use for access to the database created as part of the deployment. The password must meet three of the following four requirements: length needs to be between 12 & 72 characters, 1 lower case character, 1 upper case character, 1 number, and 1 special character that is not number sign(#), percent(%), comma(,), star(*), back quote(`), double quote("), single quote('), dash(-) and semicolumn(;)
   Deployment region	Specify where to deploy Blockchain Workbench resources. For best availability, this should match the Region location setting. Not all regions are available during preview. Features may not be available in some regions. Azure Blockchain Data Manager is available in the following Azure regions: East US and West Europe.
   Subscription	Specify the Azure Subscription you wish to use for your deployment.
   Resource groups	Create a new Resource group by selecting Create new and specify a unique resource group name.
   Location	Specify the region you wish to deploy the framework.

5. Select OK to finish the basic setting configuration section.

6. In Advanced Settings, choose the existing Ethereum proof-of-authority blockchain network, Active Directory settings, and preferred VM size for Blockchain Workbench components.

   The Ethereum RPC endpoint has the following requirements:

   • The endpoint must be an Ethereum Proof-of-Authority (PoA) blockchain network.

   • The endpoint must be publicly accessible over the network.

   • The PoA blockchain network should be configured to have gas price set to zero.

   • The endpoint starts with https:// or http:// and ends with a port number. For example, http<s>://<network-url>:<port>

     [!NOTE] Blockchain Workbench accounts are not funded. If funds are required, the transactions fail.

     

     Setting	Description
     Ethereum RPC Endpoint	Provide the RPC endpoint of an existing PoA blockchain network.
     Azure Active Directory settings	Choose Add Later. Note: If you chose to pre-configure Azure AD or are redeploying, choose to Add Now.
     VM selection	Select preferred storage performance and VM size for your blockchain network. Choose a smaller VM size such as Standard DS1 v2 if you are on a subscription with low service limits like Azure free tier.

7. Select Review + create to finish Advanced Settings.

8. Review the summary to verify your parameters are accurate.

   

9. Select Create to agree to the terms and deploy your Azure Blockchain Workbench.

The deployment can take up to 90 minutes. You can use the Azure portal to monitor progress. In the newly created resource group, select Deployments > Overview to see the status of the deployed artifacts.

Important

Post deployment, you need to complete Active Directory settings. If you chose Add Later, you need to run the Azure AD configuration script. If you chose Add now, you need to configure the Reply URL.

Blockchain Workbench web URL

Once the deployment of the Blockchain Workbench has completed, a new resource group contains your Blockchain Workbench resources. Blockchain Workbench services are accessed through a web URL. The following steps show you how to retrieve the web URL of the deployed framework.

1. Sign in to the Azure portal.

2. In the left-hand navigation pane, select Resource groups.

3. Choose the resource group name you specified when deploying Blockchain Workbench.

4. Select the TYPE column heading to sort the list alphabetically by type.

5. There are two resources with type App Service. Select the resource of type App Service without the "-api" suffix.

   

6. In the App Service Overview, copy the URL value, which represents the web URL to your deployed Blockchain Workbench.

   

To associate a custom domain name with Blockchain Workbench, see configuring a custom domain name for a web app in Azure App Service using Traffic Manager.

Azure AD configuration script

Azure AD must be configured to complete your Blockchain Workbench deployment. You'll use a PowerShell script to do the configuration.

1. In a browser, navigate to the Blockchain Workbench Web URL.

2. You'll see instructions to set up Azure AD using Cloud Shell. Copy the command and launch Cloud Shell.

   

3. Choose the Azure AD tenant where you deployed Blockchain Workbench.

4. In Cloud Shell PowerShell environment, paste and run the command.

5. When prompted, enter the Azure AD tenant you want to use for Blockchain Workbench. This will be the tenant containing the users for Blockchain Workbench.

   [!IMPORTANT] The authenticated user requires permissions to create Azure AD application registrations and grant delegated application permissions in the tenant. You may need to ask an administrator of the tenant to run the Azure AD configuration script or create a new tenant.

   

6. You'll be prompted to authenticate to the Azure AD tenant using a browser. Open the web URL in a browser, enter the code, and authenticate.

   

7. The script outputs several status messages. You get a SUCCESS status message if the tenant was successfully provisioned.

8. Navigate to the Blockchain Workbench URL. You are asked to consent to grant read permissions to the directory. This allows the Blockchain Workbench web app access to the users in the tenant. If you are the tenant administrator, you can choose to consent for the entire organization. This option accepts consent for all users in the tenant. Otherwise, each user is prompted for consent on first use of the Blockchain Workbench web application.

9. Select Accept to consent.

   

10. After consent, the Blockchain Workbench web app can be used.

You have completed your Azure Blockchain Workbench deployment. See Next steps for suggestions to get started using your deployment.

Azure AD configuration

If you choose to manually configure or verify Azure AD settings prior to deployment, complete all steps in this section. If you prefer to automatically configure Azure AD settings, use Azure AD configuration script after you deploy Blockchain Workbench.

Blockchain Workbench API app registration

Blockchain Workbench deployment requires registration of an Azure AD application. You need an Azure Active Directory (Azure AD) tenant to register the app. You can use an existing tenant or create a new tenant. If you are using an existing Azure AD tenant, you need sufficient permissions to register applications, grant Graph API permissions, and allow guest access within an Azure AD tenant. If you do not have sufficient permissions in an existing Azure AD tenant, create a new tenant.

1. Sign in to the Azure portal.

2. Select your account in the top-right corner, and switch to the desired Azure AD tenant. The tenant should be the subscription admin's tenant of the subscription where Azure Blockchain Workbench is deployed and you have sufficient permissions to register applications.

3. In the left-hand navigation pane, select the Azure Active Directory service. Select App registrations > New registration.

   

4. Provide a display Name and choose Accounts in this organizational directory only.

   

5. Select Register to register the Azure AD application.

Modify manifest

Next, you need to modify the manifest to use application roles within Azure AD to specify Blockchain Workbench administrators. For more information about application manifests, see Azure Active Directory application manifest.

1. A GUID is required for the manifest. You can generate a GUID using the PowerShell command [guid]::NewGuid() or New-GUID cmdlet. Another option is to use a GUID generator website.

2. For the application you registered, select Manifest in the Manage section.

3. Next, update the appRoles section of the manifest. Replace "appRoles": [] with the provided JSON. Be sure to replace the value for the id field with the GUID you generated.

   "appRoles": [
        {
          "allowedMemberTypes": [
            "User",
            "Application"
          ],
          "displayName": "Administrator",
          "id": "<A unique GUID>",
          "isEnabled": true,
          "description": "Blockchain Workbench administrator role allows creation of applications, user to role assignments, etc.",
          "value": "Administrator"
        }
      ],

   [!IMPORTANT] The value Administrator is needed to identify Blockchain Workbench administrators.

4. In the manifest, also change the Oauth2AllowImplicitFlow value to true.

   "oauth2AllowImplicitFlow": true,

5. Select Save to save the manifest changes.

Add Graph API required permissions

The API application needs to request permission from the user to access the directory. Set the following required permission for the API application:

1. In the Blockchain API app registration, select API permissions. By default, the Graph API User.Read permission is added.

2. The Workbench application requires read access to users' basic profile information. In Configured permissions, select Add a permission. In Microsoft APIs, select Microsoft Graph.

3. Since the Workbench application uses the authenticated user credentials, select Delegated permissions.

4. In the User category, choose User.ReadBasic.All permission.

   

   Select Add permissions.

5. In Configured permissions, select Grant admin consent for the domain then select Yes for the verification prompt.

   

   Granting permission allows Blockchain Workbench to access users in the directory. The read permission is required to search and add members to Blockchain Workbench.

Get application ID

The application ID and tenant information are required for deployment. Collect and store the information for use during deployment.

1. For the application you registered, select Overview.

2. Copy and store the Application ID value for later use during deployment.

   

   Setting to store	Use in deployment
   Application (client) ID	Azure Active Directory setup > Application ID

Get tenant domain name

Collect and store the Active Directory tenant domain name where the applications are registered.

In the left-hand navigation pane, select the Azure Active Directory service. Select Custom domain names. Copy and store the domain name.

Guest user settings

If you have guest users in your Azure AD tenant, follow the additional steps to ensure Blockchain Workbench user assignment and management works properly.

1. Switch you your Azure AD tenant and select Azure Active Directory > User settings > Manage external collaboration settings.
2. Set Guest user permissions are limited to No.

Configuring the reply URL

Once the Azure Blockchain Workbench has been deployed, you have to configure the Azure Active Directory (Azure AD) client application Reply URL of the deployed Blockchain Workbench web URL.

1. Sign in to the Azure portal.

2. Verify you are in the tenant where you registered the Azure AD client application.

3. In the left-hand navigation pane, select the Azure Active Directory service. Select App registrations.

4. Select the Azure AD client application you registered in the prerequisite section.

5. Select Authentication.

6. Specify the main web URL of the Azure Blockchain Workbench deployment you retrieved in the Blockchain Workbench web URL section. The Reply URL is prefixed with https://. For example, https://myblockchain2-7v75.azurewebsites.net

   

7. In the Advanced setting section, check Access tokens and ID tokens.

   

8. Select Save to update the client registration.

Remove a deployment

When a deployment is no longer needed, you can remove a deployment by deleting the Blockchain Workbench resource group.

1. In the Azure portal, navigate to Resource group in the left navigation pane and select the resource group you want to delete.

2. Select Delete resource group. Verify deletion by entering the resource group name and select Delete.

   

Next steps

In this how-to article, you deployed Azure Blockchain Workbench. To learn how to create a blockchain application, continue to the next how-to article.

[!div class="nextstepaction"] Create a blockchain application in Azure Blockchain Workbench