How to enable bulk self-service provisioning of Amazon WorkSpaces by using AWS Service Management Connector, AWS Service Catalog and ServiceNow Import sets

Amazon WorkSpaces is a fully-managed, secure Desktop-as-a-Service (DaaS) solution that runs on AWS. AWS provides several choices to deploy desktops to users. Some organizations need help integrating this process into their existing automation and Information Technology Service Management (ITSM) tools. Many customers that we talk to want to have a bulk provisioning process, approval process, and a tracking mechanism for their Amazon WorkSpaces process.

In this post, we’ll show you how to setup AWS Service Catalog and ServiceNow Data Source to deploy bulk WorkSpaces using the AWS Service Management Connector for ServiceNow.

The following high-level architecture diagram shows core solution components.

Figure 1. The following diagram summarizes end-user interactions. This flow shows AWS Service Catalog portfolios, API calls from ServiceNow and end user interactions.

Prerequisites

This post requires the following:

• An AWS Account with administrative access
• Access to an enterprise or a ServiceNow Personal Developer (PDI) instance
• Administrator access to ServiceNow PDI or Enterprise Instance
• Configure the AWS Service Catalog Connector for ServiceNow by following this post.
• Download the code package from Bulk-Import-Set-for-Amazon-WorkSpaces-main.zip

The overall steps to setup a solution can be broken down into three major categories:

1. Configure AWS (to set up a WorkSpace using Amazon WorkSpaces as an AWS Service Catalog product)
2. Install and configure ServiceNow (to setup the integration between AWS and ServiceNow)
3. Validate the WorkSpaces product in the ServiceNow Service Catalog
4. Configure Import Set process in ServiceNow, and upload the excel template for bulk provisioning
5. Run the Import Set using Transform Map logic
6. Validate the bulk request process

Setup a directory

Amazon WorkSpaces requires the use of a directory to store and manage information for your WorkSpaces and users. See the WorkSpaces Administration Guide on Managing Directories for more information about directories. If you already have a directory (Simple Active Directory (AD), Microsoft AD, or AD Connector) deployed on AWS, then you can skip this section. If not, then you can follow the detailed steps from Appendix A to set up a directory that will be used to store user accounts for your WorkSpaces users.

Set up an AWS CloudFormation Template

In this section, you will set up an AWS CloudFormation template that deploys WorkSpaces on your behalf. You can learn more about this step in the AWS Service Catalog Administrators Guide.

1. From the downloaded package, open a text editor or your favorite code editor and copy the content of Workspaces yaml.yml and paste it into a new file.
2. In the Mappings section of the CloudFormation template, locate the three occurrences of the text “d-XXXXXXXXXX”, and replace all of these with the directory ID that you captured when you set up the directory (Appendix A).
3. Save the file on your computer as deploy-workspaces.template and note where you’re saving it.

Setup a new portfolio

To provide users with products, begin by creating a portfolio for those products. To create a portfolio, follow the detailed instructions in the AWS Service Catalog documentation.

On the AWS Service Catalog console – Create Portfolio page, use the following values for creating the portfolio:

• Portfolio name – End-User-Compute
• Description – Portfolio for EUC products such as desktops
• Owner – IT (it@example.com)

Set up a new product

After you’ve created a portfolio, add a new product using detailed instructions in the AWS Service Catalog documentation.

On the AWS Service Catalog console – Upload New Product page, use the following values for creating the product:

• Product name – Virtual Windows Desktop
• Description – Virtual windows desktop powered by Amazon WorkSpaces
• Provided by – IT
• Vendor (optional) – Amazon Web Services

On the Enter support details page, type the following, and then choose NEXT:

• Email contact – ITSupport@example.com
• Support link – Link to your IT team’s contact us or support page (e.g.,https://aws.amazon.com/contact-us/)
• Support description – Contact IT department for further help

On the Version details page, choose Upload a template file, select Choose File, locate the deploy-workspaces.template file that you saved when you set up the CloudFormation template, and then choose NEXT:

• Version title – 1.0.0
• Description – Initial Version

On the Review page, choose CREATE.

Figure 2. Upload a new product

Enable AWS Service Catalog to launch Amazon WorkSpaces

To enable the AWS Service Catalog to launch WorkSpaces, you must grant additional security privileges. You achieve that through additional AWS Identity and Access Management (IAM) permissions and a launch constraint. A launch constraint specifies the IAM role that AWS Service Catalog assumes when an end user launches a product.

Configure IAM permissions

In this step, we’ll set up an IAM policy and modify an existing role. Make sure that you have followed the steps for integration prerequisites, discussed earlier, prior to starting this section.

Create IAM policy

In this step, you’ll create an IAM policy ‘SCWorkSpacesLaunchPermissions’ to match the following permissions. To create an IAM policy, follow the detailed instructions in the IAM User Guide.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "workspaces:*",
            "Resource": "*"
        }
    ]
}

In the IAM console, on the Review policy page, fill in the form as follows:

1. Name – SCWorkSpacesLaunchPermissions
2. Description – Allows the ability to launch WorkSpaces

Modify IAM role

Modify the existing SCConnectLaunch role and attach the SCWorkSpacesLaunchPermissions policy to it. Refer to Appendix B for detailed instructions.

Launch constraints

A launch constraint specifies the IAM role that AWS Service Catalog assumes when an end user launches a product. For the new Virtual Windows Desktop product, assign the launch constraint ‘SCConnectLaunch’ before it can be launched. Refer to Appendix C for detailed instructions.

Validate Service Catalog Product in ServiceNow

You’re now ready to validate that the new product appears in ServiceNow, and that you can order a product through the ServiceNow Service Catalog.

1. Log in to your ServiceNow instance as the end user (e.g., Abel Tuter). If you’re logged into a developer instance as the administrator, then you can do this by choosing Impersonate User from the user menu in the upper-right corner of your screen.
2. Type Service Catalog in the navigation filter, and choose Service Catalog.
3. Choose AWS Service Catalog.

4. You should now see the AWS Service Catalog product:

5. Select Virtual Windows Desktop.
6. Fill in the order form as follows:

1. 1. Product Name – Type any meaningful name, such as MyCloudDesktop.
   2. WorkStationType – Choose your type of workstation, Value, Standard, or Performance. If you modified your CloudFormation template to include different bundle names, then they should appear here.
   3. UserName – Type the Windows user name that you specified when you created the user (Appendix A). If you’re unable to provision a WorkSpace using the user ID you enter here, then ask your Active Directory administrator for your SAMAccountName.

7. This confirms that the AWS Service Catalog product is successfully synchronized into ServiceNow and we can view the parameters of the WorkSpace product.

Create an Excel Template with provisioning parameters

1. For bulk provisioning, you’ll create an excel sheet for the number of WorkSpaces required, and enter the parameter details WorkstationType, and Username. In the following example, you’ll provision eight WorkSpaces with username starting from awssmc1 – awssmc8. In an enterprise setup, you may have additional parameters and all of them will go into your excel spreadsheet columns.

Workstation parameters screen

2. Save the excel file on your computer and name it “Worskpaces Bulk Upload Excel.xslx”.

Configuring import set process in ServiceNow for bulk provisioning

In this step we will create a script Include, transform target table, import set data source, and transform map in your ServiceNow instance to enable bulk provisioning mechanism for WorkSpaces.

1. Set the application as AWS Service Management Connector on your fulfillment portal from Global.
2. Navigate to System Definitions à Script Includes, and select New and set the
   1. Name – “ServiceCatalogServer”
   2. Application – AWS Service Management Connector
   3. Accessible from – All Application Scopes
   4. Active – true (select the checkbox)
   5. For the script section, enter the content of ScriptInclude-ServiceCatalogServer from the downloaded package and save the form

3. Create a table in ServiceNow. Navigate to System Definition à Tables, and select New
   1. Label – “WorkSpaces Bulk Upload Repo”
   2. Name – Will be auto populated after entering the label column
   3. Under Columns tab – Select “Insert a new row” and add three rows for UserName, WorkSpace Name, and Workstation Type as shown in the following, and Submit.

4. Now you’ll create the Import Set Data Source. Navigate to System Import Sets -> Administration -> Data Sources, select New, and enter the following field values.

Enter the following parameters to create the new Data Source:

1. 1. Name – Bulk WorkSpaces Upload
   2. Import set table name – “x_126749_aws_sc_u_worskpace_bulk_upload”
   3. Type – File
   4. Format – Excel (xlsx.xls)
   5. Save the record

5. On the page, you can see an attachment option with a clip icon. Select it and upload the spreadsheet previously created, WorkSpaces Bulk Upload Excel.xslx.
6. On Data Source – select “Load All Records” UI Action.
7. On the next page, select Create Transform map.

8. Enter Name as – “TM-WorkSpaces” and select the Target Table as “WorkSpaces Bulk Upload Repo”, then right-click the hamburger icon to save the form.
9. Select the UI Action “Mapping Assist” and map the fields from Source Table and Target Table as shown in the following screenshot, and save.

10. Under the “Transform Scripts” tab, select New.

1. 1. Select the “When” column to “OnAfter”
   2. On the script tab, enter the content of OnAfter – transform script.txt from the downloaded package and save the form
   3. Update the productSysID marked in yellow to the sys_id of AWS Service Catalog Product – “Virtual Windows Desktop”.

• • To know the sys id on your servicenow instance, navigate to AWS Service Management Connector -> AWS Service Catalog -> Products -> Name (Search with Virtual Windows Desktop). -> Right-click and select “Copy sys_id”.

Run the Import Set using Transform Map logic

In this step, we will execute the import using the field mapping logic and the onAfter transform script to execute bulk provisioning of WorkSpaces.

1. Now let’s run the Transform map to complete the import set process. On the Table Transform Map select the UI Action “Transform”.

2. Transform will now run the import set process to do a bulk provisioning of WorkSpaces.

3. Successful completion of the Transform map will result in the following screenshot.

Validating the bulk requests

In this step we will validate the Requested Items (RITM’s) that were created as a part of bulk-provisioning process, and the successful provisioning process that includes the outputs of provisioned WorkSpaces.

1. On the ServiceNow Navigation Filter, type Requested Items and open the list view and apply the filter “Item is Virtual Windows Desktop” and “Created on Last Minute”.

2. System Administrators can now bulk provision WorkSpaces and each requested item will have its own lifecycle process. They can be further modified by adding additional approvals to the workflow depending on Username, group, etc.
3. Navigate to AWS Service Catalog -> Provisioned Products ->List View to view the output parameters for any provisioned product. Select any of the recently provisioned products. The following are the outputs from the CloudFormation output parameters that users can use to start interacting with the cloud desktop.

4. After WorkSpaces provisioning is complete, the user should receive an email from AWS with complete instructions on how to complete the user profile and log in to the WorkSpaces instance. Make sure that you complete your user profile first.

The following shows at a high level how you can log in to your WorkSpaces after the user profile completion. Start by downloading the WorkSpaces client for your platform.

5. After you’ve installed the WorkSpaces client, log in by using your username and associated credentials.

Conclusion

In this post, we covered how you can use AWS Service Catalog, AWS Service Management Connector and ServiceNow import sets to create a fully automated, self service desktop solution for bulk deploying of WorkSpaces. This simplifies IT Service Management platform administrators, HR partners to onboard new users to WorkSpaces with self-service mechanism from ServiceNow.

Authors:

Appendices

Appendix A – Create directory

In the context of testing or proof-of-concept work, we recommend that you deploy Simple AD if you don’t already have a directory setup. Simple AD is a cost-effective solution to get your environment ready for deploying Amazon WorkSpaces quickly. To create a Simple AD directory, follow the steps in Create a Simple AD Directory.

Add Users

Before you can use ServiceNow to deploy Amazon WorkSpaces, you must set up user accounts in the directory for the people for which you’ll create Amazon WorkSpaces.

Note that if you have AD Connector set up, then users would already exist in your directory, thereby allowing you to skip this step.

To add users to Simple AD directory

1. Open the Amazon WorkSpaces console. Make sure that the correct Region is selected in the upper right of the console.
2. Choose Launch WorkSpaces.
3. Select your directory from the list and choose Next Step.
4. Type the Username, First Name, Last Name, and valid email address for the first user that you want to add.

Note that if you don’t specify a valid email address, then the user won’t be able to log in.

5. If you want to add more than just one user, then choose + Create Additional Users. This will add more rows to the form.
6. Choose Create Users.
7. Choose Cancel at the bottom of the form. We don’t actually want to allocate WorkSpaces to these users at this time, just create the accounts.

Obtain WorkSpaces Directory ID

Each directory that you set up will be provisioned with a unique directory ID. It’s necessary to acquire at least one of these directory IDs from your Amazon WorkSpaces deployment. This is needed in the next section and is used to tell your CloudFormation template under which directory to deploy Amazon WorkSpaces.

1. Open the Amazon WorkSpaces console. Make sure that the correct Region is selected in the upper right of the console.
2. In the left navigation panel, choose Directories.
3. Check the box next to the directory that you want, then highlight the text of the Directory ID (d-XXXXXXXXXX) to copy it to your clipboard.

Paste this ID somewhere where you can get back to it easily for a later step.

Appendix B – To modify the IAM role

1. Open the IAM console roles page.
2. Locate the SCConnectLaunch role in the list or type the name in the search box, and then choose the role in the Role name column.
3. Choose Attach policy.
4. In the search box, begin typing SCWorkSpacesLaunchPermissions to locate the policy.
5. Select the checkbox in the first column to assign that policy.
6. Choose Attach policy.
7. On the role summary screen, and choose the copy icon next to the Role ARN field. This will copy the ARN to your clipboard.
8. Paste the ARN somewhere for safekeeping (e.g., Notepad). You’ll need it in the next section.

Appendix C – To add a launch constraint

1. Open the AWS Service Catalog console.
2. Open the End-User-Compute portfolio that we previously created.
3. Expand Constraints.
4. Choose the ADD CONSTRAINTS link.
5. You should see the following dialog box.
   1. Product – Virtual Windows Desktop
   2. Constraint type – Launch

6. Choose CONTINUE.
7. You’ll be prompted for the IAM role and description.
   1. IAM role – There are two boxes, paste the SCConnectLaunch role ARN that you set up in Appendix B into the second box.

8. Description – Ability to only launch Amazon WorkSpaces.

9. Choose SUBMIT.