Setting up Amazon Q in VSCode using IAM Identity Centre

This week at re:Invent, AWS announced a suite of amazing generative AI–powered assistants, including one that compliments Amazon CodeWhisperer and provides a conversational assistant to help you develop, test, document, and many more developer related activities. All good. I am a big fan and user of these kinds of developer productivity tools, so was eager to try this out on my VSCode setup. My colleague Denis put together a quick start video on how you can "get started with Amazon Q in VSCode in three easy steps", using the Builder ID which allows you to try this without the need for having or setting up an AWS Account. A really great and risk free way of checking out how Amazon Q can help you.

Now whilst using your Builder ID is a great way to get started, you will not have access to some of the more advanced capabilities of Amazon Q, specifically Amazon Q feature development (which is invoked using /dev) and the Code Transformation feature (accessed from within Q via /transform). For that you will need to switch to the Amazon CodeWhisperer Professional Tier, and that is what this post is about. It will walk you through how to set this up.

Note! Throughout this post I will talk about enabling and removing access to Amazon Q. This is only in the context of the Amazon CodeWhisperer Professional Tier. Developers can still enjoy free access to the basic features of Amazon Q by using their Builder ID.

Pre-reqs

Before proceeding, I make the following assumptions to what you have and what you will need.

• An AWS Account with Administrator priviledges
• An AWS Account that is integrated with IAM Identity Centre - in my specific setup, I am using Keycloak as my Identity Provider (Idp)
• A version of the AWS Toolkit for VSCode that supports the new Amazon Q features (I am using version v2.0.0)
• VSCode (I am runing version 1.84.2 on my Mac M1)

Important!! You should be aware that following the steps in this blog post, for every user that you enable via IAM Identity Centre, you will incur charges to your AWS bill. If you are just testing this out, make sure you remove those users via the Amazon CodeWhisperer console at the end to reduce the cost.

Assuming this is all good, lets get started.

Overview

Before diving into how to set this up, it is worth understanding at a high level what you need to do. The documentation provides a good overview in these steps, covering how to manage access of Amazon Q within your AWS accounts. The first thing to take note of is that you configure Amazon Q using the Amazon CodeWhisperer console, so you will see the two names used interchangerbly in this post.

Amazon CodeWhisperer has the concept of an administrator, who are able to determine who can and cannot access Amazon CodeWhisperer. This can be setup in single or more complex AWS account setups, including where you are using AWS Organisations. In this post I am going to be using a single AWS account that has been setup to use single sign on with IAM Identity Centre, and define a single user that I want to give access to Amazon Q.

The approach is:

• Create a new Permissions set in IAM Identity Centre for my Amazon Q / Amazon CodeWhisperer "admins"
• Create two new groups - one for Amazon Q users, and another for Amazon Q admins (the folk who can add/remove access to Amazon Q)
• Add a user into the Amazon Q users group (from the list of users managed by IAM Identity Centre), and add a user into the Amazon Q Admins group
• Configure an AWS account (in this case, my single account) to use these Groups, assigning Permission sets to both (For Amazon Q Users I will add ReadOnly access, for Amazon Q Admins, I will add the new Permissions set created for Amazon Q / CodeWhisperer
• From the Amazon CodeWhisperer console, now assign who I want to give access to (in this case, the Amazon Q Users group)
• Try and login to Amazon Q from VSCode

Step 1 - Create a new Permissions Set and Group within IAM Identity Centre

The first stage is to set up our Admins and Users groups to simplify how we administer access to Amazon Q. To help us we have the very helpful documentation guide, and the page we are specifically interested in is Setting up CodeWhisperer Professional with IAM Identity Center.

We need to create a new Permissions set that we can delegate Amazon Q administrators, and who will have access to add/remove users from the Amazon CodeWhisperer console. We follow the instructions on that page to create the new Permissions set, which in this guide is called "CodeWhisperer_administrator".

Once you have done that, we will create two groups, Amazon-Q-Admins, and Amazon-Q-Users. Click on Groups on the left hand side and then Create Groups, creating your group and assigning any users at the same time.

Now that we have our Groups setup, we can assign these groups together with Permissions sets to our AWS Account. For the Amazon-Q-Users, we will assign the ReadOnlyAccess permissions set (you can use what ever permissions set you typically set up), and for the Amazon-Q-Admins, we assign the CodeWhisperer_administrator group.

That is it for this step.

Step 2 - Enable Amazon Q within the Console

From our AWS Account, we now need to enable (or remove) access to Amazon Q for our developers (in this case, those in the Amazon-Q-Users group). We head over to the Amazon CodeWhisperer console, and click on the Settings menu option on the left.

To add users it is as simple as clicking on the Add Groups button, and then selecting the group we setup in the previous step (Amazon-Q-Users).

That is it, we now have our user (we only defined a single one in this example) enabled for the use of Amazon Q.

Step 3 - Authenticate and use Amazon Q

We are now ready to try this out and log in from our VSCode.

From the AWS Toolkit icon in VSCode, you will see anumber of twisties/sections. One of these will be called "AMAZON Q (PREVIEW)" so click on that to reveal the "SIGN IN TO GET STARTED" link. This will reveal the "Sign in to Get Started" page, and the first panel will be "Amazon Q + CodeWhisperer" like the following screen.

From here, you want to use the "Sign in with Identity Centre (SSO)" link, and then in the dialog that pops up, enter your SSO Url and the AWS region where you have your AWS SSO configured. In my case, I have configured AWS Identity Centre SSO in eu-west-1, so this is what I configure, and then add my SSO link. You will then need to follow a number of steps as outlined in the following screenshot. Between steps 2 and 3 you will probably be asked to log in to your identity provider (I was, but if you are already logged in then you might not have to do this).

If everything from Steps 1 and 2 was setup correctly, then you should now be logged in, and you can now click on the Amazon Q chat icon in VSCode, hit "/" and see /dev and /transform options available to you.

Overview of the steps

For those that prefer to watch these sort of things, this is a short video of me setting this up so you can see this for yourselves.

Conclusion

In this short post I showed you how you can set up users to use the advanced features of Amazon Q, by setting them up on the Amazon CodeWhisperer Professional Tier. If you followed along just to try this out, remember to remove any users to avoid additional charges on your AWS bill.

Troubleshooting

As with all blog posts, what you see is the nice shiny, working stuff. But behind all of that, is typically head scratching errors and problems that come along. So here I want to share some of the things I found that took me a while to figure out.

Configuring Amazon Q access

If you see the following error in the AWS Toolkit logs, then the most likely reason is that you have either not configured the right users/groups within the Amazon CodeWhisperer console settings, or you have not set up the permissions within IAM Identity Centre appropriately.

2023-11-30 12:37:39 [ERROR]: API response (oidc.eu-west-1.amazonaws.com /token): {
  name: 'AccessDeniedException',
  '$fault': 'client',
  '$metadata': {
    httpStatusCode: 400,
    requestId: 'f60ba750-xxxx-4axx-xx30-xxxxb0ecf504',
    extendedRequestId: undefined,
    cfId: undefined
  },
  error: 'access_denied',
  error_description: 'Access denied',
  message: 'UnknownError'
}
2023-11-30 12:37:39 [ERROR]: webviewId="authWebview": Error: Webview error
     -> Error: Webview backend command failed: "startCWIdentityCenterSetup()"
     -> Error: Failed to connect to IAM Identity Center [FailedToConnect]
     -> AccessDeniedException: UnknownError

InvalidGrantException

The main error I came across when putting this post together was that every time I went to authenticate, I would get an error within VSCode that looked like this:

Not particularly helpful, but looking at CloudWatch Trail and setting the AWS Toolkit for VSCode logging to DEBUG, provided me with some clues as to where the problems lied.

The error within VSCode showed

2023-11-30 09:24:10 [ERROR]: API response (oidc.eu-west-1.amazonaws.com /token): {
  name: 'InvalidGrantException',
  '$fault': 'client',
  '$metadata': {
    httpStatusCode: 400,
    requestId: 'xxxxxxxxx',
    extendedRequestId: undefined,
    cfId: undefined
  },
  error: 'invalid_grant',
  error_description: 'Invalid grant provided',
  message: 'UnknownError'
}

And within CloudTrail I could see events failing with the following

..

    "eventVersion": "1.09",
    "userIdentity": {
        "type": "Unknown",
        "principalId": "xxxxx",
        "accountId": "xxxxxx",
        "userName": "Ricardo Sueiras AWS"
    },
    "eventTime": "2023-11-29T18:43:47Z",
    "eventSource": "sso.amazonaws.com",
    "eventName": "CreateToken",
    "awsRegion": "eu-west-1",
    "sourceIPAddress": "xx.67.127.xx",
    "userAgent": "aws-sdk-js/3.345.0 ua/2.0 os/darwin#22.6.0 lang/js md/nodejs#18.15.0 api/sso-oidc#3.345.0",
    "errorCode": "InvalidGrantException",
    "requestParameters": {
        "clientId": "xxxx",
        "clientSecret": "HIDDEN_DUE_TO_SECURITY_REASONS",
        "grantType": "urn:ietf:params:oauth:grant-type:device_code",
        "deviceCode": "xxxxx",
        "platformSessionExpiryRequired": false
   ..
   ..

It turned out that something had got messed up in my local ~/.aws/sso directory, and the fix was pretty simple. I just deleted this directory, and then I was able to resolve the issues. Why did I do this? When exploring the logs output by the toolkit, I saw occasionaly the following lines

2023-11-30 10:19:54 [DEBUG]: SSO token cache: read failed (file not found) key: https://xxxxx-uk.awsapps.com/start

and other related messages. Sometimes you have to play a hunch, and given that these are just cached files that I could regenerated, it seemed like a simple thing to try.