Azure AD Meets AWS: A Developer's Guide to SAML Federation in the Real World

When I first started working with AWS in a financial services environment, one of the first things I ran into was the credential problem. Our organization runs Azure Active Directory for everything — Office 365, internal apps, VPN, the works. But the moment I opened a terminal and needed to run an AWS CLI command, I was completely on my own. No SSO, no federation. Just a browser window, a manual copy-paste of temporary credentials, and a one-hour expiry ticking down while I tried to get work done.

Someone on our team pointed me to aws-azure-login — an npm package that bridges your Azure AD identity directly to AWS CLI access. I’ve been using it since and it genuinely changes how you work in an environment where Azure is the identity backbone and AWS is where you’re building. In this post I want to break down how it works, what it’s actually doing behind the scenes, and why it matters in enterprise environments like ours.

Section 01

The Problem I Was Trying to Solve

Our environment is Azure-first. That’s true of a lot of large financial services companies — Azure AD was deployed years before anyone started seriously moving workloads to AWS, and it owns identity. But AWS has its own IAM system, and by default the two have nothing to do with each other.

The workarounds I kept hitting were all painful in different ways:

Long-lived IAM access keys — fine for service accounts but a real security and rotation problem for individual developers
Logging into the AWS console via our Azure SSO portal, navigating to the credentials page, copying three values manually into a terminal — every single hour
Asking our cloud team to set up AWS IAM Identity Center — always on the roadmap, never quite done

What I actually wanted was simple: I already proved who I am to Azure AD when I logged into my machine this morning. Why can’t AWS just trust that? It turns out it can — through SAML federation — and aws-azure-login is the tool that automates the whole handshake from the command line.

If this sounds familiar

This pattern shows up constantly in financial services and insurance companies. Azure AD came first, AWS came later, and now developers are stuck managing two identity worlds. If your org is in this situation, this tool is worth knowing about even if your cloud team eventually sets up something more formal.

Section 02

The Foundation: SAML Federation and Why AWS Trusts Azure

Before I get into what the package does, it’s worth understanding the mechanism underneath it — because once you get it, the whole thing makes intuitive sense.

The protocol at work here is SAML 2.0 (Security Assertion Markup Language). It’s the standard that lets an Identity Provider vouch for a user to a Service Provider without the service provider ever seeing the user’s password. In our setup:

Identity Provider (IdP) — Azure AD. It’s the source of truth for who I am.
Service Provider (SP) — AWS. It decides what I’m allowed to do once my identity is confirmed.

The way I think about it: Azure AD hands AWS a sealed, signed envelope that says “we’ve verified this person is who they say they are, and they belong to these groups.” AWS opens the envelope, checks the signature, maps the groups to IAM roles, and issues temporary credentials. AWS never sees my password — it only trusts the signature on that envelope. Here’s what that flow looks like:

// SAML federation — identity flow

Developer

CLI / Terminal

Initiates login
Provides credentials + MFA

→

SAML
request

Identity Provider

Azure AD

Authenticates user
Issues SAML assertion

→

SAML
assertion

Service Provider
AWS STS
Validates assertion
Returns temp credentials

→

Access Key
Secret Key
Session Token

Destination

AWS CLI / SDK

Uses temporary
credentials

The key thing I want to highlight here: AWS never verifies your password. It only ever sees a signed XML assertion from Azure AD. The actual authentication — password check, MFA challenge, Conditional Access policies — all of that happens entirely inside Azure. AWS is just trusting Azure’s signature. This is what makes the whole thing both secure and practical in environments where Azure owns identity.

Section 03

What’s Actually Happening When You Run aws-azure-login

This is the part I found most interesting when I first looked into it. The Azure AD login page is a JavaScript-heavy single-page application — there’s no simple API endpoint you can POST credentials to. Microsoft doesn’t expose a stable programmatic login API for this flow.

So instead of trying to reverse-engineer it, aws-azure-login uses Puppeteer — a Node.js library that drives a real headless Chromium browser. It literally opens a browser window in the background, loads the Azure login page, types your credentials, handles the MFA prompt, and extracts the SAML assertion from the response. It’s browser automation in service of identity federation.

Here’s every step of what happens under the hood from the moment you hit enter:

Reads your local AWS config

The package reads your ~/.aws/config file for the profile you pass in. It’s looking for three things: your azure_tenant_id, your azure_app_id_uri (the App ID URI of the AWS Enterprise Application registered in your Azure AD tenant), and your azure_default_username. Your Azure federation admin should have these — they’re not secrets, just identifiers.

Launches a headless Chromium browser via Puppeteer

A real Chromium instance spins up in the background. You don’t see it unless you pass --mode gui, but it’s a genuine browser — rendering JavaScript, handling cookies, the whole thing. This is what makes the solution work against a login page that would break any simple HTTP client.

Loads the Azure AD login page

The browser navigates to the Azure login URL built from your tenant ID and App ID URI. This is the exact same Microsoft login page your browser hits when you open Office 365 — the package isn’t hitting any special endpoint, just automating the same flow you’d do manually.

Fills in credentials and handles the MFA challenge

Puppeteer types your username and password into the page. Then — and this is the part that’s easy to miss — it pauses and prompts you in the terminal for your MFA code. You type it in, it enters it into the browser. In our environment this is a Microsoft Authenticator code. It works the same way regardless of which MFA method your org uses.

Extracts the SAML assertion from the response

Once Azure authenticates you, it posts a SAML response back through the browser. Puppeteer intercepts the page at that point and pulls out the Base64-encoded SAML assertion — a signed XML document that says who you are, what tenant you belong to, and which Azure AD groups you’re a member of. This document is the thing that gets handed to AWS.

Parses the available AWS roles from the assertion

Inside that SAML XML there are https://aws.amazon.com/SAML/Attributes/Role attributes — one per IAM role you’re authorized to assume. If you’re in multiple groups mapped to different roles (developer, read-only, admin), you’ll see a list and get to pick. If there’s only one, it’s automatic. Your Azure AD group membership is what drives this, which is the clean part.

Calls AWS STS AssumeRoleWithSAML

With the SAML assertion and the role ARN you selected, the package calls the AWS STS AssumeRoleWithSAML API. AWS checks the assertion signature against the Azure AD signing certificate it has on file (set up in the Enterprise Application configuration), confirms it’s valid and unexpired, and hands back temporary credentials: an Access Key ID, Secret Access Key, and Session Token.

Writes temporary credentials to ~/.aws/credentials

The credentials land in your ~/.aws/credentials file under the profile you specified. From that point your AWS CLI, any SDK — boto3, the AWS SDK for .NET, Terraform — picks them up automatically. They’re valid for up to an hour by default. When they expire, you just run the command again. One minute of terminal interaction instead of the browser dance.

What I appreciate about this security model

My password never touches AWS. Not even a hash of it. AWS only ever receives a signed XML document from Azure — it has no way to verify my credentials independently, and it doesn’t need to. If my session gets somehow intercepted, the attacker has temporary credentials that expire in an hour with permissions scoped to a single IAM role. There are no long-lived access keys to accidentally commit to a repo or forget to rotate.

Section 04

Getting It Set Up

Setup is straightforward. You’ll need Node.js 12 or higher and two pieces of information from whoever manages your Azure AD tenant — your Azure Tenant ID and the App ID URI of the AWS Enterprise Application. These are the two values that tell the package which Azure tenant to authenticate against and which AWS application to request access to.

Install the package

Install it globally so you can run it from any directory:

terminal bash

# Install globally so you can run it from any directory
npm install -g aws-azure-login

# Verify installation
aws-azure-login --version

Configure your profile

Run the configure command once per profile. It walks you through an interactive prompt — just have your tenant ID, App ID URI, and corporate email ready:

terminal bash

aws-azure-login --configure --profile mycompany-dev

# You will be prompted for:
# Azure Tenant ID:   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# Azure App ID URI:  https://signin.aws.amazon.com/saml
# Username:          [email protected]
# Default role ARN:  (optional — skip if you want to choose at login)
# Default session duration (hours): 1

That writes a block to your ~/.aws/config file that looks like this — nothing sensitive, just configuration identifiers:

~/.aws/config ini

[profile mycompany-dev]
azure_tenant_id     = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
azure_app_id_uri    = https://signin.aws.amazon.com/saml
azure_default_username = [email protected]
azure_default_role_arn = arn:aws:iam::123456789012:role/Developer
azure_session_duration = 3600
region              = us-east-1

Log in and get to work

terminal bash

# Login with your configured profile
aws-azure-login --profile mycompany-dev

# Use the credentials with the AWS CLI
aws s3 ls --profile mycompany-dev

# Or export the profile for the whole terminal session
export AWS_PROFILE=mycompany-dev
aws s3 ls

When the headless flow breaks

This has happened to me — Microsoft changes something in the login page and suddenly the automation fails silently. The fix is to run with --mode gui which opens the browser visibly so you can watch exactly where it’s getting stuck. Nine times out of ten it’s a new UI element Puppeteer isn’t handling. Check the GitHub issues page — breakages get reported and patched quickly.

Section 05

Why This Matters Beyond Just Convenience

I want to be clear that this isn’t just a quality-of-life improvement for developers. There are real operational and security properties here that matter in enterprise financial environments — things that come up in security reviews and compliance conversations.

No long-lived access keys in the wild

Every credential this tool produces expires in an hour. There are no static IAM access keys to rotate, audit, or accidentally push to a GitHub repository. In a financial services environment where audit trails matter, not having long-lived developer credentials floating around is a meaningful security improvement.

Offboarding is handled in one place

When someone leaves the team and gets disabled in Azure AD, their AWS access disappears automatically — they can’t get a valid SAML assertion anymore. You don’t need to remember to separately deprovision an IAM user in a different system. Identity lifecycle management lives where it already lives: Azure AD.

Your existing MFA policy applies automatically

Whatever Conditional Access or MFA policies your security team has configured in Azure AD automatically cover AWS CLI access too. There’s no separate MFA setup in AWS, no additional policy to maintain. Our security team enforces it in Azure, and it just works for AWS without any extra configuration on our end.

AWS role access follows your Azure AD group membership

IAM roles are mapped to Azure AD security groups in the Enterprise Application configuration. Adding a developer to the right Azure group grants them the corresponding IAM role at their next login — no separate IAM changes needed. The access model is managed by whoever already manages group membership in your directory.

It lays the groundwork for more serious AWS adoption

Getting SAML federation working between Azure AD and AWS — even informally through this tool — establishes the identity pattern that scales. When our team eventually moves to AWS IAM Identity Center or expands our AWS footprint, the conceptual plumbing is already understood and partially in place. The federation trust relationship exists; we’re just formalizing it.

Role access maps to existing Azure AD groups

IAM roles are mapped to Azure AD security groups in the Enterprise Application configuration. Adding a developer to the “AWS-Developers” Azure group grants them the corresponding IAM role automatically at their next login. No separate IAM permission changes are needed.

Section 06

The One Real Limitation Worth Knowing About

I want to be honest about this because I’ve hit it myself: aws-azure-login is inherently brittle. The package documentation says this openly, and the maintainers deserve credit for that transparency.

Because the tool is driving a real browser through a UI that Microsoft controls, any change on their side can break the automation without warning. This has happened. The Azure login page gets updated, Puppeteer can’t find the element it’s looking for, and the tool fails. It usually gets patched within a few days once someone files an issue, but if you’re on a deadline and it breaks on a Tuesday morning, that’s not great.

A few things I’d recommend if you’re rolling this out to a team:

Pin to a specific version and test upgrades before pushing to everyone
Make sure everyone knows about --mode gui — visible browser mode lets you authenticate manually when the headless flow breaks
Keep the GitHub issues page bookmarked — if something breaks, the fix is usually already there
Think of this as a bridge tool while your org evaluates AWS IAM Identity Center for a more robust long-term solution

Don’t use this in CI/CD pipelines

This tool is for interactive developer use only. It requires a terminal prompt for MFA — there’s no way to automate that step without compromising your MFA policy entirely. For automated pipelines, use IAM roles on EC2 or ECS task roles, or set up GitHub Actions OIDC federation with AWS. Those approaches skip credentials entirely and are the right pattern for automation.

No Keys, No Problem: How AWS Identity Federation Actually Works

Leave a Reply Cancel reply

The Problem I Was Trying to Solve

The Foundation: SAML Federation and Why AWS Trusts Azure

What’s Actually Happening When You Run aws-azure-login

Getting It Set Up

Install the package

Configure your profile

Log in and get to work

Why This Matters Beyond Just Convenience

The One Real Limitation Worth Knowing About

Similar Posts

Leave a Reply Cancel reply