Desktop and Application Streaming

Migrating to Microsoft 365 Apps for enterprise at scale on Amazon WorkSpaces

Amazon Web Services offers two choices to run Microsoft Office productivity applications on Amazon WorkSpaces Family services. One option is to license Microsoft Office as part of a WorkSpaces application bundle. As of August 1, 2023, you have the option to bring Microsoft 365 Apps for enterprise licenses to use on Amazon WorkSpaces services. Microsoft 365 adds to the power of WorkSpaces services with popular office productivity applications like Microsoft Word, Microsoft Excel, Microsoft PowerPoint, Microsoft Outlook, and others. Included apps vary by Microsoft 365 license plan. Microsoft allows Microsoft 365 E3/E5, A3/A5, G3/G5, and Business Premium licenses to run on WorkSpaces services.

Customers often ask how to migrate their users from the license-included version of Office to Microsoft 365 licenses they already own. Previously, administrators had to remove application bundles through the WorkSpaces migration process, which creates a new root volume while keeping the user volume intact. That migration option is still available, but now customers can use the new manage applications feature to do the same. This blog guides you through removing Office from existing WorkSpaces bundle using the new APIs provided by the manage applications feature. You will also learn how to identify and remove Office license included from your WorkSpaces at scale, using either standalone PowerShell scripts or an AWS Lambda function.

Time to read 15 minutes
Time to complete 1 hour
Learning level Expert (400)
Services used Amazon WorkSpaces
Amazon WorkSpaces Core
AWS Identity and Access Management (IAM)
AWS Lambda

Prerequisites

This article assumes that you have the following in place:

Option 1: Using PowerShell to remove Office from WorkSpaces

Step 1: Create the IAM policy

In this step, you create an IAM policy for the administrator running the scripts. This provides permissions required to find WorkSpaces with the associated application, remove that application association, and deploy the change. AWS recommends that you review and vet the policy created in this step within your environment to verify it meets your security standards prior to deployment.

  1. Open the IAM console.
  2. In the navigation pane, choose Policies.
  3. Choose Create policy.
  4. For Policy editor, choose JSON.
  5. Copy and paste the following JSON policy.
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "workspaces:DescribeApplications",
                "workspaces:DeployWorkspaceApplications",
                "workspaces:DescribeWorkspaceAssociations",
                "workspaces:AssociateWorkspaceApplication",
                "workspaces:DisassociateWorkspaceApplication",
                "workspaces:DescribeApplicationAssociations",
                "workspaces:DescribeWorkspaces",
                "workspaces:DescribeWorkspaceDirectories"
            ],
            "Resource": "*"
        }
    ]
}
  1. Once finished, choose Next.
  2. For Policy name, enter a name for the policy, EUC_WorkSpaces_Office_Removal_Policy.
  3. Add any required tags for your environment, then choose Create policy.
  4. Attach the policy to the user, group, or role assumed by the user running the PowerShell scripts in steps 2 – 4.

Step 2: Generate a list of WorkSpaces instances with Office installed

Once you have met the prerequisites, proceed with running the scripts. In this step, WorkSpaces instances with Office installed are written to a CSV file. In this script, you supply the directoryId, region, and a path for the output file. That file is used in later steps.

  1. Download the zipped PowerShell scripts from the GitHub repository.
  2. Unzip the download to the location where you want to run the scripts from.
  3. Open the Office-removal-Step-1.ps1 script in a text editor of your choice.
  4. Update the value for $region to the AWS Region where your WorkSpaces reside. Update the value for $CSV_Output to a location of your choice. Update the value for $directoryId to the Directory Id that contains your WorkSpaces to remove Office from.
  5. Open a PowerShell window and navigate to the directory containing the scripts.
  6. Set your AWS credentials for the script to use when making service API calls. This is accomplished by using the Set-AWSCredentials cmdlet. If you are using permissions from an instance profile, you may skip this step.
  7. In the PowerShell window, run the first script: .\Office-removal-Step-1.ps1

Step 3: Disassociate Office from listed WorkSpaces instances

You can now remove any rows in the file output from step 2 that contain WorkSpaces instances that you do not want targeted for Office removal. This script loops through the WorkSpaces instances in the output file and issues the command to disassociate the Office application package from them.

  1. Open the Office-removal-Step-2.ps1 script in a text editor of your choice.
  2. Update the value for $region to the AWS Region entered in step 2. Update the value for $CSV_Input to match the path of the file output in step 2.
  3. Save the updated file.
  4. In the PowerShell window, run the second script: .\Office-removal-Step-2.ps1

Step 4: Initiate Office uninstalls

Once the applications are no longer associated with the WorkSpaces instances, you publish the changes. When this script runs, the WorkSpaces instances will reboot and begin the Office removal process. The user is logged out of their machine and the WorkSpace enters a maintenance mode, preventing reconnection until the process is complete.

  1. Open the Office-removal-Step-3.ps1 script in a text editor of your choice.
  2. Update the value for $region to the AWS Region entered in step 2. Update the value for $CSV_Input to match the path of the file output in step 2.
  3. Save the updated file.
  4. In the PowerShell windows, run the third script: .\Office-removal-Step-3.ps1

Option 2: Using AWS Lambda and Python to remove Office from WorkSpaces instances

Alternatively, you can create a Lambda function scheduled to run during a time that does not impact users or is used as part of another automation workflow.

Step 1. Create the IAM policy and role

In this step, you create an IAM policy and role that the Lambda function will assume. This provides Lambda the permissions required to find WorkSpaces with associated applications, remove the application association, and deploy the change. The policy also contains the basic Lambda permissions required for logging. The policy created in this step should be viewed and vetted within your environment to verify it meets your security standards prior to deployment.

  1. Open the IAM console.
  2. In the navigation pane, choose Policies.
  3. Choose Create policy.
  4. For Policy editor, choose JSON.
  5. Copy and paste the following JSON policy.
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "workspaces:DescribeApplications",
                "workspaces:DeployWorkspaceApplications",
                "workspaces:DescribeWorkspaceAssociations",
                "workspaces:AssociateWorkspaceApplication",
                "workspaces:DisassociateWorkspaceApplication",
                "workspaces:DescribeApplicationAssociations",
                "workspaces:DescribeWorkspaces",
                "workspaces:DescribeWorkspaceDirectories"
            ],
            "Resource": "*"
        },
        {
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": "arn:aws:logs:aws-region-code:account-id-without-hypens:*",
            "Effect": "Allow"
        }
    ]
}
  1. To match your environment, update the following values:
    • Replace aws-region-code with the AWS Region code in which the solution is being deployed.
    • Replace account-id-without-hyphens with the account ID number of the account in which the solution is being deployed.
  2. Once finished, choose Next.
  3. For Policy name, enter a name for the policy, EUC_WorkSpaces_Automated_Office_Removal_Policy.
  4. Add any required tags for your environment, then choose Create policy.
  5. In the navigation pane, choose Roles.
  6. Select Create role.
  7. For Select type of trusted entity, verify AWS service is selected.
  8. For Use case, select Lambda, and then choose Next.
  9. For Permissions policies, browse for, or search in the filter policies search box, for the name of the policy created previously. Select the check box next to the policy name.
  10. Choose Next.
  11. For Role name, enter a name for your role to help you identify it, EUC_WorkSpaces_Automated_Office_Removal_Role.
  12. Add any required tags for your environment, then choose Create role.

Step 2. Create the Lambda function

In this step, you create the Lambda function that searches a specified directory for WorkSpaces instances with associated applications. The script then removes the application association and initiates the uninstallations on each WorkSpaces. It logs the results of its actions into Amazon CloudWatch for review.

  1. Open the Lambda console.
  2. Choose Create function.
  3. Verify Author from scratch is selected. Enter a Function name, EUC_WorkSpaces_Automated_Office_Removal.
  4. For Runtime, select Python 3.12. Version 3.12 is required for Boto3 support of the Manage applications feature.
  5. Under Permissions, expand Change default execution role and select Use an existing role.
  6. For Existing role, select the IAM role created in step 1, EUC_WorkSpaces_Automated_Office_Removal_Role.
  7. Choose Create function.
  8. Within the Code source section, replace the placeholder code with the contents of Python script hosted on GitHub.
  9. Choose Deploy to save the changes.
  10. Choose the Configuration tab.
  11. Choose Environment variables, then choose Edit.
  12. Choose Add environment variable twice to create two blank variables.
  13. For the first Key, enter OfficeAppId.
  14. For the first Value, enter the WorkSpaces application id for the version of Microsoft Office you are removing from your WorkSpaces. For Microsoft Office Professional Plus 2016, enter wsa-khw7gclz4. For Microsoft Office Professional Plus 2019, enter wsa-hvh179sq6.
  15. For the second Key, enter WorkspacesDirectory.
  16. For the second Value, enter the WorkSpaces Directory Id that contains your WorkSpaces to remove Office from.
  17. Choose Save.
  18. Choose General configuration, then choose Edit.
  19. Increase the value for Timeout to 15 min. *Note, the larger the number of WorkSpaces in your directory, the longer the time it takes for the script to iterate through them all. AWS recommends running application management actions in batches of 200 WorkSpaces or less.
  20. Chose Save.

You are now ready to run the Lambda function manually or using triggers such as Amazon EventBridge. The Lambda function can be utilized as part of a larger automation tool your company utilizes.

Cleanup

In this blog post, you created several components that may generate costs based on usage. To avoid incurring future charges, remove the following resources.

  1. Lambda functions do not incur a charge unless invoked. To remove this component completely:
    1. Open the Lambda console.
    2. Select your function.
    3. Choose Actions, then Delete.
  2. There are no charges for IAM Policies and Roles. To remove the IAM entities created in this article:
    1. Navigate to the IAM console.
    2. Click Roles.
    3. Select the role created as part of this blog, then choose Delete.
    4. Click Policies.
    5. Select the policy created previously. Choose Actions, then Delete.

Conclusion

In this post, you learned about two options for automating the removal of Office-included bundles from Amazon WorkSpaces. With these methods, streamline the process of migrating to Microsoft 365 Apps for enterprises using licenses you already own. If you’d like to discuss how to optimize the procedure described in this blog for your specific use case, reach out to your account team.

Justin Grego Justin Grego is a Senior End User Computing Specialist Solutions Architect. As part of the EUC Service Aligned SA Team, he helps enable both customers and fellow SAs get up to speed on and be successful with new AWS EUC features and services.
Dave Jaskie Dave Jaskie is a Senior End User Computing Specialist Solutions Architect. He brings 15 years of experience in the End User Computing space. Outside of Work, Dave enjoys traveling and hiking with his wife and 3 kids.