# Getting started with AWS Transform
<a name="getting-started"></a>

**Topics**
+ [Setting up AWS Transform](transform-setup.md)
+ [Enable AWS Transform](#transform-enable)
+ [Quick start: Trying AWS Transform](#transform-app-admin-starting-standalone)
+ [Managing users](transform-user-management.md)
+ [AWS Transform environment](transform-environment.md)

# Setting up AWS Transform
<a name="transform-setup"></a>

## Before you begin
<a name="transform-prerequisites"></a>

Before you set up AWS Transform make sure you have an AWS account with administrator access

**Note**  
If you want to try out AWS Transform as a proof-of-concept or for test environments see [Quick start: Trying AWS Transform](https://docs.aws.amazon.com/transform/latest/userguide/transform-setup.html#transform-app-admin-starting-standalone).

## Getting started with AWS Organizations
<a name="transform-app-admin-starting-orgs"></a>

Follow these steps to set up AWS Transform:

1. Sign in to your AWS Organizations management account.

1. Navigate to the AWS Transform service.

1. Choose **Enable service** for your organization to use AWS Transform.

1. Configure the necessary permissions for organizational member accounts.

1. Access the AWS Transform web experience from your member accounts.

**Note**  
To use the Landing Zone Accelerator (LZA) on AWS solution to build your landing zone together with AWS Transform for migration capabilities, your AWS Transform account and LZA installation must be in the same AWS Organization. Using separate Organizations IDs for LZA and AWS Transform deployments is not supported because this can cause inconsistencies in organizational management and resource deployments. To learn how to set up your LZA installation using Organizations see [Deploy a cloud foundation to support highly-regulated workloads and complex compliance requirements ](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/solution-overview.html) in the *Landing Zone Accelerator on AWS Implementation Guide user guide*. 

## Getting started with AWS IAM Identity Center
<a name="transform-app-admin-starting-idc"></a>

Follow these steps to use IAM Identity Center for AWS Transform and to add users and groups.

By default, no users have access to AWS Transform when you first enable it. 

**Note**  
IAM Identity Center is not limited to the region in which it is set up. If you already set up IAM Identity Center in a region that is not supported by AWS Transform, you can use it for AWS Transform.

1. Set up IAM Identity Center following the instructions in [ To enable an instance of IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/enable-identity-center.html#to-enable-identity-center-instance).

   Configure IAM Identity Center to use an external enterprise identity provider, and replicate its user and group info into IAM Identity Center.

1. In the AWS console, select AWS Transform and choose **Get started**.

1. Choose **Enable service** for your organization to use AWS Transform.

1. Select an encryption key. The default selection is an AWS managed key. To use a custom key:

   1. Under **Encryption key**, choose **Customize encryption settings**.

   1. Select **Use an AWS KMS key**.

   1. Choose an existing key or create a new one.

   1. Choose **Submit** to apply your changes, and then choose **Enable AWS Transform**.

   Click **View profile** to view the configuration. The Web application URL is used by your users to access the AWS Transform unified web experience.

1. Select **Users** in the navigation pane and select **Assign users or groups**.

1. Search for the name of the user or groups you want to authorize to use AWS Transform. The search references users and groups propagated from your identity provider.

1. Select a group or user, select **Done**, and then, **Assign**. These users are authorized to use the AWS Transform unified web interface.

## Using third-party identity providers
<a name="transform-third-party-identity"></a>

AWS Transform supports integration with third-party identity providers (IdPs) such as Azure Active Directory (Entra ID) and Okta Workforce Identity. This allows you to use your existing identity management system for user authentication.

### Prerequisites
<a name="transform-third-party-prerequisites"></a>

Before configuring third-party identity provider integration, ensure that users in your identity provider have name, email, and username attributes configured

### Stored Information
<a name="transform-stored-information"></a>

When you use AWS Transform with IdPs, AWS stores minimal user information that is encrypted and secured:

Stored User Information  
AWS Transform stores basic user profile information upon first login, including display name, email address, username (preferred\$1username), and a unique user identifier. This information is encrypted using either a customer-owned KMS key or a service-owned key, depending on the customer's AWS Transform profile configuration. The data is stored in AWS Transform's authentication database and is only collected during the initial login session. This populates the search results when inviting other users to a workspace.

Data Lifecycle  
User information is stored only for users who have logged in to the AWS Transform web app at least once, and may become stale if users update their information in their identity provider without logging back into AWS Transform. All stored user information is deleted when the AWS Transform profile is deleted.

Client Secret Storage  
The client secret provided during setup is stored using AWS Secrets Manager via a Service Linked Secret (SLS) in your account.

### User Identifier Handling
<a name="transform-user-identifier-handling"></a>

Entra  
Uses the "oid" (object identifier) claim as the unique user identifier, which is immutable and uniquely identifies users across the Microsoft tenant. This value is visible to customers in the Entra console and appears in CloudTrail logs.

Okta Workforce Identity  
Uses different claims for user identification depending on token type - the "sub" claim in ID tokens and the "uid" claim in Access tokens. AWS Transform validates that both claims contain the same value during authentication. This value is visible to customers in the Okta console and appears in CloudTrail logs.

### Setting up Azure Active Directory (Entra ID)
<a name="transform-azure-setup"></a>

To configure Azure Active Directory integration with AWS Transform:

1. Navigate to the Azure portal and select **Azure Active Directory**.

1. In the left navigation pane, choose **Manage** > **App registrations**.

1. Choose **\$1 New registration**.

1. Enter an application name, choose your supported account type, leave the redirect URI blank, and choose **Register**.

1. In the left navigation, choose **Manage** > **Manifest**.

1. Update `requestedAccessTokenVersion` from `null` to `2` and choose **Save**.

1. Choose **Manage** > **Expose an API** and choose **Add a scope**.

1. Create an Application ID URI using the default structure `api://<client-id>`.

1. Add the scope `transform:read_write`.

1. Choose **Add a certificate or secret** and create a new client secret. Save this value as it's needed for profile creation.

1. Find the Issuer URL by choosing **Endpoints** and selecting the OpenID Connect metadata document. The "issuer" field in the metadata is your Issuer URL.

1. Create a profile in the AWS Transform console using the Client ID, Client Secret, and Issuer URL.

1. After profile creation, add a redirect URI by choosing **Add a platform**, selecting **Web**, and entering `<web-application-url>/login/callback`.

### Setting up Okta Workforce Identity
<a name="transform-okta-setup"></a>

To configure Okta Workforce Identity integration with AWS Transform:

1. Navigate to your Okta Workforce Identity console.

1. Choose **Applications** > **Applications** and select **Create App Integration**.

1. Select **OIDC - OpenID Connect** and **Web Application**, then choose **Next**.

1. Name your application, leave the Grant Type as *Authorization Code*, leave redirect URIs blank, configure user assignments, and choose **Save**.

1. Navigate to the **Sign On** tab and set the Issuer to **Okta URL** instead of Dynamic.

1. Copy the Client ID and configure it as the Audience for your Authorization Server by going to **Security** > **API** and adding an Authorization Server.

1. In the Authorization Server, add the scope `transform:read_write` under the **Scopes** tab.

1. Add an Access Policy that allows the OIDC Application to use this Authorization Server and configure a rule for the policy.

1. On the Authorization Server Settings page, note the Issuer URL for profile creation in AWS Transform.

1. Create a profile in AWS Transform using the Issuer URL, Client ID, and Client Secret from the application settings.

1. After profile creation, add `<web-application-url>/login/callback` as a redirect URL in the application's General tab.
**Note**  
If you would like to be redirected back to the AWS Transform webapp after logout, you’ll need to configure your web application URL as a trusted origin under **Security** > **API**.

## User onboarding
<a name="transform-user-onboarding"></a>

This section describes the experience for users who have been granted access to AWS Transform.

### Accepting the invitation
<a name="transform-user-invitation"></a>

When a user is added to AWS Transform, they receive an email invitation containing:
+ A greeting and information about the invitation
+ The AWS Transform web application URL
+ Their username
+ A link to accept the invitation and set up their password

To set up their account:

1. The user clicks the "Accept invitation" link in the email.

1. On the "New user sign up" page, they enter and confirm a password.

1. The password must meet security requirements, including:
   + At least 8 characters
   + At least one uppercase letter
   + At least one lowercase letter
   + At least one number
   + At least one special character

1. After creating a password, they see a confirmation that their account was successfully created.

### Signing in to AWS Transform
<a name="transform-user-signin"></a>

To sign in to AWS Transform:

1. Navigate to the AWS Transform web application URL provided in the invitation email.

1. Enter the username.

1. Choose **Next**.

1. Enter the password.

1. Choose **Sign in**.

### Welcome experience
<a name="transform-user-welcome"></a>

Upon first login, users see the AWS Transform welcome page with:
+ A personalized greeting
+ Available transformation capabilities
+ Option to create a workspace

The welcome page provides information about the transformation capabilities available in AWS Transform, including:
+ Modernize IBM z/OS migrations to AWS
+ Migrate VMware workloads to Amazon EC2
+ Modernize .NET applications to Linux-ready cross-platform .NET
+ Assess workloads for migration readiness

Users can start by creating a workspace or asking their team to add them to an existing workspace.

## Enable AWS Transform
<a name="transform-enable"></a>

To enable AWS Transform:

1. Sign in to the AWS Management Console.

    

1. In the search bar at the top of the console, search for *AWS Transform*.

1. Select **AWS Transform** from the search results.

1. Choose **Get started** to enable the service in your current Region.

1. Optional: configure IAM Identity Center. You will also be able to choose to use a [third-party identity provider (IdP)](transform-setup.md#transform-third-party-identity) in a later step.

1. Select an **Encryption key**: **default AWS managed key** or **Customize encryption settings.**

1. Choose which AWS Transform capabilities you want to enable:
   + **Command line interface** (CLI), needed to create and run [custom transformations](https://docs.aws.amazon.com/transform/latest/userguide/transform-app-custom.html). To enable the CLI, view and follow the download instructions.
   + **Web application**, the agentic user interface for modernization. Choose** Enable web application** to use it.

1. Choose **Enable AWS Transform**. 

1. Optional: choose **Enable View profile** to access the AWS Transform **Users**, **Settings**, and **Connectors** tabs, or **Manage users** to manage users.

   You can access the **Users**, **Settings**, and **Connectors** tabs at any time by choosing the menu icon in the top left corner of the console.

1. Configure User access by choosing an identity provider, either IAM Identity Center or a [third-party identity provider (IdP)](transform-setup.md#transform-third-party-identity).
**Note**  
This choice is finalized and cannot be changed when you enable AWS Transform.

1. Choose **Enable web application**. 

1. The system displays "Enabling AWS Transform" while it creates the necessary resources.

After AWS Transform is enabled, the **Settings** tab displays the following information:
+ **Web application URL** - The URL for accessing the AWS Transform web application
+ **Start URL for IDE** - The URL for accessing AWS Transform in integrated development environments
+ **Region** - The AWS Region where AWS Transform is enabled

## Quick start: Trying AWS Transform
<a name="transform-app-admin-starting-standalone"></a>

The easiest way to try out AWS Transform is with a standalone AWS account. You may want to do this as a proof-of-concept or for test environments. Use this procedure:

1. Sign in to the AWS Management Console.

1. Navigate to the AWS Transform service.

1. Choose **Get started** to enable the service.

1. Select and set up your identity provider.

1. Assign users to AWS Transform service.

1. After the service is enabled, you'll see the AWS Transform web application URL.

1. Open that URL in a new browser window to access the AWS Transform web experience.

Now you're ready to set up your workspace.

# Managing users
<a name="transform-user-management"></a>

AWS Transform integrates with IAM Identity Center for user management. This section describes how to add users to IAM Identity Center and grant them access to AWS Transform.

## Adding users in IAM Identity Center
<a name="transform-add-idc-users"></a>

To add users in IAM Identity Center:

1. Navigate to the IAM Identity Center console.

1. In the navigation pane, choose **Users**.

1. Choose **Add user**.

1. Enter the required information:
   + **Username** - A unique identifier for the user (cannot be changed later)
   + **Email address** - The user's email address
   + **First name** and **Last name** - The user's name
   + **Display name** - The name that appears in the user list

1. For **Password**, choose how the user receives their password:
   + **Send an email** - Send setup instructions via email
   + **Generate a one-time password** - Create a password to share manually

1. Choose **Next** to review the user information.

1. Review the details and choose **Add user**.

After the user is added, they'll receive an email invitation to set up their IAM Identity Center account. The invitation link is valid for 7 days.

You can also learn about working with IAM Identity Center and AWS Transform in this video:

[![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/NesMt5cgT0s/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/NesMt5cgT0s)


## Adding users to AWS Transform
<a name="transform-add-transform-users"></a>

After adding users to IAM Identity Center, you can grant them access to AWS Transform:

1. Return to the AWS Transform console.

1. In the navigation pane, choose **Users and groups**.

1. Select the **Users** tab or the **Groups** tab.

1. Search for and select the users or groups that you want to add from IAM Identity Center.

1. Choose **Assign users and groups** to grant the selected users or groups access to AWS Transform.

After adding users, they appear in the **Users** list with a status of "Pending" until they accept the invitation and sign in.

# Understanding collaborator permissions
<a name="collaborator-permissions"></a>

 AWS Transform uses a workspace-based permission model to control access to resources and actions. Each user is assigned a specific role within a workspace, which determines what actions they can perform. A user can have different roles in different workspaces. 

## User roles
<a name="user-roles"></a>

 AWS Transform supports five user roles within each workspace. These roles apply within the context of a workspace, and a user will be assigned roles in each workspace they are a member of. The access permissions defined for each role are workspace agnostic, so user A with the Administrator role in workspace A has the same permissions as user B with the Administrator role in workspace B. 

## Role permissions
<a name="permission-table"></a>

 Detailed permissions for each role: 


| Action | ResourceType | Admin | Approver | Contributor | ReadOnly | 
| --- | --- | --- | --- | --- | --- | 
| Create | Workspace | ✓ | ✓ | ✓ | ✓ | 
| List | Workspace | ✓ | ✓ | ✓ | ✓ | 
| Get | Workspace | ✓ | ✓ | ✓ | ✓ | 
| Update | Workspace | ✓ | ✗ | ✗ | ✗ | 
| Delete | Workspace | ✓ | ✗ | ✗ | ✗ | 
| Create | ChatMessage | ✓ | ✓ | ✓ | ✗ | 
| Read | ChatMessage | ✓ | ✓ | ✓ | ✓ | 
| Create | RoleAssociation | ✓ | ✗ | ✗ | ✗ | 
| Read | RoleAssociation | ✓ | ✓ | ✓ | ✓ | 
| Update | RoleAssociation | ✓ | ✗ | ✗ | ✗ | 
| Delete | RoleAssociation | ✓ | ✗ | ✗ | ✗ | 
| Read | CriticalHITLTask | ✓ | ✓ | ✓ | ✓ | 
| Update | CriticalHITLTask | ✓ | ✓ | ✗ | ✗ | 
| Delete | CriticalHITLTask | ✓ | ✓ | ✗ | ✗ | 
| Read | HITLTask | ✓ | ✓ | ✓ | ✓ | 
| Update | HITLTask | ✓ | ✓ | ✓ | ✗ | 
| Delete | HITLTask | ✓ | ✓ | ✓ | ✗ | 
| Create | Job | ✓ | ✓ | ✓ | ✗ | 
| Read | Job | ✓ | ✓ | ✓ | ✓ | 
| Update | Job | ✓ | ✓ | ✓ | ✗ | 
| Delete | Job | ✓ | ✓ | ✓ | ✗ | 
| Read | Worklog | ✓ | ✓ | ✓ | ✓ | 
| Create | Artifact | ✓ | ✓ | ✓ | ✗ | 
| Read | Artifact | ✓ | ✓ | ✓ | ✓ | 
| Update | Artifact | ✓ | ✓ | ✓ | ✗ | 
| Delete | Artifact | ✓ | ✓ | ✓ | ✗ | 
| Create | Connector | ✓ | ✓ | ✓ | ✗ | 
| Read | Connector | ✓ | ✓ | ✓ | ✓ | 
| Update | Connector | ✓ | ✓ | ✓ | ✗ | 
| Delete | Connector | ✓ | ✓ | ✓ | ✗ | 

## Human-in-the-loop (HITL) actions
<a name="hitl-actions"></a>

 AWS Transform provides two types of HITL actions - standard and critical: 

Standard HITL actions  
 These are routine actions that can be performed by users with Contributor, Approver, or Administrator roles. 

Critical HITL actions  
 These are actions with significant impact, and thus require higher permission levels. Examples include:   
+ Merging code to main branches
+ Performing graph decomposition
+ Deploying code to production environments
 Critical HITL actions can only be performed by users with Approver or Administrator roles. 

 To ensure there's a differentiation between Standard HITL and Critical HITL actions in AuthZ policies, AWS Transform provides two separate HITL APIs, one for completing a standard HITL action, and one for completing a critical HITL action. 

# AWS Transform environment
<a name="transform-environment"></a>

AWS Transform is an agentic service that uses natural language processing to help you plan and execute your workload transformations. You interact with AWS Transform primarily through a conversational interface, where the service adapts and responds based on the context of your discussion. For example, you can start by describing your current architecture and transformation goals using everyday language, such as "I need to migrate my on-premises VMs to EC2." 

 As you converse with AWS Transform, the service builds a customized job plan that aligns with your specific requirements. The conversation flow is dynamic and driven by you, allowing you to refine your transformation plan iteratively. You can modify the job plan during the conversation by making requests like "add a testing phase before production cutover" or "remove the backup step since we already have a solution." You can also go back to a previous task and perform it again. AWS Transform continuously updates the plan based on your input, ensuring the final transformation strategy meets your technical and business needs.

Here's what you see when you open AWS Transform. 
+ View control pane: This is the narrow pane on the left of AWS Transform. You can choose one of the icons to choose what view is shown to the right of the view control pane. Hover over each icon for a tool tip explaining the view. The give standard views, from top to bottom, are:
  + **Job Plan**
  + **Dashboard**
  + **Approvals**
  + **Artifacts**
  + **Worklog**

  Some workflows provide additional views.

  When you are working in a job plan, the views are:
  + **Chat**
  + **Approvals**
  + **Artifact store**
  + **Worklog**

  When you are in a workspace, the views are at the top:
  + **Jobs**
  + **Artifacts**
  + **Collaborators (Users)**
  + **Connectors**
  + **Settings**
+ The **View** pane is next to the view controls.
+ The **Chat** pane is in the center. This is where you conduct your conversation with AWS Transform.
**Note**  
Users with read-only permissions are unable to send messages in the chat.
+ To the right is the **Collaboration** pane. This appears when *human in the loop* (HITL) activities are performed, such as:
  + Uploading data files
  + Reviewing information and plans provided by AWS Transform

## Start your project
<a name="start-workflow"></a>

AWS Transform guides you through your modernization and migration projects. To get started:

1. Create a workspace to host your project. On the **Workspaces** page, choose **Create workspace**. Follow the instructions and then open the workspace.

1. In the **Chat** pane, type "create a job"

1. Choose a job, and follow the instructions provide by AWS Transform. If your input is required, the **Collaboration** pane appears and explains what is required.

### Workflow flexibility
<a name="flexible-workflow"></a>

The AWS Transform workflow environment provides flexibility in the progression of your modernization projects. Using natural language in the chat pane you can:
+ Retry a task that AWS Transform has already completed, providing different human-in-the-loop input along the way.
+ Rerun a job, for example, if there have been changes in your modernization sources.

## Chatting with AWS Transform
<a name="transform-app-chat"></a>

AWS Transform chat is available at every stage of your project. To open the chat click the purple hexagonal icon in the lower right corner of the web console. 

The chat is there for you to ask anything. For example, you can ask the chat to explain concepts, guide you through a process, explain a AWS Transform request or response, or explain a AWS Transform report. 

**Note**  
Users with read-only permissions are unable to send messages in the chat.

### AWS Transform chat integrations
<a name="transform-app-chat-integrations"></a>

AWS Transform chat is integrated with:

#### Experience-Based Acceleration
<a name="transform-app-chat-eba"></a>

[Experience-Based Acceleration (EBA)](https://aws.amazon.com/experience-based-acceleration/) is offered through AWS Transform chat. It enables you to perform EBA assessment for Windows workloads and generate a plan. You can start by importing assessment results from CAST. It helps you discover your application portfolio, after which you can use AWS Transform chat to select applications that meet your business needs (for example, filtering applications based on complexity or lines of code). You can then perform deeper assessment of the selected application and generate a modernization plan.

#### AWS Countdown Premium
<a name="transform-app-chat-cdp"></a>

[AWS Countdown Premium](https://aws.amazon.com/premiumsupport/aws-countdown/) (CDP) integrated into AWS Transform provides sustained, expert guidance with designated AWS engineering support. Your designated CDP Engineer dives deep into your tech stack, providing personalized, context-aware support when issues arise. Users can leverage AWS Transform to log a support ticket directly from its chat interface. The support ticket embeds worklog and job plan details to help support understand the customer's context. If a customer or partner is part of the CDP Program, the support ticket automatically gets routed to the designated CDP Engineer who can help debug issues, interpret transformation outputs, and drive progress for expedited issue resolution. For example:
+ For .NET workloads, CDP can assist with repository connector issues, dependency resolution, and post-transformation deployment.
+ In mainframe scenarios, CDP can help troubleshoot refactored Java code, configure database migration tools, and build CI/CD pipelines.
+ In VMware migrations, CDP can accelerate network configuration, Application Migration Service setup, and agent installation.

#### AWS Skill Builder
<a name="transform-app-chat-skillbuilder"></a>

[AWS Skill Builder](https://skillbuilder.aws/) provides relevant learning modules through the chat. You can ask AWS Transform chat about your learning needs, and it presents you relevant course catalog. Skill Builder delivers contextual micro-learning experiences as you work through transformation stages.