Wrap Up: Cross-Account Role Onboarding Workflow

By Ian Scofield. Ian is a Partner Solutions Architect (SA) at AWS. 

Over the course of three blog posts (Parts 1, 2, and 3), we’ve been discussing a new way for APN Partners to onboard customers, focusing on the creation of cross-account roles.  Throughout this series, we’ve proposed the usage of AWS CloudFormation for the creation of this role, to provide an automated process that can seamlessly integrate into an existing onboarding workflow.

In this post, we’ll recap the components discussed so far, put it all together, and show you the completed workflow.  As we move along, each step we discuss (designated as Step 1, 2, 3, etc. in the text) will correlate with a numbered arrow in the following diagram.

As you’ll recall from the earlier posts, to kick off the onboarding process, we first ask the customer to provide their AWS account ID. (Step 1)  We use this information as follows:

• We whitelist the provided account ID in our non-public Amazon SNS topic to adhere to security best practices. (Step 2)
• We create a customer tracking entry in our Amazon DynamoDB table. (Step 3)
• We associate a uniquely generated external ID with the provided account ID and store in our DynamoDB Table (Step 3).

After storing the relevant information and updating the relevant policies, we generate a customized CloudFormation template. (Step 4)  In Part 2 of this series, we demonstrated a method for generating customized templates using an AWS Lambda function to replace values.  This customized template will contain the AWS account ID the customer will trust, and the uniquely generated external ID the partner uses to assume the role.

There are two options available: include the two IDs as the default values for the CloudFormation parameters, or hardcode the IDs into the resources section of the template.  If we prepopulate the parameters with the IDs, the user can easily inspect the IDs, but might override them with incorrect data.  If we hardcode the IDs into the resources section, the user will not be presented with any parameters to fill in. This removes the risk of entering erroneous values at the cost of visibility.  We prefer the second option, as it increases the robustness of the process.

Once this customized template has been generated and uploaded to an Amazon S3 bucket, we provide the user with a launch stack URL.  When the user clicks this link (Step 5), they will be directed to the AWS CloudFormation console with the stack name and template location prepopulated, so they can launch the customized template easily.  Embedded in this template is a custom resource, which automatically sends the Amazon Resource Name (ARN) for the created cross-account role back to the APN Partner. (Step 6)  Once the APN Partner receives the role ARN, they can be sure that the CloudFormation template has been launched.  Additionally, this process eliminates all manual steps, including the customer copying and pasting the created ARN back into the APN Partner’s onboarding workflow.

Custom resources provide an additional benefit. They are triggered whenever the CloudFormation stack is updated or deleted.  If the customer modifies the template or deletes the stack, a notification will be sent to the APN Partner, which allows them to react to the change appropriately.  For example, if a user deletes the stack, the partner can reach out and ask if there were any technical problems that led to them discontinuing the service, provide an exit survey, or trigger an off-boarding workflow.

On the APN Partner side, this custom resource takes the cross-account role ARN and puts it in the DynamoDB table that contains the customer data. (Step 7) We now have a customer record that contains their AWS account ID, a unique external ID, and a cross-account role ARN, which can be used together to assume the role in the customer’s account.  As a final cleanup step, the custom resource deletes the customized template from the S3 bucket, since it’s no longer needed.

In summary, we’ve provided a workflow where the customer simply provides their AWS account ID, clicks a launch stack button, and then follows the CloudFormation wizard.  At no point does the user have to interact with the IAM console, copy and paste policy documents and role ARNs, or engage with any other potentially error-prone or manual steps.

With this workflow, we’ve reduced the chances of failure due to misconfiguration or incorrectly typed values, and we’ve minimized onboarding friction to reduce the chance of customers getting stuck or frustrated and abandoning the onboarding process.  As an added benefit, we’ve also provided a way to capture the removal of the trust policy and cross-account role.  This allows APN Partners to proactively reach out to determine if the removal was due to accidental deletion, and engage with customers if there were any technical issues that led to them tearing down the role.

Be sure to read the preceding posts for more detail on each of these steps.  Let us know if you have any questions or comments regarding this process!