Continue using Device Code for SSO with AWS CLI

[#1]

The AWS Command-Line Interface utility was recently updated in an attempt to improve the single-signon authentication process by reducing the number of manual steps. The implementation of this approach, however, will break many workflows. Most notably for us here, that possibly includes the SAS Viya 4 Infrastructure as Code for Amazon Web Services.

So let's get into how to keep things working and look a little more closely at how we got here.

What's the problem look like?

In order to use the AWS Command-Line Interface utility - what I'll call "awscli" here for short - to manage resources in AWS, you need to authenticate to tell Amazon who you are first. The command to do so:

aws configure sso

And it prompts you for information that it needs to configure your access. About halfway through the process, it will generate a URL for you to visit in a web browser to complete authentication. After visiting the URL, the browser then complains that it cannot reach the localhost address, 127.0.0.1.

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

To be clear, this is not a problem with the awscli. If you get this error condition, then there is a problem with your environment. And we can fix it.

Fix it first

I'm not gonna make you wait any longer. Let's fix the problem now and explain why after.

aws configure sso --use-device-code

This "--use-device-code" parameter tells the awscli to revert back to older behavior - probably one you're expecting to see where you're given a simpler/shorter url followed by an 8-letter code to type into the browser as part of authentication.

Not a bad fix, really. Just add the "--use-device-code" parameter and everything works as you expect. This simple edit should allow your established process flow using awscli to continue working.

When is this a problem?

In simplest terms, this new, default behavior is a problem when you run the awscli on a different host than the web browser being used for authentication. The new, default behavior requires that the awscli and an interactive web browser exist together.

And by interactive web browser, I mean one that provides JavaScript and cookies since the OAuth process requires it. So, it's not a simple HTTP RESTful interface you can script the "curl" command for. That means you need Firefox or Chromium or any such GUI-based web browser.

Now, think about remotely adminstering an environment over SSH where you're running the awscli at arm's length. In order for an interactive web browser to run alongside the awscli on the same host, then you'll need to also fire up an X11 server to render the browser's interface on your screen. That's a pretty tall requirement that might be challenging in some scenarios - especially if there are firewall restrictions between your X11 server and the remote host. But, it is doable.

Now, let's go one farther.

The SAS Viya 4 Infrastructure as Code for Amazon Web Services project (a.k.a., viya4-iac-aws) can be run as a Docker (OCI-compliant) container (how to). There are good reasons to do this; mainly because it then includes all of the necessary software utilities at known-good versions - including the awscli.

This saves you a lot of hassle since you don't need to worry about installing individual utilities - as well as all their upstream dependecies - on your PC yourself.

But a Docker container can be considered similar in many ways to a remote host. The processes running in the container are meaningfully isolated from your PC. In particular, this matters when trying to authenticate using the awscli now.

To make this plain, here's how I invoke the awscli to run inside the viya4-iac-aws container:

docker container run -it --rm --group-add root --user 1000:1000  \
                     -v /home/cloud-user/.aws:/.aws \
                     --entrypoint aws viya4-iac-aws

In my screenshots above, I've simplified this by using an alias "aws" for that long command instead.

With its new, default authentication behavior, the awscli is now firing up a simple web server at a randomly assigned free TCP port (shown in the example above as 39171 - but different each time). That's why the web browser is redirected to 127.0.0.1 -- it's trying to talk back to the awscli on localhost.

Without the ability to close the authentication loop, then we cannot proceed to finish the signon process.

While it's possible to publish a TCP port for a process inside the container so it's visible outside the container, you define that route when you start running the container. We can't do that here because the awscli doesn't request the free, random port until after the container is already running. This means that there's no obvious way to run the awscli in a container to perform the new, default single-signon authentication.

Let's talk versions

The awscli changed to its new, default single-signon behavior at version 2.22.0. This new behavior implements Proof Key Code Exchange (PKCE), an extension to the OAuth 2.0 Code Grant Flow. (read more about PKCE and device code authorization with OAuth). Awscli version 2.22 also introduced the "--use-device-code" parameter to keep the legacy SSO signon behavior available. (see the changelog)

The viya4-iac-aws release 8.7.0 includes the awscli at version 2.17.58.

The viya4-iac-aws release 8.8.0 - the latest at time of this post - includes the awscli at version 2.24.16.

So, if you go with the latest viya4-iac-aws today and run the awscli from inside that container, you'll get the new PKCE behavior by default. Alternatively, if you pin back an older viya4-iac-aws, then you'll get an older awscli that doesn't have PKCE ability.

Pin to an older version if you really need to, but if you stick with the latest viya4-iac-aws, it's easy to get the legacy device code authentication approach with the "--use-device-code" parameter.

Wrapping this up

The new, default approach to SSO authentication implemented by the awscli is intended to streamline the process by removing a manual step where you enter the 8-letter device code into a prompt in your web browser. This works great for environments where you are running the awscli and an interactive web browser on the same host, like your PC.

But if you find you're stuck where this doesn't work, then provide the "--use-device-code" parameter when performing SSO authentication with the awscli to restore the legacy behavior that your established process might expect.

Find more articles from SAS Global Enablement and Learning here.