DEV Community: Ira Rainey

Human-First Engineering

Ira Rainey — Mon, 20 Apr 2026 15:18:40 +0000

There is a question that keeps coming up in conversation at the moment, but one that doesn't seem to have a good clear answer anywhere: How, as engineers, do we use AI tooling productively and not deskill ourselves in the process — and how do we keep supporting those earlier in their careers?

My answer has always been that it is more important than ever to understand what good looks like. Which is fine in principle. It is less useful when someone pushes back and asks what that means in reality, or how you actually apply it when an engineer just raised a pull request with 500 lines of AI-generated code that nobody actually understands.

That gap is where the idea for Human-First Engineering came from. It is a lightweight manifesto and framework you can adopt today to address these very issues. Everything is published at humanfirstengineering.dev, with the source on GitHub under a permissive licence so you can fork it, adapt it, and run with it.

Why is it different this time?

As engineers we have long had productivity assistive tooling. Compilers, IDEs, autocomplete, intellisense, static analysis — these all made our lives easier and largely automated the tedious bits. But AI tooling is different. It can automate the parts engineers actually learn from: reading code, working through a bug, sketching a design, explaining what your code does to another human. Those moments of friction are where the intuition comes from. They are how engineers build the judgement they rely on later.

Automate those at scale, without thinking about it, and you get a generation of engineers who can ship things but cannot reason about what they shipped or why.

And that risk is not evenly distributed. It falls most heavily on the engineers entering the industry now. The senior engineers of five years hence are the juniors of today. If AI quietly routes them around the struggle that creates seniors, we are not going to notice the damage until it is too late to fix.

The failure modes I see

A lot of the conversation about AI-assisted engineering gets framed as "too much AI vs too little." In practice, the real failure modes are subtler.

The most common one is using these tools without really understanding what they are generating. Engineers accept output because it looks plausible, without the reading and reasoning that would normally catch the issues. The mistakes that show up here are rarely spectacular — they are small, quiet, and compound. Clean architecture; separation of concerns; security; performance; all become invisible in an ever-growing weave of spaghetti code, that is a maintainability timebomb waiting to explode.

Another issue that gets discussed less than it should: dependency risk at the individual level. I've heard from engineers who lean heavily on an AI tool, hit their token or quota limit mid-cycle, and then spend the rest of the period noticeably less productive than they were before the tool existed, even with more generous enterprise subscriptions. A skill you have outsourced is a skill you don't have when the outsourcing stops.

Both of these are symptoms of the same thing: treating AI as a productivity multiplier without treating the use of AI as a skill in its own right. That framing is what this framework is built to address.

What follows is an attempt to make that framing concrete — something a team can actually pick up and use.

What is the framework?

Human-First Engineering is built on eight beliefs and five core pillars. The beliefs are the why; the pillars are the how. The pillars are where the operational content lives:

Think first — understand the problem before you prompt. AI accelerates execution, not understanding.
Own the output — every line has a named human owner. If you cannot explain it, you do not ship it.
Grow through AI, not around it — use AI to reach harder problems and understand more deeply, not to avoid the discomfort of not knowing. This is the pillar that protects the pipeline.
Use AI intelligently — model choice, context, prompting, and instruction files are skills. Using AI well is part of the modern craft.
Trust AI, but verify everything — calibrate trust to the risk. Human reasoning leads on anything sensitive, irreversible, or security-critical.

If you need the whole thing in one line:

Think first. Own what you ship. Grow through AI, not around it. Use AI intelligently. Verify everything.

Each pillar has a small set of concrete behaviours. No process. No ceremony. The aim is to be light enough to actually remember, and concrete enough to change the questions asked in a code review.

The whole thing is deliberately small. You should be able to read the manifesto and framework in ten minutes.

The toolkit

The framework on its own is useful as a shared mental model, but adoption needs more than beliefs. So alongside it there is a toolkit — the bit that turns the manifesto into something a team can actually run.

Implementation Guide — a ten-step rollout plan: introduce the manifesto, then the framework, then embed both into the rituals you already have.
Practices — concrete patterns for how engineers use AI day to day.
Slide Deck — a ready-to-present deck for a 30–45 minute team session, editable like code.
Developer FAQ — the questions engineers actually ask. Honest answers, not corporate ones.
For Early-Career Engineers — written for junior engineers, not about them. Practical habits for using AI to grow rather than stall.
Templates and Prompts — drop-in instruction files for GitHub Copilot and Claude Code, plus reusable prompts for framing, reviewing, and risk-assessing AI-assisted work.

How to adopt it

Three sensible paths, depending on how much energy you have:

Just the framework. Read the manifesto and framework. Share both with your team. Use the one-line summary as a shared vocabulary in code reviews and retros. That alone will shift how people talk about AI-assisted work.
Framework plus a team session. Add the slide deck and run a 30–45 minute session. Follow up with the developer FAQ and the early-career guide as written references.
Full adoption. Run the implementation guide end-to-end. Drop the instruction files into your repositories. Add the prompts to your team's shared prompt library. Set a quarterly review on the calendar.

Everything is CC BY-NC-SA 4.0. Fork the repo, cut what does not fit your context, add the examples that will land with your team. The goal is for the principles to be lived, not for the artifacts to be preserved.

If it is useful to you, take it. If it sparks a better idea, tell me about it — I'd love to hear what you do with it.

Site: humanfirstengineering.dev
Source: github.com/irarainey/human-first-engineering

Important: A VS Code Extension That Keeps Your Python Imports Clean

Ira Rainey — Sat, 07 Mar 2026 14:51:06 +0000

If you've ever spent time manually cleaning up Python imports after a review comment saying "wrong order" or "import the module, not the symbol", you'll appreciate this.

Important is a free, open-source VS Code extension that validates and auto-fixes Python import statements according to the Google Python Style Guide and PEP 8. It gives you real-time feedback as you type and can fix every issue it raises with a single command.

Why another import tool?

Ruff and isort are great at sorting imports, but they don't enforce the style rules that teams adopting the Google guide care about — things like importing modules instead of symbols, banning wildcards, or flagging unjustified aliases. Important fills that gap, and its output is designed to be Ruff-compatible so the two tools don't fight each other.

What does it do?

Here's a quick overview of what Important validates and fixes:

Rule	Example	Auto-Fix
No relative imports	`from .module import x` → absolute	✅
No wildcard imports	`from os.path import *` → qualified access	✅
One import per line	`import os, sys` → separate lines	✅
Import modules, not symbols	`from PIL import Image` → `import PIL`	✅
Standard aliases only	`import numpy as npy` → `import numpy as np`	✅
Justified from-aliases only	Flags pointless `as` renames	✅
Unused imports	Removes dead imports	✅
Duplicate imports	Merges duplicates	✅
Correct ordering	`__future__` → stdlib → third-party → first-party → local	✅
Sorted within groups	`import` before `from`, then alphabetical	✅
Misplaced imports	Lazy imports inside functions get relocated	✅

Every rule has an auto-fix — no manual intervention required.

See it in action

Take this messy import block:

import requests
import os, sys
from os.path import *
from models.user import User
import json

print(abspath("."))
user = User()

Run "Important: Fix Imports in This File" (Ctrl+K, Ctrl+Shift+F) and you get:

import json
import os
import sys

import requests

from models import user

print(os.path.abspath("."))
user = user.User()

Imports are split, sorted into groups, wildcard usage is converted to qualified access, and symbol imports are rewritten to module imports — all references in your file are updated automatically.

Real-time diagnostics

You don't need to run the fix command to see problems. Important validates as you type, highlighting issues directly in the editor:

Warnings for rule violations (wrong order, wildcards, symbol imports)
Faded text for unused imports (matching VS Code's convention)
Hover info explaining exactly what's wrong and why

Each diagnostic links to the relevant style guide rule, so you learn the conventions as you go.

Smart features

A few things that set Important apart from a basic linter:

Ruff-compatible output

Sorted imports match Ruff/isort defaults — import before from, order-by-type name sorting (CONSTANT_CASE → CamelCase → snake_case), aliased imports kept on separate lines. You can run both tools without conflicts.

Multi-line formatting

Long from imports are automatically wrapped into Ruff-style parenthesised multi-line format when they exceed the line length:

from mypackage.models import (
    BaseModel,
    ConfigModel,
    UserModel,
)

The line length is auto-detected from your pyproject.toml ([tool.ruff] → line-length) or can be set manually.

`if TYPE_CHECKING` support

Imports inside if TYPE_CHECKING: blocks are handled correctly — all sorting and validation rules apply within the block, but the import-modules-not-symbols rule is relaxed since these imports exist purely for type annotations.

First-party module detection

Important automatically reads known-first-party from [tool.ruff.lint.isort] in your pyproject.toml and groups those imports correctly between third-party and local. Monorepo support is built in — nested pyproject.toml files scope their first-party modules to the relevant subtree.

Inline suppression

Need to keep a specific import the way it is? Add a # noqa: important comment:

from os.path import join  # noqa: important[import-modules-not-symbols]

You can also use a quick-fix action to add the suppression comment directly from the editor.

Configuration

All settings live under important.* in VS Code:

{
  "important.validateOnSave": true,
  "important.validateOnType": true,
  "important.styleGuide": "google",
  "important.knownFirstParty": ["myproject"],
  "important.readFromPyprojectToml": true,
  "important.lineLength": 0
}

Setting lineLength to 0 (the default) auto-detects from pyproject.toml, falling back to 88.

Install it

You can install Important directly from the VS Code Marketplace:

👉 Install Important

Or search for "Important" in the VS Code Extensions panel (Ctrl+Shift+X).

The source is on GitHub under the MIT licence — contributions and issues welcome.

If you work on a Python codebase that follows (or wants to follow) the Google Style Guide, give Important a try. It catches the things that linters miss and fixes them without you lifting a finger.

A Consent Dialog Listed 1,467 Partners — So I Used AI to Unmask Them

Ira Rainey — Sat, 07 Mar 2026 13:28:36 +0000

The Moment That Started It All

Someone sent me a link to an article about a bench on Bristol Live — a local UK news site — and when I clicked on it, a consent dialog popped up. Nothing unusual there. But something made me look closer at the fine print this time. The dialog was asking me to agree to share my data with 1,467 partners.

One thousand, four hundred and sixty-seven. For a story about a bench.

I'm not saying that advertising isn't important to allow businesses to generate revenue, but this felt a big much. Curious as to why, I tried to find out more. I clicked and scrolled through the partner list in the dialog, clicking into individual entries, reading purpose descriptions and "legitimate interest" declarations and quickly found myself deep in a rabbit hole. Hundreds of companies I'd never heard of, vague descriptions of data processing purposes, toggles nested inside toggles. After ten minutes I was no closer to understanding what any of these companies actually did with my data, or why a local news article needed nearly fifteen hundred of them. The dialog was technically giving me information, but in practice it told me almost nothing.

That's when I thought: there has to be a better way to find out more about what's going on. And the result is an open-source application called Meddling Kids.

The Illusion of Choice

A recent BBC article titled "We have more privacy controls yet less privacy than ever" hit the nail on the head. We're surrounded by cookie banners, privacy settings, and consent dialogs — yet somehow we end up with less privacy, not more. The article cites Cisco's 2024 Consumer Privacy Survey: 89% of people say they care about data privacy, but only 38% have actually done anything about it.

And honestly, can you blame the other 62%? The consent mechanism is designed to exhaust you into clicking "Accept". The alternative is scrolling through hundreds of partner names, deciphering purposes written in legalese, and toggling individual switches — all before you can read the article you came for - about a bench. Dr Carissa Veliz, author of Privacy is Power, put it well: "Mostly, people don't feel like they have control."

As a software engineer, that felt like an itch I should at least start to scratch. I figured if I could automate the process of visiting a site, accepting its consent dialog, and then capturing exactly what happens behind the scenes — cookies dropped, scripts loaded, network requests fired, storage written — maybe I could pull the mask off what's really going on.

Enter the Meddling Kids

Meddling Kids is a Scooby-Doo inspired privacy analysis tool, because they always unmasked the villain in the end. You give it a URL, it visits the site in a real browser, detects and dismisses the consent dialog, and then captures everything it sees: cookies, scripts, network traffic, localStorage, sessionStorage, and more. It then uses AI to analyse all of that data and produce a privacy report with a deterministic score out of 100.

The tech stack is a Vue 3 + TypeScript frontend with a Python FastAPI backend. Browser automation is handled by Playwright, running in headed mode on a virtual display (Xvfb) so that ad networks don't block it for being headless. Results stream to the UI in real time via Server-Sent Events.

But the interesting part is how AI is woven into pretty much every stage of the analysis doing what it is good at - analysing large amounts of data quickly.

AI All the Way Down

Vision Models for Consent Detection

The first challenge is detecting the consent dialog itself. These overlays vary wildly across sites — different consent management platforms, different layouts, different button labels. A brittle CSS selector approach wasn't going to cut it.

Instead, Meddling Kids takes a screenshot of the loaded page and sends it to a vision-capable LLM. The model looks at the screenshot and identifies whether an overlay is present, what type it is (consent dialog, paywall, sign-in prompt, etc.), and the exact text of the button to click. If the model is confident enough, Playwright clicks that button, and the tool captures a before-and-after comparison.

There's a fallback chain too: if the vision call times out or can't parse the dialog, a text-only LLM attempt runs against the page content, and if that also fails, a local regex parser takes over. No single point of failure.

Structured Analysis with the Microsoft Agent Framework

Under the hood, the analysis pipeline uses the Microsoft Agent Framework to orchestrate eight specialised AI agents. Each agent has a focused role — consent extraction, tracking analysis, script classification, cookie explanation, storage analysis, report generation, and summary findings — and they coordinate through a concurrent pipeline with controlled parallelism.

The structured report agent, for example, generates ten report sections in parallel, while a global semaphore limits concurrent LLM calls to avoid overwhelming the endpoint. Each agent uses structured output with JSON schemas and Pydantic models, so the responses are deterministic and parseable — no fragile prompt-and-pray string parsing.

The application has the ability to log everything to file so it can be analysed more closely, from operations logs, through Agent Framework threads, to final privacy reports.

The Pipeline

The whole analysis runs as a six-phase streaming pipeline over SSE, so results appear in the UI as they happen rather than after a long wait:

Navigation — Playwright opens an isolated browser context, navigates to the URL, and waits for the network to settle and content to render.
Page load and access check — Detects bot protection or access denied responses and bails out early if the site blocks us.
Initial data capture — Snapshots cookies, scripts, network requests, and storage before any consent interaction. This is the pre-consent baseline — anything captured here was tracking you before you clicked a thing.
Overlay handling — The vision model detects overlays, Playwright clicks through them, and a consent extraction agent pulls out partner lists, purposes, and CMP details. TC and AC consent strings are decoded and vendor IDs resolved against the IAB Global Vendor List and Google's ATP provider list.
Concurrent AI analysis — Three workstreams run in parallel: script grouping and classification, a structured ten-section privacy report, and a tracking risk analysis. Once the tracking analysis finishes, a summary agent distils everything into prioritised findings. A global semaphore caps concurrent LLM calls at ten to avoid hammering the endpoint.
Completion — The final privacy score, report, and summary stream back to the client.

Making Sense of the Data

A single news site analysis can surface hundreds of cookies, dozens of scripts, and thousands of network requests. No human is going to read through all of that manually, and that's exactly the point — the consent dialogs are counting on it.

The AI doesn't work in a vacuum though. Bundled with the tool are local databases sourced from public and permissively licensed sources that provide grounding context for the analysis — a form of RAG without a vector store. These include over 19,000 known tracker domains (from Privacy Badger, AdGuard, and EasyPrivacy), nearly 500 script URL patterns, the full IAB Global Vendor List (1,111 TCF vendors), Google's ATP provider list (598 providers), cookie and storage pattern databases, CMP platform signatures, 574 partner risk profiles across eight categories, and media group profiles for 16 UK publishers. This reference data is injected into agent prompts so the LLM can match what it finds against known entities rather than guessing — and it means a large chunk of the classification is deterministic before the model even gets involved.

The AI agents summarise what the tracking data actually means in plain language. They surface the risk: which cookies are from data brokers, which scripts are fingerprinting you, which network requests fire before you've even had a chance to consent. The tool also decodes IAB TCF consent strings (those opaque euconsent-v2 values) and Google's Additional Consent strings to show exactly which vendors and purposes are encoded.

Where possible every cookie, script, and network request is explained and attributed to the company behind it. This makes it very clear what is going on behind the scenes.

Perhaps most usefully for non-technical users, there's a "What You Agreed To" digest — a two to three sentence summary, written at roughly a 12-year-old reading level, explaining what clicking "Accept" actually meant. Something like: "By clicking Accept, you allowed 847 companies to track your browsing activity and share data about you, including with data brokers."

Smart Caching to Keep Costs Down

Running vision and language models isn't free, so the tool caches aggressively. Script analysis is cached by script domain, not by the site being scanned — so a Google Ads script analysed on one site is an instant cache hit when the same script appears on another. Overlay dismissal strategies are cached per domain too. In testing against a large news site, a cold run made 72 LLM script calls while subsequent warm runs made zero.

Try It Yourself

The whole thing is open source under AGPL-3.0, and you can pull a pre-built Docker image from GitHub Container Registry and have it running in minutes:

docker run -p 3001:3001 \
  -e AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/ \
  -e AZURE_OPENAI_API_KEY=your-api-key \
  -e AZURE_OPENAI_DEPLOYMENT=your-deployment \
  ghcr.io/irarainey/meddlingkids:latest

It works with both Azure OpenAI and standard OpenAI — you just need to bring your own model with vision capabilities. I used gpt-5.2-chat for the main analysis and vision work, and gpt-5.1-codex-mini for script analysis. Point your browser at http://localhost:3001 and start unmasking.

If you prefer you can also clone the repo and run it locally with Python and Node in the devcontainer, or build the Docker image yourself using the docker compose file included docker compose up --build.

Everything you need to get going — setup, configuration options, Docker Compose, local development — is in the README on GitHub. There is also a comprehensive developer guide explaining how it all works.

What I Learned

Building this tool confirmed what I suspected: the scale of tracking on mainstream websites is genuinely staggering. Some UK news sites drop cookies before you've even interacted with the consent dialog. Scripts from dozens of advertising, analytics, and fingerprinting vendors fire tracking, selling, and sharing your data. Everything from the stories you read, your health and political interests, precise location, and device characteristics. If you're logged into social media on the same device then often this is also automatically shared with them too, driving the algorithms of what appears in your feed. The consent dialog is, in reality, an illusion of control over your data, wrapped in legal form.

Prof Alan Woodward from Surrey University, quoted in that BBC article, argues that when people assume they're constantly tracked, they self-censor, and that harms free speech and weakens democracy. It's a strong claim, but spend a few minutes watching the tracker graph light up on a typical news site and it starts to feel less academic.

I don't think the answer is purely technical. There are some great privacy tools out there you should be using, and together with better regulation, better enforcement, and a cultural shift around data privacy all matter more than any tool I can build. But as software engineers, we're in a unique position to make the invisible visible. If nothing else, Meddling Kids lets you see exactly what you're agreeing to — and maybe that's worth knowing before you click "Accept" next time.

Oh, and that Bristol Post article? When unmasked it scored 100 out of 100.
Zoinks!

The source code is on GitHub:
github.com/irarainey/meddlingkids

If you find it useful, give it a star. And if you run it against your own favourite news site, I'd love to hear what you find.

How to Delete Multiple Azure Resources all at Once with Beeching

Ira Rainey — Mon, 01 May 2023 15:43:18 +0000

You know what it's like - you're working on some IaC and spinning up loads of different resources at once, or you've been playing around with ideas and now you're left with a raft of bits and pieces to clean up to save yourself some money, but going into the portal and finding them all can be a hassle, and writing loads of Azure CLI delete statements is a pain. If only there was a tool that offered a single CLI command you could run to delete a bunch of selected stuff at once. Well, now there is. - welcome to Beeching.

Beeching is a command line tool to help you quickly and easily delete Azure resources you no longer need. Inspired by The Beeching Axe it allows you to cull vast numbers of resources across a subscription with a single swing of the axe. It can delete multiple resource types at the same time, based on a name, part of a name, or by tag value.

Resources can be protected from the axe by specifying them in an exclusion list. This allows you to shield resources that you wish to keep. The list of resources can be further restricted to only cull certain types of resource by using another switch.

Locked resources? No problem, Beeching can cull those too, as long as you have the permission of course.

Beeching is a cross-platform .NET 6.0 / 7.0 application that can be run on Windows, Linux and Mac. It can be installed via any terminal, or in the Cloud Shell, and can also be run in your CI/CD pipeline.

You can install the tool globally, using the dotnet tool command:

dotnet tool install --global beeching

When a new version is available you will be prompted when calling Beeching, and you can use the dotnet tool update command to easily upgrade your installation:

dotnet tool update --global beeching

To call to beeching and swing the axe, you need to run the command from a user account with permissions to delete the specified resources, and resource locks if using the --force option. Authentication is performed via Azure CLI. Make sure to run az login (optionally with the --tenant parameter) to make sure you have an active session and have the correct subscription selected by using the az account set command. Alternatively you can specify a different subscription when calling the tool.

You can invoke the axe using the beeching command and by specifying your parameters. The most basic usage is to specify the name of the resources you want to axe. This will use your active Azure CLI subscription and will delete all resources that match the name or part of the name. You can use the axe command, but this is optional as it is the default command so can be omitted.

beeching axe --name my-resource

This is the same as:

beeching --name my-resource

Multiple name values can be supplied in a single string by separating them with the : symbol as in this example.

beeching --name my-resource-001:my-resource-002

Resources can also be selected by tags. This will delete all resources that have a tag with the specified key and value. Tags must be supplied as a single string in the format key:value.

beeching --tag key:value

Excluding and restricting

Once you have selected the resources you want to axe, you can optionally specify a list of resources to exclude from the axe using the --exclude option. This allows you to protect resources you wish to keep.

beeching --name my-resource --exclude my-resource-to-keep

Multiple name values can again be supplied in a single string by separating them with the : symbol.

beeching --name my-resource --exclude keep001:keep002

The list of resources can be further restricted to only cull certain types of resource using the --resource-types option. This example will only axe resources of the type Microsoft.Storage/storageAccounts.

beeching --name my-resource --resource-types Microsoft.Storage/storageAccounts

Again multiple options can be specified by single string separating them with a : symbol, as shown in this example which will axe only storage accounts and virtual networks.

beeching --name my-resource --resource-types Microsoft.Storage/storageAccounts:Microsoft.Network/virtualNetworks

Resource Groups

By default the axe will only cull individual resource types. If you want to axe an entire resource group and all the resources within it, you can use the --resource-group option. This will axe the resource group and all resources in it. This option can be used with the --name or --tag options to axe resource group that match the name, or partial name, or tag key and value.

beeching --name my-resource-group --resource-group

All of these options can be combined to create a very specific axe that will only delete the resources you want to delete.

Resource Locks

Resource locks can be applied to Azure resources at the resource, resource group or subscription level. If a resource is locked, it cannot be axed. Beeching will check for resource locks and will not attempt to axe any resources that are locked. If you want to axe a resource that is locked, you will need to remove all applicable locks first, or use the --force option to override the locks.

beeching --name my-resource --force

Using the --force option will attempt to remove any resource locks before axing the resource. This can be useful if you have a resource that is locked, but you know that it is safe to delete. This option should be used with caution as it can lead to accidental deletion of resources.

Following the axing of a locked resource, any relevant locks, such as subscription locks or resource group locks will be reapplied. This is to prevent accidental deletion of resources that are locked for a reason.

What If?

It is also possible to use the --what-if parameter to see which resources would face the axe. This will show you the list of resources that would be deleted, but will not actually delete anything.

beeching --name my-resource --what-if

Confirmation

Before any resources are actually deleted, you will be prompted to confirm that you really want to delete the resources. For automated deletion such as in a CI/CD pipeline you can skip this prompt by using the --yes parameter.

beeching --name my-resource --yes

Retries

A built-in retry mechanism is in place to handle transient network errors. By default, the axe will retry each request 3 times at the API level.

Occasionally deletion requests can fail if other dependent resources have yet to be deleted. In this instance a further retry mechanism is in place which will pause for 10 seconds between each retry attempt, and each action will be retried 6 times. These two values are configurable and can be set using the --max-retry and --retry-pause parameters.

beeching --name my-resource --max-retry 10 --retry-pause 30

Beeching can be found on NuGet and GitHub

Manage Azure App Registrations in VS Code

Ira Rainey — Tue, 10 Jan 2023 09:59:52 +0000

If you work with Microsoft Azure and use Application Registrations to create OAuth2 scopes for your APIs, or maybe create client applications that consume scopes from other applications, then you will no doubt be managing this all in the Azure Portal. That's great, and most of the functionality is there.

If you work with large numbers of applications, or if you automate parts of your works then you might perform these tasks with PowerShell or even by calling the Microsoft Graph API directly to manage these Azure Active Directory objects.

But if you're working in Visual Studio Code building your application, wouldn't it be great to be have all of your Application Registration information and management to hand directly in Visual Studio Code? Well now you can.

As a side project I have built a new extension for Visual Studio Code to allow for the management of Application Registrations from within the IDE.

It allows for easy viewing, copying, adding, and editing of most the core application properties, such as:

Client Id
Application ID URI
Sign In Audience
Certificates and Secrets
Redirect URIs
API Permissions
Exposed API Permissions
App Roles
Owners

It also allows for the simple creation of new applications, quickly viewing of the full application manifest in the editor, and has the ability to open the application registration directly in the Azure Portal when you need full editing control.

All application properties have their own range of functionality. From the top-level application itself, down to each individual property, functionality can be accessed via a range of context menus.

If required functionality is not currently implemented for a particular property then you can open the application registration in the Azure portal from the context menu of the application itself.

You can install the extension directly from with Visual Studio Code, or you can find out more information about it by visiting the Visual Studio Code Marketplace.

Using Playwright to test Azure Active Directory secured APIs

Ira Rainey — Mon, 28 Nov 2022 11:57:01 +0000

So you've built yourself a great API, and because you're smart you've secured it using JSON Web Tokens that you need to get from Azure Active Directory. Nice. As it's a user-focussed API you've implemented an authorisation model based on the user scopes defined in the access token. Smart.

However, now you want to perform end-to-end testing of your API endpoints, but you've suddenly realised that you need a user to authenticate themselves with Azure Active Directory to generate the access token you need.

If you were using the Client Credentials OAuth2 grant type you wouldn't have this problem, but that would only allow you to use application permissions and not user delegated scopes as you need. So using the Authorization Code OAuth2 grant type you're now presented with the challenge of automating that authentication process.

One way of doing this would be to use the Resource Owner Password Credentials (ROPC) OAuth2 grant type, which allows you to simply pass the username and password with the token request and be given back an access token. But this grant type is considered insecure and should be avoided if possible. It is also proposed to be omitted from the OAuth2.1 standard.

A better way to achieve this would be to use the open source browser automation framework Playwright, which offers the ability to test applications in Chromium, Firefox and WebKit with a single API, using .NET, Python, Java, or Node.js.

While Playwright is a fully-fledged automation framework for testing browser-based applications, in our scenario we're only interested in automating the Azure Active Directory authentication process. This will enable us to obtain an access token with user-scoped claims to allow us to test our API authorisation model.

This example uses a .NET 6.0 console application (a Node version can be found in the comments) with Playwright and the Microsoft Authentication Library (MSAL). The token acquisition process uses the Authorization Code grant type which following successful authentication of a user will return an authorization code to the specified redirect URI. This is the part that will be automated using Playwright. The returned authorization code is then exchanged for an access token using MSAL.

A client Application Registration is required to be registered in your Azure Active Directory tenant, with all required user permissions consented, and a redirect URI configured to receive the authorization code. This example uses https://oidcdebugger.com/ which is then accessed by Playwright to retrieve the code. This could however just as easily be your own service.

Your tenant id, client id, and scope are required for the sample to function. In the snippet below they are shown as placeholders. In the GitHub repository these values are set from either an appsettings.json or usersecrets.json file. This is only designed as an example. If you are running this anywhere other than locally it's recommended to store these values in Azure Key Vault secrets and access them using Managed Identity.

// Get client app related related settings
string tenant_id = "< AAD TENANT ID >";
string client_id = "< AAD CLIENT ID >";
string scope = "< API SCOPE >";

// The redirect uri being used here could be any service that you can use to access the auth code
// after it has been redirected from Azure Active Directory.
// This is using https://oidcdebugger.com which of course determines how you extract the auth code
// from page at the step lower down to use to exchange for an access token
string redirect_uri = "https://oidcdebugger.com/debug";

// Define authority and login uri
string authority = $"https://login.microsoftonline.com/{tenant_id}";
string login_uri = $"{authority}/oauth2/v2.0/authorize?client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&response_type=code&prompt=login";

// Create a Playwright instance
Console.WriteLine("Creating Playwright instance");
using var playwright = await Playwright.CreateAsync();

// Launch an instance of Chrome
Console.WriteLine("Launching Chrome");
await using var browser = await playwright.Chromium.LaunchAsync(new BrowserTypeLaunchOptions()
{
    Headless = true
});

// Create a browser page
var page = await browser.NewPageAsync();

// Navigate to the login screen
Console.WriteLine($"Navigating to {login_uri}");
await page.GotoAsync(login_uri);

// Enter username
Console.WriteLine("Entering username");
await page.FillAsync("input[name='loginfmt']", "< USERNAME >");
await page.ClickAsync("input[type=submit]");

// Wait until page has changed and is loaded
await page.WaitForLoadStateAsync(LoadState.NetworkIdle);

// Enter password
Console.WriteLine("Entering password");
await page.FillAsync("input[name='passwd']", "< PASSWORD >");
await page.ClickAsync("input[type=submit]");

// Wait until page has changed and is loaded
await page.WaitForLoadStateAsync(LoadState.NetworkIdle);

// Extract the auth code from the page we've redirected it to
Console.WriteLine("Extract auth code");
var authCode = await page.InnerTextAsync("#debug-view-component > div.debug__callback-header > div:nth-child(4) > p");

// Close the browser
await browser.CloseAsync();

// Build an MSAL confidential client
var app = ConfidentialClientApplicationBuilder.Create(client_id)
    .WithAuthority(authority)
    .WithRedirectUri(redirect_uri)
    .WithClientSecret("< CLIENT SECRET >")
    .Build();

// Get access token with code exchange
Console.WriteLine("Request access token with MSAL");
AuthenticationResult result = await app.AcquireTokenByAuthorizationCode(new string[] { scope }, authCode)
    .ExecuteAsync();

// Display the access token from the response
Console.WriteLine("Access token retrieved:\n");
Console.WriteLine(result.AccessToken);

Once you have exchanged your authorization code for an access token, you are free to use that token to call your API endpoints passing the token in the Authorization header as usual.

It is worth noting that this example will not work if multi-factor authentication is enabled for the user to be authenticated. It is recommended to create test users in your tenant that are excluded from MFA using a Conditional Access Policy.

If that is not possible, then you could configure MFA to use an SMS number and use a service such as Twilio to trigger a webhook from incoming SMS messages, which could then be included into the automated token acquisition process. This is not included in the scope of this article.

Full Code: https://github.com/irarainey/PlaywrightTokenAcquisition