Most organizations do not wake up one morning and decide to run an agent fleet. It happens in increments. A Copilot appears to summarize meetings. A bot gets introduced to triage requests. A workflow assistant starts opening cases after hours. An autonomous agent begins moving across APIs, files, and approvals with just enough independence to be useful. Then another team builds one. A vendor brings one. A low-code platform makes one easy to publish. Soon enough, you've inadvertently deployed the software equivalent of Talkie Toaster, relentlessly asking your APIs if they'd like any toast, or perhaps a toasted teacake, while consuming valuable resources. What looked like a handful of helpful automation becomes a population of nonhuman actors that sign in, request tokens, call resources, and accumulate access. Before you know it, your tenant is drifting like the Jupiter Mining Corporation ship Red Dwarf, overrun by unmanaged Skutters while the AI effectively operates with the IQ of a PE teacher.

That is exactly why Microsoft Entra Agent ID matters. In preview, and currently available through Microsoft Agent 365 in the Frontier program, it gives organizations a formal identity model for AI agents instead of forcing them into a patchwork of human accounts and long-lived application identities. Microsoft is not just adding a new object type. It is building a governance model around agent identity blueprints, blueprint principals, agent identities, and agent users, then layering sponsorship, access packages, Conditional Access, ID Protection, and monitoring on top.

The practical question, then, is not whether agent identity matters, (spoiler alert: they do) it's how to adopt them successfully without creating new sprawl, new blind spots, and a new category of orphaned access. The best way to think about Microsoft Entra Agent ID is as a path to success. Not a single feature, but a sequence.

The Tikka to Ride: Agent 365 and the Frontier Program

Before we start building our mechanoid empire, let's talk prerequisites. You can't just flip a switch and get Agent ID today—it requires authorization higher than a Space Corps Directive. To get started, your tenant must be part of the Frontier preview program and you have to agree to the Agent 365 terms of service. You also need at least one license of Microsoft 365 Copilot in the tenant to enable Agent 365.

To turn the key, an admin needs to head over to the Microsoft 365 admin center, navigate to Copilot > Settings, find Copilot Frontier under User access, and grant access to the specific users or groups looking to pilot the future.

The Path to Success

Laying the Foundation: The Agent Blueprint Model

The first successful move is to resist the temptation to create agents one by one with ad hoc settings. If you build them like snowflakes, they'll melt into a management puddle—or worse, you'll end up with a Series 4000 mechanoid obsessed with ironing everything in your tenant. Microsoft’s model starts with the agent identity blueprint for a reason. Every agent identity in a tenant is created from a blueprint, and that blueprint defines the shared characteristics of the agent type. Microsoft documents properties such as description, app roles, verified publisher, and authentication-related settings like optional claims as part of that common definition. The blueprint also carries the credentials used to request tokens for the agent identities it creates, which means the authentication model is set at the class-of-agent level rather than reinvented for every instance.

That is where categories, metadata, and auth method become operational decisions instead of afterthoughts. If an organization wants a category for customer support agents, another for finance automation, and another for internal copilots, the blueprint is the right boundary. If you want those categories to carry meaningful metadata about purpose, publisher, capabilities, and expected use, the blueprint is where you set that baseline. If you want the authentication method to align with environment and risk, this is where Microsoft’s guidance becomes especially important. For Azure-hosted agents, managed identity is the strongest production pattern. For other software-hosted agents, federated identity credentials are the modern choice. Certificates and client secrets exist, but Microsoft is clear that they are less aligned with current security best practice.

This matters because standardized provisioning is one of the main governance wins in Agent ID. A blueprint is not just a template. It is also a control surface. Microsoft explicitly notes that policies applied to a blueprint can affect every agent identity created from it, and that disabling a blueprint prevents its child agent identities from authenticating. That makes the blueprint model the right place to define consistent categories, metadata, and authentication posture before the fleet grows beyond what any team can reason about manually.

Putting Humans in Charge: Sponsorship and Accountability

Once the blueprint model exists, the next step is to make sure every agent is tied to accountable humans (preferably someone more responsible than Dave Lister). This is where many automation stories fail. The technology works, the business value shows up, and six months later nobody can answer who owns the thing or who should approve more access for it. Microsoft Entra Agent ID tries to close that gap by treating sponsors and owners as core governance constructs rather than optional documentation.

Microsoft’s governance guidance is direct on this point. Sponsors are the human users accountable for lifecycle and access decisions. Owners are the technical administrators responsible for operational management. In practice, that gives enterprises a clean division between business accountability and technical custody. More importantly, Microsoft has built lifecycle features around it. Sponsors can request access on behalf of an agent identity. Sponsors receive notifications as time-bound access assignments approach expiration. If sponsorship changes are required, Lifecycle Workflows can notify managers and cosponsors so accountability does not quietly disappear when people move roles or leave the organization.

This is where lifecycle approvals, renewals, and access escalations stop being improvised in email threads. If an agent needs broader access, the sponsor can act as the human checkpoint. If access is nearing expiry, the sponsor can renew it within policy or allow it to lapse. If an escalation is needed, the request can route through configured approval stages instead of becoming a permanent privilege grant that nobody revisits. For agent fleets, that human-in-the-loop model is not bureaucratic overhead. It is the thing that keeps nonhuman identities from becoming unmanaged business risk.

Bundling the Keys: Access Packages for Agents

After accountability is in place, access itself needs structure. This is where entitlement management becomes the turning point. Microsoft Entra now supports access packages for agent identities, and this is arguably one of the most important capabilities in the entire story because it turns access from scattered assignments into a governed product.

Microsoft documents that access packages for agent identities can include security group memberships, Microsoft Entra roles, and OAuth API permissions, including application permissions to target APIs. That means organizations can build a reusable access pattern for an entire class of agents rather than granting rights one object at a time. A support-agent package might include membership in a bounded security group and a specific API permission. A finance automation package might include a time-bound directory role and group-based access to tightly controlled systems. An agent can request a package programmatically, a sponsor can request it on the agent’s behalf, or an administrator can assign it directly.

What makes this powerful is not just the packaging. It is the policy around the package. Microsoft’s access package model lets the admin define who can request access, how many approval stages apply, who the approvers are, how long the assignment lasts, and whether extension is allowed. That is the entitlement-based governance pattern enterprises have needed for agent fleets. The access is intentional, auditable, and time-bound. It is also worth being precise about the limits. Microsoft notes that agent identities and service principals cannot be added through these access packages to application roles, SAP roles, or SharePoint Online site roles, so those should not be described as supported package targets. The supported story today is group memberships, allowed Entra roles, and API permissions.

There is an even more important constraint sitting underneath that packaging model: not every role or permission can be granted to an agent in the first place. Microsoft maintains a specific list of Microsoft Entra roles allowed for agents and separately blocks a set of high-risk Microsoft Graph permissions for agent identities and blueprints, including examples such as Application.ReadWrite.All, RoleManagement.ReadWrite.All, User.ReadWrite.All, and Directory.AccessAsUser.All. The reason is straightforward and worth stating plainly. High-privilege directory roles and tenant-wide control permissions assume a human administrator exercising deliberate judgment. An autonomous or semi-autonomous agent with those privileges could delete users, alter security settings, or escalate access at machine speed. Microsoft’s design is intentionally restrictive so that agent authorization defaults to least privilege instead of turning every helpful assistant into a tiny, tireless super-admin.

Giving Agents a Desk, Not Just a Badge: Agent Users and Work IQ

Not every extension story stops with an agent identity acting like an application. Sometimes an agent needs to participate as a digital worker with user-shaped capabilities. That is where the agent user pattern becomes important. Microsoft’s agent user model gives an agent a dedicated nonhuman user account that is linked one-to-one with its parent agent identity. That user account is optional, not automatic, and should be created only when the agent truly needs to act in contexts where a user identity is required.

This distinction matters because an agent user is not just "an app with a mailbox." Microsoft documents it as a constrained user identity that receives user-type tokens, can be added to groups, can be licensed for Microsoft 365 resources, and can participate in collaboration scenarios, while still being prevented from behaving like a normal interactive human account. It cannot have passwords or passkeys, it cannot break away from its parent identity, and it cannot take on privileged admin roles. In other words, you get user-context capability without abandoning the nonhuman security model.

That opens up a useful design pattern for extending agents with Work IQ. Work IQ MCP servers give agents access to grounded Microsoft 365 context and deterministic tools across mail, calendar, Teams, SharePoint, OneDrive, Word, and user profile data. For many scenarios, delegated or On-Behalf-Of access is enough. But the agent user pattern becomes compelling when the agent must persist as a long-lived teammate rather than merely borrowing a person’s context for a moment.

Think about a few practical scenarios. A service desk agent acting as a round-the-clock digital employee might need its own mailbox, Teams presence, and membership in a support operations group so it can triage inbound issues, summarize the case history with Work IQ Mail, inspect meeting context with Work IQ Calendar, and post updates into the right Teams channel. A project coordinator agent might need to appear as a stable participant in recurring planning meetings, access collaboration spaces that are only exposed to user identities, and use Work IQ User, Calendar, and Teams to keep schedules, participant context, and follow-up actions aligned. A research or account-planning agent might use Work IQ Copilot, SharePoint, and OneDrive to gather organizational context, files, and prior conversations while retaining a persistent user-shaped identity that other systems can recognize as part of the working team.

The key point is that Agent ID governance and Agent 365 extensibility are not competing stories. They reinforce each other. Agent identities give you the control plane for lifecycle, access, and policy. Agent users give you a constrained pattern for user-centric collaboration scenarios. Work IQ gives those governed identities useful, grounded context and tools. Put together, they allow an agent to be more than a background daemon without letting it wander the tenant like a caffeinated intern with global admin. 🤪

Setting the Bouncers: Conditional Access for Agents

With provisioning and entitlement in place, the next step is to make the access decision itself more intelligent. Microsoft Entra Conditional Access for Agent ID brings that control to token acquisition by agent identities and agent users. This is where the phrase “adaptive risk evaluation before token issuance” becomes more than marketing language. It's essentially putting a bouncer at the door of your data, ensuring that merely shouting "Smoke me a kipper, I'll be back for breakfast!" isn't enough to secure an access token.

Microsoft’s documentation is explicit that Conditional Access applies when an agent identity or agent user requests a token for a resource. It does not apply when the blueprint acquires a token for Microsoft Graph to create agent identities or agent users, and it does not apply to the intermediate token exchange step itself. That nuance matters because it keeps the blog accurate and helps architects understand where enforcement actually sits. The control point is the moment an instantiated agent identity or agent user is trying to obtain access to a protected resource.

From there, Microsoft gives admins several ways to shape policy. Policies can target all agent identities, specific agents by object ID, agents grouped by blueprint, or agents selected through custom security attributes. Policies can also target all resources, all agent resources, or specific resources. Conditions include agent risk, and access controls can block. Microsoft even documents a concrete pattern for approval-aware policy design: assign custom security attributes such as an approval status to agents or blueprints, assign corresponding attributes to resources, and then use Conditional Access to block all agents except those reviewed and approved for that kind of resource.

That is an important shift. Conditional Access is no longer just a broad perimeter control for users and apps. In the Agent ID model, it becomes a way to express that a newly created or unreviewed agent should not be able to get a token to sensitive resources until it has passed the organization’s governance checkpoints. That is the practical meaning of agent-context-aware policy.

Preventing the Zombie Apocalypse: Lifecycle Automation

Once agents can be created and granted access safely, the next challenge is to make sure they do not keep that access forever. Lifecycle governance is where most identity programs prove whether they are durable, and the same is true for agent identity. A forgotten, over-permissioned agent is the IT equivalent of a dormant volcano—if left unchecked, eventually someone is going to have to say, "Everybody's dead, Dave."

Microsoft’s guidance already provides several lifecycle levers. Access package assignments can expire automatically. Sponsors can renew them or let them lapse. Agent owners and sponsors can disable agent identities through the My Account experience. Blueprint principals can be viewed and managed in the Entra admin center, where their linked identities, permissions, owners, sponsors, audit logs, and sign-in logs are visible. Microsoft also documents that blueprint principals can be disabled, and that disabling the blueprint prevents child agent identities from authenticating. On the extreme end, a blueprint principal can be removed from a tenant, and the blueprint documentation also notes that associated identities and users should be removed before deleting the blueprint itself.

This is also the right place to bring in access reviews, but carefully. Microsoft’s agent-specific governance guidance is strongest around access packages, sponsor approvals, expiration's, and administrative actions. Microsoft’s broader access review documentation, however, makes it clear that access reviews can be used to re-certify access to groups, enterprise applications, role assignments, and access package assignments. So the most accurate way to frame lifecycle reviews for agents is this: review the groups, applications, roles, and access package assignments that agent identities depend on, and use the results to remove unneeded access automatically where the integration supports it. That keeps the lifecycle story factual while still supporting the “review, remove access, revoke, deactivate” progression.

In practical terms, a mature lifecycle motion looks like this: review the package assignments and dependent resource access on a schedule, let expired assignments revoke access automatically, disable the agent identity if the agent should stop operating, remove unnecessary assignments and memberships, and disable the blueprint principal when the whole class of agent should no longer authenticate. That is how you keep the directory from becoming a graveyard of forgotten automation.

Keeping an Eye on the Machines: Monitoring and Guardrails

The final step is to accept that governance is not complete just because an agent was onboarded correctly. Agents must remain observable, and guardrails must hold when behavior changes. When things go sideways, you need a warning system significantly more helpful than Holly simply announcing, "Emergency. There's an emergency going on." This is where Microsoft Entra ID Protection, sign-in telemetry, audit logs, and network-level controls come together.

Microsoft Entra ID Protection for agents is designed to spot behaviors that fall outside the normal baseline for an agent. The current documented detection's include unfamiliar resource access, sign-in spikes, failed access attempts, delegated sign-in on behalf of a risky user, and threat-intelligence-backed suspicious activity. Admins can investigate risky agents, confirm compromise, dismiss false positives, or disable the agent entirely. That last point is important for the requested guardrail around compromised credentials. The most accurate way to say it is not that Entra blocks “compromised credentials” directly, but that it can flag risky or confirmed-compromised agents and feed that signal into Conditional Access policies that block high-risk agents before they obtain tokens for resources.

Microsoft also provides observability through sign-in logs and audit logs. For Conditional Access troubleshooting, admins can filter sign-in events by agent type. For blueprint principals, the Entra admin center exposes linked identities, status, permissions, audit logs, and sign-in logs. Inside Microsoft Agent 365, the registry and reporting model broadens that visibility further by giving IT and security teams a unified view of agents across supported platforms.

Then there are the network guardrails. Microsoft’s current Global Secure Access documentation is most explicit for Copilot Studio agent traffic, where tenant-level baseline profiles can enforce web content filtering, threat-intelligence filtering, and file filtering once traffic is forwarded through the service. Even where those network controls are product-scoped today, the design intent is clear: agent governance is not just identity issuance and access approval, it is also safe resource boundaries. The enterprise goal is to ensure an agent cannot freely roam to any API, any connector, or any destination simply because it can technically make a call. Safe boundaries come from a combination of least privilege, resource targeting, risk-based policy, and network restriction.

Conclusion

That is why the path to success matters. Microsoft Entra Agent ID is not valuable simply because it introduces new object types. Its value comes from the sequence it enables. First, define the blueprint model so agents are categorized and provisioned consistently. Then tie each agent to accountable humans. Govern access through packages instead of ad hoc grants. Make token issuance conditional on risk and approval state. Run lifecycle processes that can renew, expire, disable, and remove what is no longer needed. Finally, monitor what agents do and enforce guardrails when behavior moves out of bounds.

For organizations trying to govern AI copilots, automation bots, and autonomous agents seriously, that sequence is much closer to an operating model than a feature checklist. It reduces attack surface. It creates a consistent baseline. It improves visibility and compliance. Most importantly, it keeps the agent conversation anchored in identity engineering rather than novelty. In the Frontier-era Microsoft Agent 365 story, Microsoft Entra Agent ID is starting to look like the control plane enterprises will need if they want agent adoption to scale without losing control of who, or what, is acting inside the tenant. 🚀

References

Microsoft Entra Agent ID documentation.

What is Microsoft Entra Agent ID?.

What is Microsoft agent identity platform.

Agent identity blueprints in Microsoft Entra Agent ID.

Create an agent identity blueprint.

What are agent identities.

Agent identities in Microsoft Entra Agent ID.

Agent users in Microsoft Entra Agent ID.

View and manage agent identity blueprints in your tenant.

Conditional Access for Agent ID (Preview).

Governing Agent Identities (Preview).

Authorization in Microsoft Entra Agent ID.

Access packages for Agent identities.

The agent's user account in Microsoft Entra Agent ID.

What are access reviews?.

Prepare for an access review of users' access to an application.

Agent identity sponsor tasks in Lifecycle Workflows (Preview).

ID Protection for agents (Preview).

Overview of Microsoft Agent 365.

Work IQ MCP overview (preview).

Protect agent identities with Microsoft Entra.

The standard capability to convert SOA for a group is well-documented, but combining it with Cloud Sync customized attribute mapping to seamlessly overwrite the existing AD group requires bringing together several different configuration concepts.

This post assumes that fundamental hybrid infrastructure is already established. AD DS, Microsoft Entra ID, identity synchronization, and Cloud Sync are deployed and functioning. The target group must already exist in AD and synchronize to Microsoft Entra.

Scenarios / use cases

Below are practical reasons why organizations utilize this conversion pattern:

- Legacy application authorization: On-premises applications that depend on LDAP queries or Kerberos tokens need security groups to stay in AD DS.

- Modernizing access governance: By changing the group's source of authority to Entra, administrators can utilize Entra ID Governance like access packages, access reviews and self-service management, which are difficult or impossible to perform efficiently in AD DS.

- Shifting the management plane: Rebuilding permission models across legacy applications is often not feasible. By transitioning group SOA to the cloud and mirroring the result backward, Entra becomes the control plane, while AD functions merely as a projection layer.

It is important to note that this is not a dual-write sync. Once a group's source of authority is moved to the cloud, any direct modifications to the on-premises AD group are treated as temporary and overwritten during the next provisioning cycle.

Prerequisites

Before converting the source of authority, ensure the following requirements are met:

- Supported sync client versions: Ensure Entra Connect Sync is running version 2.5.76.0 or later, and Cloud Sync is running version 1.1.1370.0 or later. For group writeback to AD DS, the Cloud Sync provisioning agent must be at version 1.1.3730.0 or later.

- Active Directory schema validation: The AD schema requires the msDS-ExternalDirectoryObjectId attribute, which is included by default in Windows Server 2016 and newer.

- Microsoft Graph permissions: Changing the group's source of authority requires the Group-OnPremisesSyncBehavior.ReadWrite.All permission. For delegated workflows, the least-privileged administrative role required is Hybrid Identity Administrator.

- Universal group scope: The existing AD group should be set to Universal scope before the conversion.

Preserving the existing AD identity

Since the goal is to map the cloud-managed group back to its original AD location, preservation steps must happen prior to the conversion. The existing distinguished name (DN) of the AD group must be mapped into Entra.

The most common enterprise pattern is that inbound synchronization still runs through Microsoft Entra Connect Sync, while Cloud Sync is introduced later for the Entra-to-AD writeback leg. In that model, the DN should be preserved in a tenant-scoped directory extension that Entra Connect Sync owns through its Tenant Schema Extension App. If the inbound leg is already running on Cloud Sync, the equivalent extension can instead be created on CloudSyncCustomExtensionsApp. Cloud Sync group writeback can consume extension attributes from either supported application, but Entra Connect Sync should not be described as exporting directly into a CloudSync-managed extension.

The following Microsoft Graph PowerShell example demonstrates creating the extension on CloudSyncCustomExtensionsApp, which is the pattern Microsoft documents for Cloud Sync-native extension mapping:

$tenantId = (Get-MgOrganization).Id
\(app = Get-MgApplication -Filter "identifierUris/any(uri:uri eq 'API://\)tenantId/CloudSyncCustomExtensionsApp')"
if (-not $app) {
    \(app = New-MgApplication -DisplayName "CloudSyncCustomExtensionsApp" -IdentifierUris "API://\)tenantId/CloudSyncCustomExtensionsApp"
}

\(sp = Get-MgServicePrincipal -Filter "AppId eq '\)($app.AppId)'"
if (-not $sp) {
    \(sp = New-MgServicePrincipal -AppId \)app.AppId
}

New-MgApplicationExtensionProperty -ApplicationId $app.Id -Name "GroupDN" -DataType "String" -TargetObjects Group

After creating or identifying the extension, the next step is to populate it. The objective is the same regardless of sync client: take the current AD distinguished name and copy it into an Entra extension attribute on the synchronized group before the SOA change.

Common enterprise approach: Entra Connect Sync inbound

If your tenant still uses Entra Connect Sync for the AD-to-Entra path, the cleanest supported pattern avoids custom synchronization rules entirely. Because converting a group's Source of Authority is typically a one-off transition for each group rather than a continuously synchronized state, you do not need a permanent script or custom rule bridging distinguishedName to an extension attribute.

A practical pattern is:

1. Pick an unused on-premises group attribute that can safely hold the original DN as a single string value (e.g., extensionAttribute15).

2. Populate that on-premises attribute with the group's current DN statically, just once, before the SOA change.

3. Use the Entra Connect wizard to enable that attribute for Group directory extensions. (Let the built-in sync rules flow the attribute natively).

4. Run the required import/sync steps so Entra Connect creates and populates the generated extension property in Entra.

5. Verify the value in Entra before changing isCloudManaged.

A short worked example from my lab looked like this:

- On-premises source attribute: extensionAttribute15 on the group object

- Value stored before conversion (one-off text deployment): CN=GroupSOADemo,OU=Groups,DC=contoso,DC=com

- Entra Connect wizard action: enable extensionAttribute15 for Group directory extensions

- Resulting Entra attribute after sync: extension_<TenantSchemaExtensionAppId>_extensionAttribute15

Custom rules in the Synchronization Rules Editor are functionally optional and only required if you decide to dynamically derive the DN value for ongoing synchronizations. By simply treating the extension attribute as a static, one-time payload populated before the cutover, the native directory extensions feature handles the rest without complex customized rule shapes.

After synchronization completes, verify that the generated Entra extension contains the full DN. That is the value later consumed by the Cloud Sync ParentDistinguishedName and CN expressions.

Running Get-MgGroup -GroupId <groupId> -Property * will show the on-prem extension properties in the AdditionalProperties collection, which is often easier to parse than the more complex $expand=extensions syntax. The key point is confirming that the extension contains the full DN before proceeding with the SOA switch.

Cloud Sync inbound alternative

If the inbound leg is already on Cloud Sync, the workflow is simpler:

- Add or confirm an inbound attribute mapping for the group object that sources the AD distinguished name.

- Target the tenant-scoped extension attribute created on CloudSyncCustomExtensionsApp, such as extension_<appIdWithoutHyphens>_GroupDN.

- Run a sync cycle and wait for the group object in Entra to update.

- Confirm the value on the target group before changing isCloudManaged.

Validation matters here because the writeback configuration later depends on this value being correct. A simple validation approach is to query the group through Microsoft Graph and confirm the extension property contains the full original DN, for example CN=GroupSOADemo,OU=Groups,DC=contoso,DC=com. If the value is missing, truncated, or reflects a stale OU path, Cloud Sync will not have enough information to match the original object reliably.

For example, after the inbound mapping runs, retrieve the group and inspect the extension property:

GET https://graph.microsoft.com/v1.0/groups/{groupId}?\(select=id,displayName&\)expand=extensions

Depending on the client you use, it can be easier to request the specific extension property directly through Microsoft Graph PowerShell or Graph Explorer and verify that the stored DN exactly matches the current on-premises group DN. In an Entra Connect Sync-based deployment, this extension name will usually be in the form extension_<TenantSchemaExtensionAppId>_<AttributeName>. In a Cloud Sync-based deployment, it will typically be extension_<CloudSyncCustomExtensionsAppId>_<AttributeName>. That one check establishes that Entra now has a durable copy of the AD location data needed for the later ParentDistinguishedName and CN mappings.

Converting Source of Authority

The source-of-authority switch is performed against the Microsoft Graph API.

First, retrieve the current synchronization state:

GET https://graph.microsoft.com/v1.0/groups/{groupId}/onPremisesSyncBehavior?$select=isCloudManaged

For standard synced AD groups, the isCloudManaged property will evaluate to false. Next, issue a PATCH request to flip management to the cloud:

Invoke-MgGraphRequest -Method PATCH `
    -Uri "https://graph.microsoft.com/v1.0/groups/$groupId/onPremisesSyncBehavior" `
    -Body @{ isCloudManaged = $true }

Subsequent GET requests will show isCloudManaged as true and onPremisesSyncEnabled as null. At this operational boundary, the group becomes fully editable within Microsoft Entra. However, the legacy application integration depends on completing the writeback setup.

You can also verify the change in the Entra portal. The group will lose its "Synchronized from on-premises Active Directory" status and the "Source" field will update to "Cloud". The critical part of this pattern is that the original AD group is not orphaned or duplicated, but rather becomes cloud-managed while retaining its original identity and location in AD. However, it will be flagged as excluded in Entra Connect Sync when the source of authority has changed.

Before:

After:

Configuring Cloud Sync Writeback

The final component uses the preserved DN established in the prerequisites for the Entra-to-AD provisioning job.

In the Cloud Sync attribute mapping for groups, expression-based mappings must be configured for the ParentDistinguishedName and CN target attributes. The mapping definitions strip the CN= portion to identify the parent OU path for the ParentDistinguishedName, while separately extracting the CN string to specify the target group name.

Microsoft's documented pattern uses an extension name such as extension_<AppIdWithoutHyphens>_GroupDistinguishedName. In an enterprise tenant using Entra Connect Sync to flow an existing on-premises attribute (like extensionAttribute15), the stored DN resides on the Tenant Schema Extension App with a generated name like extension_<TenantSchemaExtensionAppId>_extensionAttribute15. Substitute your exact generated extension attribute name in the expressions below. The key point is that both expressions must reference the same stored DN value.

Use the following expression for ParentDistinguishedName:

IIF(
  IsPresent([extension_<TenantSchemaExtensionAppId>_extensionAttribute15]),
  Replace(
    Mid(
      Mid(
        Replace([extension_<TenantSchemaExtensionAppId>_extensionAttribute15], "\,", , , "\2C", , ),
        InStr(Replace([extension_<TenantSchemaExtensionAppId>_extensionAttribute15], "\,", , , "\2C", , ), ",", , ),
        9999
      ),
      2,
      9999
    ),
    "\2C", , , ",", ,
  ),
  "<Existing ParentDistinguishedName>"
)

This expression does two things. If the extension is populated, it removes the leading CN= segment and returns only the parent DN path. If the extension is empty, it falls back to the default target OU that you specify in the mapping.

Use the following expression for CN:

IIF(
  IsPresent([extension_<TenantSchemaExtensionAppId>_extensionAttribute15]),
  Replace(
    Replace(
      Replace(
        Word(Replace([extension_<TenantSchemaExtensionAppId>_extensionAttribute15], "\,", , , "\2C", , ), 1, ","),
        "CN=", , , "", ,
      ),
      "cn=", , , "", ,
    ),
    "\2C", , , ",", ,
  ),
  Append(Append(Left(Trim([displayName]), 51), "_"), Mid([objectId], 25, 12))
)

This expression extracts the first DN component, removes the CN= prefix, and restores any escaped commas that were temporarily converted during parsing. If the extension is not present, the fallback generates a deterministic CN from the group display name and part of the object ID.

Worked example:

- Stored extension value: CN=GroupSOADemo,OU=Groups,DC=contoso,DC=com

- Resolved ParentDistinguishedName: OU=Groups,DC=contoso,DC=com

- Resolved CN: GroupSOADemo

This is the intended outcome of the two mappings together. The first expression removes the leading common name component and preserves the remaining OU and domain path. The second expression extracts only the common name so Cloud Sync can target the original group name in the original container.

This ensures Cloud Sync derives the proper container and naming convention to match the original AD object path, rather than generating an arbitrary object. When properly scoped and configured, the provisioning logs should indicate a match and update against the pre-existing target group, confirming the behavior framework.

The next step is to run the Cloud Sync provisioning job and monitor the logs for the expected match and update operations against the original AD group. If the expressions are correct and the extension contains the right DN, you should see a successful update rather than a creation of a new object in the default OU.

You can perform an additional validation step by adding or removing a member from the group in Entra and confirming the change is reflected in AD DS after provisioning runs. This confirms that the writeback is functioning end-to-end and that the original group is now being managed from the cloud.

Troubleshooting

If your provisioning log shows HybridSynchronizationActiveDirectoryInvalidGroupType, the expression mappings are usually not the problem. That error normally means the matched on-premises target group is not a supported writeback target. In practice, recheck that the original AD object is a standard non-mail-enabled Security group, that its scope is Universal before the SOA cutover, and that it is not still carrying Exchange-style mail-enabled group characteristics from an earlier lifecycle.

A quick validation checklist for the original AD group is:

- GroupCategory = Security

- GroupScope = Universal

- Not a Mail-Enabled Security Group or Distribution List

- No Exchange dependency that keeps the group mail-enabled when Cloud Sync tries to update it

Important caveats and limitations

- Mail-enabled groups and writeback: While Mail-Enabled Security Groups (MESGs) and Distribution Lists (DLs) can have their Source of Authority converted to the cloud (for management via Exchange Online), they are not supported for Cloud Sync group writeback to AD DS. If provisioning logs show HybridSynchronizationActiveDirectoryInvalidGroupType, this unsupported target-group state is one of the first things to verify. The writeback pattern detailed in this post applies only to standard Security Groups.

- Entra Connect Sync customization boundaries: If you preserve the DN by using Entra Connect Sync, use custom synchronization rules with higher precedence than the defaults and avoid directly editing Microsoft out-of-box rules. Microsoft also documents that directory extensions owned by Entra Connect should be managed through the Entra Connect-supported model, because cloning or manually re-pointing directory extension rules can create upgrade and synchronization issues.

- Nested groups: Group SOA does not apply recursively. For nested synced groups to transition to cloud management, administrators must convert them iteratively, typically beginning at the lowest level of the hierarchy.

- Cloud-only users: Group provisioning to AD DS handles only member references with valid on-premises identity anchors. For hybrid groups containing both cloud-only and synchronized user accounts, Cloud Sync writes back the synchronized identities and skips cloud-only references.

- Prohibited local modifications: Post-conversion, the on-premises copy is no longer the source of truth. Any direct changes made against AD DS will be overwritten silently when the background provisioning system next executes.

- Scale constraints: For the Cloud Sync group provisioning job, Selected security groups is the recommended scope. There are scale boundaries documented regarding maximum groups, total processing memberships, and maximum membership per individual group (capped at 50,000 users).

- Rollback operations: Source of authority can be reverted by running a PATCH request setting isCloudManaged to false. The rollback process completes only when the directory sync client evaluates and re-assumes ownership on the next iteration. It is critical to sever cloud reference dependencies, such as clearing cloud-only members or removing associated Access Packages, prior to initiating a rollback.

Architecture

The following diagram illustrates the complete logical workflow.

Conclusion

Converting a group's Source of Authority from Active Directory to Microsoft Entra, combined with Cloud Sync writeback mapping, provides a precise bridge between overlapping architectures. Administrators can transition group management, approvals, and dynamic requirements to Entra ID while safely preserving the exact group structure that existing LDAP or Kerberos applications rely on.

Once you have validated the core pipeline of storing the GroupDN and applying custom Cloud Sync expressions, there are several ways to scale or apply this model:

- Connect Group SOA to Access Packages: With management shifted to Entra ID, these groups are eligible for Microsoft Entra ID Governance. This means you can wrap the group in an Access Package, enabling self-service requests and automated access reviews for legacy apps without writing custom code or deploying complex on-premises identity managers.

- Implement AD DS Minimization: Evaluate whether certain applications have modernized entirely to SAML or OpenID Connect. If they no longer require the AD group for authorization, you can flip their group SOA to the cloud and simply skip the Cloud Sync writeback step. Over time, this steadily reduces reliance on AD DS.

- Address Exchange Dependencies: Distribution Lists (DL) and Mail-Enabled Security Groups (MESG) synced from on-premises Exchange can also have their SOA converted. While these cannot be directly managed by Microsoft Graph, converting them enables management through Exchange Online PowerShell. From there, you can upgrade non-nested DLs into modern Microsoft 365 Groups for richer collaboration.

- Convert Groups Systematically: For nested groups, begin converting from the lowest level of the hierarchy, as the SOA switch does not apply recursively.

References

1. [Guidance for using Group Source of Authority (SOA)](https://learn.microsoft.com/en-us/entra/identity/hybrid/concept-group-source-of-authority-guidance)

2. [Configure Group Source of Authority (SOA)](https://learn.microsoft.com/en-us/entra/identity/hybrid/how-to-group-source-of-authority-configure)

3. [Embrace cloud-first posture: Convert Group Source of Authority to the cloud](https://learn.microsoft.com/en-us/entra/identity/hybrid/concept-source-of-authority-overview)

4. [Tutorial - Provision groups to Active Directory Domain Services by using Microsoft Entra Cloud Sync](https://learn.microsoft.com/en-us/entra/identity/hybrid/cloud-sync/tutorial-group-provisioning)

5. [Group writeback with Microsoft Entra Cloud Sync](https://learn.microsoft.com/en-us/entra/identity/hybrid/group-writeback-cloud-sync)

6. [Cloud sync directory extensions and custom attribute mapping](https://learn.microsoft.com/en-us/entra/identity/hybrid/cloud-sync/custom-attribute-mapping)

7. [Attribute mapping - Active Directory to Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/hybrid/cloud-sync/how-to-attribute-mapping)

8. [Writing expressions for attribute mappings in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/hybrid/cloud-sync/reference-expressions)

9. [Expression builder with cloud sync](https://learn.microsoft.com/en-us/entra/identity/hybrid/cloud-sync/how-to-expression-builder)

10. [onPremisesSyncBehavior resource type](https://learn.microsoft.com/en-us/graph/api/resources/onpremisessyncbehavior)

11. [Get onPremisesSyncBehavior](https://learn.microsoft.com/en-us/graph/api/onpremisessyncbehavior-get)

12. [Update onPremisesSyncBehavior](https://learn.microsoft.com/en-us/graph/api/onpremisessyncbehavior-update)

13. [Microsoft Entra Connect Sync: Directory extensions](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-sync-feature-directory-extensions)

14. [Microsoft Entra Connect Sync: Make a change to the default configuration](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-sync-change-the-configuration)

15. [Microsoft Entra Connect Sync: Best practices for changing the default configuration](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-sync-best-practices-changing-default-configuration)

Microsoft Graph also supports delivering these change events through Azure Event Grid (via Event Grid Partner Events). Instead of posting directly to your webhook, Graph publishes events into an Event Grid partner topic in your Azure subscription. From there, you use a normal Event Grid event subscriptions to route events to whatever you want 🎉 . You still need to handle at-least-once delivery and subscription lifecycle events, but you get Azure-native routing, filtering, monitoring, and dead-lettering without putting an HTTP endpoint on the public internet.

This project utilizes Microsoft Graph to deliver events into Azure Event Grid Partner Events, and from there I route them into Azure Functions (PowerShell) with proper buffering, idempotency, dead-lettering, and subscription lifecycle handling.

In this post I detail an identity governance scenario (joiner/mover/leaver-style signals on users), but the pattern is useful anywhere you want “near real-time” identity change pipelines: birthright automation, security reactions, audit/enrichment streams into SIEM, or ops workflows that open tickets and notify owners.

A side benefit of this design is that it removes the temptation to “paper over” eventual consistency and transient failures with arbitrary Start-Sleep calls and retry loops sprinkled throughout your business logic. Instead of making the application guess when Graph has “settled” (or how long downstream systems need), you let the platform absorb the timing variability: Event Grid provides durable at-least-once delivery, the Function handler turns each event into a queued work item, and workers process asynchronously with explicit retry and dead-letter semantics. If a dependency is temporarily unavailable (Graph throttling, directory propagation delays, downstream API outages), you can retry in a controlled way (with backoff, visibility timeouts, and poison-message handling) without blocking an HTTP request, holding open connections, or burning compute on sleeps.

Because events can be duplicated and delivered out of order, the pipeline also makes idempotency a first-class concern: a stable dedupe key is recorded once, and replays become a no-op instead of “retry storms” that require defensive delays. The result is fewer brittle timing hacks in the app, clearer operational behavior (you can see retries and failures as messages), and a system that degrades predictably when the real world is slow—without turning every caller into a hand-rolled queue processor.

This pattern is particularly well-suited to hybrid identity environments where you're waiting for on-prem changes to sync up to Entra ID via Entra Connect/Cloud Sync. By leveraging Event Grid's reliable delivery and Azure Functions' asynchronous processing, you can effectively manage the inherent delays in synchronization without complicating your application logic.

Other possible scenarios include:

• User risk event processing

• Privileged role assignment changes

• Group membership changes

• Application credential changes

• And more (whatever Entra publishes through Event Grid partners!)

What about Entra ID Governance Lifecycle Workflows?

Compared to Entra ID Governance Lifecycle Workflows, this pattern trades “built-in product workflow” for “programmable event pipeline”: the big wins are flexibility (any Graph/API call or downstream integration), near real-time reactions (seconds/minutes instead of scheduled runs), richer idempotency/retry/dead-letter control, and easier extension beyond the lifecycle catalog (tickets, SIEM enrichment, custom audits); the downsides are you own more of the engineering surface area (deployments, monitoring, versioning, security reviews), you must correctly manage and periodically re-validate Graph permissions/consent, and you’re responsible for guardrails and supportability that Lifecycle Workflows provide out of the box (scoping, approvals/notifications, reporting, and “it’s supported by Microsoft” operational expectations).

The Demo Environment

The promise is simple: I run one deployment script and end up with a working pipeline where Graph events land in my Function App reliably, with dead-lettering and lifecycle handling.

First the infrastructure is deployed using Bicep templates in infra/. The core resources are:

• Azure Function App (PowerShell) with managed identity

• Storage Account with queues (work items + lifecycle) and table (dedupe keys)

• Event Grid Partner Configuration authorizing Microsoft Graph

• App Insights for logging and monitoring

Next, the deployment scripts in scripts/ wire everything up. They create and assign a user-assigned managed identity, assign Azure RBAC and Graph app roles, deploy the Bicep templates, zip-deploy the Function code, create the Graph subscription that delivers to Event Grid, activate the partner topic, and finally create the event subscription from the partner topic to the Function app using CloudEvents 1.0 as the delivery schema.

Inside the Function App I treat incoming events as “messages,” not “requests”: I dedupe them using Table Storage (Entra ID auth, no keys) and buffer them through Storage Queues so downstream workers can run independently. Lifecycle events are handled too: the subscription gets reauthorized and renewed so the demo doesn’t silently die.

Finally, the event subscription is configured with dead-lettering to blob storage using a user-assigned managed identity (so there are no storage keys sitting in configuration).

A guided tour of the architecture

Here’s the complete flow at a glance. I’ll walk it left-to-right in the next sections.

flowchart LR
  Graph[Microsoft Graph<br>change notifications] -->|Partner Events| PC[Event Grid<br>Partner Configuration]
  PC --> PT[Event Grid<br>Partner Topic]

  PT --> ES[Event Subscription<br>CloudEvents 1.0]
  ES -->|invoke| GEH[Azure Function<br>**GovernanceEventHandler**]

  GEH -->|dedupe key| Dedupe[Table Storage<br>**DedupeKeys**]
  GEH -->|enqueue| WorkQ[Storage Queue<br>**workitems**]
  GEH -->|enqueue lifecycle| LifeQ[Storage Queue<br>**lifecycle**]

  WorkQ --> BW[Azure Function<br>**BirthrightWorker**]
  LifeQ --> SLW[Azure Function<br>**SubscriptionLifecycleWorker**<br>reauthorize + renew]

  ES -->|dead-letter| DL[Blob Storage<br>**dead-letter** container]

  UAMI[User-assigned<br>managed identity] --> GEH
  UAMI --> BW
  UAMI --> SLW
  UAMI --> Dedupe
  UAMI --> WorkQ
  UAMI --> LifeQ
  UAMI --> DL

Repo map (where to look first)

I split the repo into three chunks: infrastructure (infra/), orchestration scripts (scripts/), and the Function App (src/FunctionApp/). That mirrors how I think about the system: “build the platform”, “wire it up”, then “process events”.

And the directory structure looks like:

project-eventgrid-partnerconfiguration
├── infra
│   ├── main.bicep
│   ├── link.bicep
│   └── parameters.dev.bicepparam
├── scripts
│   ├── Deploy-Infrastructure.ps1
│   ├── Deploy-FunctionCode.ps1
│   ├── New-GraphUsersSubscriptionToEventGrid.ps1
│   ├── Activate-EventGridPartnerTopic.ps1
│   ├── Grant-GraphAppRolesToManagedIdentity.ps1
│   └── Set-Policy.ps1
└── src
    └── FunctionApp
        ├── GovernanceEventHandler
        ├── BirthrightWorker
        ├── SubscriptionLifecycleWorker
        ├── Modules
        │   └── GovernanceAutomation
        │       ├── GovernanceAutomation.psm1
        │       └── GovernanceAutomation.psd1
        ├── policy
        │   └── policy.json
        ├── host.json
        ├── local.settings.example.json
        ├── profile.ps1
        └── requirements.psd1

What’s where (and what it does)

Infrastructure

I intentionally split IaC into two stages.

infra/main.bicep is “core infra only”: it creates the Function App, storage (queues + dedupe table), diagnostics, and the Event Grid partner configuration authorization. The Function runs under a user-assigned managed identity (UAMI).

infra/link.bicep is the second stage that I run after Graph has created the partner topic. It attaches the UAMI to the partner topic (while preserving the partner-provided properties.source), creates dead-letter storage + RBAC, and then creates the partner topic → Function event subscription using CloudEventSchemaV1_0.

infra/parameters.dev.bicepparam is just the “comfortable defaults” file for main.bicep.

Scripts

The scripts are the glue that makes this feel like “one command deploy” instead of “seven manual steps.”

scripts/Deploy-Infrastructure.ps1 is the main entry point: it creates/uses the UAMI, assigns Azure RBAC, assigns Graph application roles to the managed identity (defaults include User.ReadWrite.All, Directory.Read.All, and Group.ReadWrite.All), deploys main.bicep, deploys the function code, bootstraps Graph → Event Grid, activates the partner topic, and then deploys link.bicep. It also makes re-runs sane by picking a unique partner topic name when the deterministic name already exists.

If you want to focus on individual steps, scripts/Deploy-FunctionCode.ps1 does the zip deploy for src/FunctionApp, scripts/New-GraphUsersSubscriptionToEventGrid.ps1 creates the Graph subscription (and supports -UseAzCliGraphToken so you don’t need the Microsoft Graph PowerShell module), and scripts/Activate-EventGridPartnerTopic.ps1 flips the partner topic into the active state so events will flow.

Function code

I treat the Function App as a small event-processing system.

src/FunctionApp/GovernanceEventHandler/run.ps1 is the Event Grid trigger. It normalizes the incoming payload (Graph partner events arrive as CloudEvents 1.0), generates a stable dedupe key, records idempotency in Table Storage (managed identity auth), and then enqueues a work item. Lifecycle notifications get routed to a dedicated queue.

The heavy lifting lives in src/FunctionApp/Modules/GovernanceAutomation/GovernanceAutomation.psm1: schema normalization, stable dedupe keys, Table Storage idempotency, and the Graph lifecycle calls (reauthorize + renew).

From there, src/FunctionApp/SubscriptionLifecycleWorker/run.ps1 processes lifecycle messages and validates clientState (via GRAPH_CLIENT_STATE) before calling Graph, and src/FunctionApp/BirthrightWorker/run.ps1 processes work items and applies birthright group assignments for newly created users.

Important Graph nuance: for users subscriptions, user creation shows up as an updated notification (Graph does not emit a created changeType for user resources). To avoid accidentally touching every user update, the birthright worker gates “new user” using createdDateTime proximity to the event time.

The policy itself is in src/FunctionApp/policy/policy.json.

How policy.json drives decisions

I wanted the “governance logic” to be editable without touching code, so the Function reads a JSON policy file and uses it to decide whether it should only detect and log something, or whether it should eventually remediate.

At the top level, the policy has a mode (for example detect) and a version. In detect mode, the workers still process events and emit useful logs, but they’re intentionally conservative about making changes.

There are three main ideas inside the policy:

1. Birthright assignments

The birthrights block is how I model “when a user appears (or changes), what should they get by default?”

In the current policy file, birthrights.mode is set to remediate, and the default assignment matches userType: "Member" and adds the user to a specific Entra security group:

"birthrights": {
  "enabled": true,
  "mode": "remediate",
  "assignments": [
    {
      "name": "Default-Birthright",
      "when": { "userType": "Member" },
      "addToGroups": ["928bd0ce-8abc-43dd-94a0-d350fe49e991"]
    }
  ]
}

The BirthrightWorker reads this policy and, for newly created users only, calls Microsoft Graph to add the user as a member of each configured group.

2. Safety rails (break-glass + allow lists)

The breakGlass section is where I list accounts that should be treated as special (for example, never auto-remove, never auto-disable). The allowLists section is the opposite: known-good groups/apps/roles that the automation can ignore or treat as explicitly permitted.

3. Rules: match an event, then choose an action

The rules array is the “if this, then that” part. Each rule has criteria that matches against the normalized work item (for example eventTypeStartsWith, subjectContains, and a higher-level condition like UserDisabled). When a rule matches, the action describes what to do. In the sample policy there’s a “leaver” style rule that, when a user is disabled, would run steps like RevokeSessions and RemoveFromHighRiskGroups.

The important part is that this policy file is read in the context of the event pipeline: Graph emits change events, the handler normalizes/dedupes/queues them, and the worker uses policy.json to decide what it would do next.

Prerequisites

This is a PowerShell-first repo. I run it with PowerShell 7.4+ and Azure CLI (az) authenticated via az login. You also need enough Azure permissions to create resources in your target subscription/resource group.

On the Entra side, you need permission to create Microsoft Graph subscriptions (delegated), and admin consent permissions to assign Microsoft Graph application roles to the managed identity.

For birthright group assignment (adding users to groups), the managed identity needs (at minimum) a Graph application permission that can add group members:

• GroupMember.ReadWrite.All (least-privilege for add/remove members)

This repo’s deployment script uses Group.ReadWrite.All by default (broader, but simple) plus user/directory read permissions so the worker can query createdDateTime for the new-user gate.

The one-command deployment

This is the command I use when I want complete setup without thinking too hard about the order of operations:

pwsh ./scripts/Deploy-Infrastructure.ps1 `
  -SubscriptionId <sub> `
  -ResourceGroupName <rg> `
  -Location <location>

What it does (in order):

1. Creates (or reuses) a user-assigned managed identity (UAMI)

2. Assigns Azure RBAC on the resource group (so the deployment can create resources)

3. Assigns Graph app roles to that identity (defaults include User.ReadWrite.All, Directory.Read.All, and Group.ReadWrite.All)

4. Deploys infra/main.bicep

5. Zip deploys the Function code

6. Creates a Graph subscription that delivers to Event Grid (partner topic)

7. Activates the partner topic

8. Deploys infra/link.bicep to create the partner topic → function event subscription (with dead-lettering)

Notes for re-runs:

If the partner topic name already exists, the script automatically chooses a new unique one. If you want full control (for example, because you’re integrating into another environment), you can pass -PartnerTopicName <partnerTopic>.

Similarly, a new User-Assigned Managed Identity (UAMI) is created by default (each deployment). You can pass in -BootstrapUserAssignedIdentityName '<name>' to use an identity from a previous deployment (or one created outside this project).

How I sanity-check it (events + dedupe + lifecycle)

To verify everything is working, create a new user in your Entra tenant. In the GovernanceEventHandler invocation logs you should see a received event with CloudEvents fields like type, subject, and time. You should also see a corresponding event in the BirthrightWorker logs showing the work item being dequeued with the same correlationId and event details.

For a newly created user (within the configured window), you should see a log like:

If Graph sends multiple events, the dedupe processing logs look like:

For a normal user update or change event, you should see a log like:

And when Graph sends lifecycle notifications, you'll see logs for reauthorization and renewal (for example, Graph subscription reauthorized and Graph subscription renewed).

The bits worth stealing

The two-stage IaC split (main.bicep + link.bicep) is a useful pattern when working with Event Grid partner topics, because you often need to create the partner topic first (via Graph) before you can attach identities and event subscriptions.

I also like the security posture here. Dead-lettering uses deadLetterWithResourceIdentity, so there are no storage keys in app settings. For idempotency I store a hashed dedupe key in Table Storage using Entra auth and treat HTTP 409 as “already processed.” And because Graph partner events arrive as CloudEvents 1.0, I normalize them into a stable work-item shape before queuing.

Finally, the lifecycle worker is what makes this demo feel “production-ish”: it reauthorizes and renews subscriptions so the pipeline keeps working across longer-lived test runs.

Lessons learned (so you don’t hit the same walls)

I tripped over a few sharp edges building this.

Partner topics are partner-created; if you try to “just create them in Bicep” without the partner metadata, it fails. Even when you’re updating a partner topic, you have to preserve partner-provided fields like properties.source.

I also hit an ARM circular dependency when I tried to “read the existing partner topic source” and “update partner topic identity” in the same template. The pragmatic fix was to pass partnerTopicSource in from the script.

Re-runs matter a lot for demos: if you re-run Graph bootstrap with the same partner topic name and it already exists, Graph can fail. Picking a unique name on re-run makes the whole thing repeatable.

On the Event Grid side, target validation happens up-front, so the Function needs to exist before creating the event subscription. And in Functions, PowerShell queue triggers can hand payloads in different shapes (string/base64/object), so defensive parsing is worth the effort.

Finally, RBAC is non-negotiable for the data plane: use Storage Queue Data Contributor for queues, I tried least-privilege roles like Storage Queue Data Sender and Storage Queue Data Processor but they fell short. Use Storage Table Data Contributor for tables, and Storage Blob Data Contributor for the dead-letter container.

On the Graph side, group membership writes require group permissions (GroupMember.ReadWrite.All or broader). A common failure mode is granting only user permissions (like User.ReadWrite.All) and then getting a 403 when trying to add the user to a group.

Conclusion

Using Event Grid partner events to receive Microsoft Graph change notifications is a powerful pattern that avoids the need to host public webhooks. By combining Event Grid with Azure Functions, managed identities, and proper idempotency and lifecycle handling, you can build robust identity event pipelines that are secure and maintainable. This project provides a solid foundation to get started, and I encourage you to adapt and extend it for your own identity governance scenarios. 🚀

References

• My Repo: vsCode/project-eventgrid-partnerconfiguration at main · broberts23/vsCode

• Microsoft Graph API change events through Azure Event Grid overview

• Event Grid partner events documentation

• CloudEvents 1.0 schema reference for Event Grid

• Use managed identities to access Azure Storage from Azure Event Grid

• Microsoft Graph subscription lifecycle management

• Set dead-letter location and retry policy

• Renew a Microsoft Graph API subscription

In my previous infrastructure blog, we built a disposable Active Directory lab: a domain controller in its own subnet, a function app in another, Key Vault for secrets, and just enough networking glue to make it feel like a real hybrid environment.

This post is the other half of the story: the PowerShell 7.4 Azure Function that accepts authenticated requests, authorizes them with role claims, and resets passwords in on-prem AD over LDAPS.

The goal is intentionally boring: one HTTP POST, a strong password comes back, and the AD change happens safely and repeatably.

Where This Pattern Fits

This “thin API + strong platform auth + pinned LDAPS” pattern is useful anywhere you want a controlled bridge between cloud automation and a directory that still lives behind private networking.

Here are a few practical scenarios:

1. ITSM-driven onboarding (e.g., ServiceNow)

   • A user onboarding workflow runs in an ITSM tool and, at the right step, calls POST /api/ResetUserPassword using client credentials.

   • The ITSM app registration gets a tightly scoped role (for example, only the password reset role), and the function enforces that role claim.

   • The generated password can be handed off to the next step (securely) or used to set an initial password before the user is prompted to change it at first sign-in.

2. Scheduled service account password rotation

   • A rotation service (another API, a runbook, or a GitHub Actions workflow) calls the endpoint on a schedule for a known set of accounts.

   • Because the function pulls its bind credential and LDAPS pinning material from Key Vault, you can rotate the function’s own dependencies independently.

   • The caller can store the new password in the system that actually consumes it (Key Vault secret, configuration store, etc.) and trigger downstream restarts.

3. Internal admin portal / delegated operations

   • A small internal portal can call the function on behalf of authorized operators.

   • The portal becomes the UX layer, while the function remains the audited, least-privileged “knife switch” that performs the directory operation.

Architecture at a Glance

Here’s the moving parts that matter for the function app itself:

flowchart TB
      subgraph Azure["Azure Resource Group"]
            FA["Function App (Windows)
PowerShell 7.4"]
            KV["Key Vault
Secrets"]
            LA["App Insights / Log Analytics"]
      end

      subgraph VNet["VNet"]
            DC["Domain Controller
LDAPS :636"]
      end

      Caller["Calling App
(Entra client credentials)"] -->|Bearer token| FA
      FA -->|Managed Identity| KV
      FA -->|LDAPS <br>pinned cert + hostname validation | DC
      FA --> LA

Two design choices shape almost everything:

1. Authentication is delegated to the platform (App Service Authentication aka “Easy Auth”).

2. Directory operations are done via LDAPS using .NET LDAP APIs, with strict TLS validation.

Prerequisites

To follow along end-to-end you’ll need:

• An Entra ID app registration for the API, with role assignments for callers.

• App Service Authentication enabled for the Function App (configured in IaC).

• A domain controller reachable from the Function App via VNet integration.

• Two Key Vault secrets: - ENTRA-PWDRESET-RW (JSON containing username/password)

  • LDAPS-Certificate-CER (the domain controller’s public cert, base64)

The Request Walkthrough

Let’s walk the request the same way the runtime sees it.

Step 1: The request arrives (but your code doesn’t validate the JWT)

The caller sends Authorization: Bearer ....

Before PowerShell starts, Easy Auth validates the token:

• Signature + issuer via OIDC metadata (.../{tenantId}/v2.0).

• exp / nbf timing.

• Audience (aud). In this project the allowed audiences include both:

  • the plain client id, and

  • api://{clientId}

If validation fails, Easy Auth returns 401 and the function never runs.

Step 2: Easy Auth injects the principal

On success, Easy Auth injects X-MS-CLIENT-PRINCIPAL (base64 JSON). The function decodes it with:

$principal = Get-ClientPrincipal -HeaderValue $Request.Headers['X-MS-CLIENT-PRINCIPAL']

That gives us a consistent claim set without having to do token cryptography in PowerShell.

Step 3: Authorization is a role claim check

The function enforces a single rule: the caller must have the required role (from REQUIRED_ROLE).

$hasRole = Test-RoleClaim -Principal $principal -RequiredRole $env:REQUIRED_ROLE

No role claim → 403.

Step 4: Parse the body and choose the target user

The request body is intentionally small:

{ "samAccountName": "jdoe" }

If samAccountName is missing → 400.

Step 5: Fetch secrets with Managed Identity

At this point we have an authorized request, but we still need two things:

• AD service account credential (from Key Vault)

• LDAPS certificate pinning material (from Key Vault)

The function app uses its system-assigned managed identity to call Key Vault. Secrets are cached per runspace inside the helper module, so normal traffic doesn’t hammer Key Vault.

If the LDAPS certificate secret is missing or empty, the function fails fast with 500 (that’s a misconfiguration we don’t want to “best-effort” our way through).

The LDAPS Story (Strict, No Hostname Bypass)

Resetting passwords over LDAP is the part that tends to get hand-waved with “just trust the cert.” This project goes the other direction.

The function resets passwords over LDAPS using System.DirectoryServices.Protocols.LdapConnection, and validates the server certificate in two ways:

1. Certificate pinning: the presented server cert thumbprint must match the pinned cert retrieved from Key Vault.

2. Hostname validation: the cert must match the domain controller hostname (SAN/CN checks).

This keeps TLS strict without requiring the Function App sandbox to write to any certificate store. (On Windows-hosted Functions, opening cert stores for write is commonly blocked.)

Before attempting the TLS handshake, the code also performs a quick TCP preflight to port 636. That makes “network unreachable” failures look different from “TLS validation failed” failures, which is invaluable when debugging.

Generating and Returning the Password

The function generates a password with New-SecurePassword (length default 16, with required character classes), converts it to SecureString for the directory operation, and returns the plain text password in the response body.

The important operational rule is: no password is written to logs. The only place the generated password exists is in memory during that request and in the HTTPS response to an authorized caller.

Hosting and Scaling Notes

This function app runs on Elastic Premium (EP1) on Windows, because VNet integration is a core requirement for reaching the domain controller.

Concurrency is tuned with:

• FUNCTIONS_WORKER_PROCESS_COUNT=2

• PSWorkerInProcConcurrencyUpperBound=10

Those settings let a single app instance handle multiple requests in parallel while keeping directory operations responsive.

Where the Logic Lives

The entrypoint is intentionally small: it validates the request shape, checks role claims, and orchestrates calls into a helper module.

The heavy lifting lives in PasswordResetHelpers:

• Get-ClientPrincipal and Test-RoleClaim (authorization)

• Get-FunctionAdServiceCredential (Key Vault + MI)

• Get-FunctionLdapsCertificateBase64 (pinned cert from Key Vault)

• Set-ADUserPassword (LDAPS user lookup + unicodePwd modify)

Keeping the LDAPS plumbing in one place made it much easier to iterate on TLS validation without turning run.ps1 into a wall of LDAP code.

How the Pieces Fit Together in the Repo

The function app is intentionally small: one HTTP-triggered endpoint, one helper module, and a profile script for worker initialization.

Here’s the layout under project-functionapp-roles/FunctionApp:

FunctionApp/
      host.json
      local.settings.json               # local-only settings (not deployed)
      profile.ps1                       # runs once per worker instance
      requirements.psd1                 # managed dependencies
      ResetUserPassword/
            function.json                   # httpTrigger + http output binding
            run.ps1                         # endpoint handler
            PasswordResetHelpers.psm1       # core logic (auth parsing, Key Vault, LDAPS)
            PasswordResetHelpers.psd1       # module manifest

One detail that’s easy to miss: function.json uses "authLevel": "anonymous" because authentication is handled by Easy Auth before PowerShell runs.

The Startup Hook: profile.ps1

Azure Functions loads profile.ps1 once per PowerShell worker instance (think “once per worker process,” not once per request). In this project it does three things:

1. Sets strict error behavior (Set-StrictMode -Version Latest, $ErrorActionPreference = 'Stop').

2. Detects the Managed Identity endpoint variables (IDENTITY_ENDPOINT/IDENTITY_HEADER, with fallback to legacy MSI_*).

3. Optionally “warms” secrets by retrieving:

   • the AD service account secret (currently ENTRA-PWDRESET-RW), and

   • the LDAPS public cert (LDAPS-Certificate-CER).

The request path in run.ps1 does not depend on these global variables; it retrieves secrets on-demand through the helper module and caches per runspace. You can think of profile.ps1 as a worker-initialization script and (optionally) an early warning system if Managed Identity / Key Vault access is broken.

The Helper Module: PasswordResetHelpers.psm1

PasswordResetHelpers.psm1 is where the “real work” lives. Each function is small on purpose, so you can test and reason about the behavior in isolation.

• Get-ManagedIdentityAccessToken - Calls the App Service / Functions Managed Identity endpoint (new IDENTITY_* or legacy MSI_*) and returns an access token for a given resource.

• Get-KeyVaultSecretValue - Uses Managed Identity to fetch a secret value from Key Vault via the REST API.

• Get-FunctionAdServiceCredential - Builds a PSCredential either from local env vars (AD_SERVICE_USERNAME/AD_SERVICE_PASSWORD) or from Key Vault (ENTRA-PWDRESET-RW). It also fixes the common JSON-backslash issue (DOMAIN\svc) before parsing.

• Get-FunctionLdapsCertificateBase64 - Retrieves and caches LDAPS-Certificate-CER (base64). This is the pinning material used to validate the DC’s LDAPS certificate.

• Get-ClientPrincipal - Decodes the X-MS-CLIENT-PRINCIPAL header (base64 JSON) injected by Easy Auth, returning a PowerShell object with the caller’s claims.

• Test-RoleClaim - Scans the decoded principal for the required role (handles both roles and role claim types).

• New-SecurePassword - Generates a random password (default length 16) with required character classes.

• Test-LdapsTcpConnectivity - Performs a quick TCP connect check to host:636 so network problems are easier to distinguish from TLS/cert validation problems.

• ConvertFrom-LdapsCertificateBase64 - Parses the pinned certificate from base64, accepting either DER bytes or PEM text.

• Get-CertificateDnsNames - Extracts DNS names from the certificate (SANs first, with CN as fallback).

• Test-CertificateMatchesHostName - Validates that the certificate names match the domain controller hostname, including wildcard handling.

• New-LdapsConnection - Creates an LDAPS LdapConnection, enables SSL, and attaches a strict VerifyServerCertificate callback that enforces: 1) thumbprint pinning to the Key Vault cert, and 2) hostname validation.

• Get-ADUserDistinguishedName - Searches AD over LDAPS to find the user DN by sAMAccountName.

• Set-ADUserPassword - Uses LDAPS to modify unicodePwd for the target user (via ModifyRequest). This is the core “reset” operation.

The Endpoint: run.ps1

run.ps1 is intentionally written as a single guided flow (not a pile of helper functions). Conceptually, it’s a pipeline:

1. Validate request envelope

   • Requires X-MS-CLIENT-PRINCIPAL and checks required env vars (REQUIRED_ROLE, DOMAIN_CONTROLLER_FQDN, DOMAIN_NAME).

2. Decode principal + authorize

   • Get-ClientPrincipal → Test-RoleClaim → return 401/403 early if needed.

3. Parse and validate request body

   • Handles both string JSON and already-deserialized bodies, then requires samAccountName.

4. Load secrets needed for the operation

   • Get-FunctionAdServiceCredential for the bind credential.

   • Get-FunctionLdapsCertificateBase64 for the pinned cert (required).

5. Generate a password and apply it over LDAPS

   • New-SecurePassword generates the value returned to the caller.

   • Set-ADUserPassword performs the reset over LDAPS.

6. Return the response (with security headers)

   • Responds 200 with { samAccountName, password, resetTime, message } and Cache-Control: no-store to reduce accidental caching.

The Test Driver: Test-FunctionAppWithToken.ps1

The scripts/Test-FunctionAppWithToken.ps1 script is designed to simulate a real calling application. It uses the same client credentials flow your automation, portal, or service would use in production.

What it does:

1. Requests an access token from the Entra v2 token endpoint:

   • https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

2. Uses the .default scope for your API:

   • scope=api://{ApiAppId}/.default

3. Calls the function endpoint with Authorization: Bearer {token}.

4. Sends a JSON body that includes samAccountName (derived from UserPrincipalName). The current function only requires samAccountName; extra fields in the test payload are ignored.

Example usage:

./scripts/Test-FunctionAppWithToken.ps1 \
      -ClientId "<client-app-id>" \
      -ClientSecret "<client-secret>" \
      -TenantId "<tenant-id>" \
      -ApiAppId "<api-app-id>" \
      -FunctionAppUrl "https://<functionapp>.azurewebsites.net" \
      -UserPrincipalName "testuser1@contoso.com" \
      -NewPassword "IgnoredByCurrentAPI123!"

It also prints key token claims (aud, iss, roles) so when auth breaks you can quickly see whether you’re dealing with an audience mismatch, issuer mismatch, or missing role assignment.

To generate a app registration and secret for the calling app the scripts/Create-ClientAppRegistration.ps1 script can help.

Don't forget to grant admin consent for the API permissions after creating the app registration!

Conclusion

This project looks small on the surface—one endpoint that resets a password—but it only stays “boring” because the hard parts are handled deliberately.

• Easy Auth takes care of token validation so the function can focus on business logic.

• Authorization is reduced to a single, auditable decision: “does the caller have the role?”

• Key Vault + Managed Identity keeps credentials and pinning material out of code and out of deployment scripts.

• LDAPS with strict certificate pinning and hostname validation makes the directory operation secure without relying on fragile trust-store customization.

The result is an API you can demo, redeploy, and troubleshoot confidently: when it fails, it fails for reasons you can explain—and when it succeeds, it does exactly one thing, safely. 🚀

Quick Reference

• Endpoint: POST /api/ResetUserPassword

• Auth: Easy Auth (Entra ID v2 issuer) + role claim check

• Required request body: { "samAccountName": "..." }

• Key Vault secrets: ENTRA-PWDRESET-RW, LDAPS-Certificate-CER

• Directory transport: LDAPS on :636 with certificate pinning + hostname validation

Built with: PowerShell 7.4 • Azure Functions • Easy Auth • Key Vault (Managed Identity) • LDAPS

Here's a problem you might not be tracking as closely as you should: every workload identity in your Entra ID tenant—the service principals and app registrations powering your automation, CI/CD pipelines, and third-party integrations—is a potential security incident waiting to happen.

I'm not talking about user accounts. Those get MFA, Conditional Access policies, password expiry rules, and constant security team scrutiny. But workload identities? They tend to live in the shadows. Someone creates an app registration, generates a client secret, drops it into a GitHub secret or Azure Key Vault, and... that's it. No rotation schedule. No expiry monitoring. No privilege reviews. That secret could have been exfiltrated months ago and you'd never know until it's used to ransomware your tenant.

The wake-up call for most organizations comes from one of three places: an Entra ID Protection alert flagging a risky service principal (yes, that's a thing now), a penetration test report showing credential sprawl, or an audit finding that half your apps have Directory.ReadWrite.All when they only needed User.Read. By then you're playing catch-up.

This article walks through a practical solution I built to get ahead of that problem: a PowerShell 7.4 toolkit that discovers, triages, and remediates workload identity risk using Microsoft Graph. The philosophy is simple—stop rotating secrets and start eliminating them. Use federated credentials (OIDC workload identity) wherever possible, short-lived certificates where federation isn't an option, and actually monitor what your workload identities are doing.

If you're following Microsoft's guidance on protecting identities and secrets, this toolkit gives you the automation to make it real.

Prerequisites

Licensing requirements: The toolkit's discovery features work with any Entra ID tenant and require no additional licenses—the read-only scan operations use standard Microsoft Graph permissions available to all organizations. However, several of the scenarios and enforcement capabilities discussed in this article require premium licensing:

• Microsoft Entra ID P2 or Microsoft Entra ID Governance — Required to access Identity Protection risk detections for workload identities (the risky-service-principals.json and risky-service-principal-triage.json artifacts). Basic risk visibility (limited reporting details) is available without premium licenses, but full risk details and risk-based actions require a premium subscription.

• Microsoft Entra Workload Identities Premium — Required to create or modify Conditional Access policies scoped to service principals, to use risk-based Conditional Access conditions for workload identities, and to conduct access reviews of service principals in Privileged Identity Management. You can view, start a trial, and acquire licenses at https://portal.azure.com/#view/Microsoft_Azure_ManagedServiceIdentity/WorkloadIdentitiesBlade.

• Access Reviews for service principals — Requires both Workload Identities Premium and an ID Governance or ID P2 license.

The core scanning and reporting functionality—credential inventory, privileged role enumeration, high-privilege app permissions, and consent settings—operates without premium licenses. You can run the full scan, generate all artifacts, and build remediation plans using the free tier. Premium licensing becomes necessary when you move from visibility to enforcement (Conditional Access) or governance automation (PIM access reviews, advanced Identity Protection actions).

For more information, see:

• Microsoft Entra Workload ID licensing: https://www.microsoft.com/security/business/identity-access/microsoft-entra-workload-identities

• Microsoft Entra ID Governance licensing: https://learn.microsoft.com/en-us/entra/id-governance/licensing-fundamentals

• Conditional Access for workload identities: https://learn.microsoft.com/en-us/entra/identity/conditional-access/workload-identity

What This Toolkit Does

The WorkloadIdentityTools module is designed to answer a few critical questions about your Entra ID workload identities:

Which secrets are ticking time bombs? It inventories every credential across your app registrations—client secrets, certificates, federated credentials—and flags the ones that are long-lived (over 180 days) or nearing expiry (under 30 days). You get a risk score for each app so you can prioritize what to fix first.

Who has the keys to the kingdom? It enumerates which service principals hold privileged directory roles or dangerous Microsoft Graph permissions like Directory.ReadWrite.All or Application.ReadWrite.All. If you've got a CI/CD pipeline with Global Administrator, you'll know about it.

What's your consent posture? It pulls your tenant's authorization policy settings to show whether users can consent to apps, whether admin consent workflows are enabled, and who's allowed to create new app registrations. These are the knobs that control how workload identities proliferate in your environment.

Are any of your service principals already flagged as risky? Entra ID Protection now tracks risky workload identities (currently in beta). The toolkit pulls those signals and generates a triage report showing which service principals are at risk, confirmed compromised, or dismissed.

How do I actually fix this? It includes remediation helpers to create federated credentials (the secretless pattern for GitHub Actions, Azure workload identity federation, etc.) and rotate to short-lived certificates when federation isn't possible.

All of this data gets written to machine-readable JSON and CSV artifacts, so you can feed it into dashboards, SIEM systems, or just open it in Excel and start making a plan. The centerpiece is Scan-And-Report.ps1, a one-shot script that runs the full discovery sweep and drops everything into an ./out/ folder.

How the Repository is Organized

The project follows a standard PowerShell module layout. Everything lives under project-workload-identity/: the scripts/ folder has the standalone scan script and dependency installer, src/WorkloadIdentityTools/ contains the module itself (manifest, loader, public cmdlets, private helpers), and tests/Unit/ has Pester tests to validate the module loads correctly and the risk scoring logic works as expected. The README.md is your quick-start guide if you just want to run a scan; this blog post is the deep dive explaining why it exists and how it works under the hood.

When You'd Use This

Let's say you're a security engineer at a company that's been using Entra ID (formerly Azure AD) for a few years. You've got hundreds of app registrations scattered across dev, staging, and production. Some were created by developers who've since left. Some were generated by automated deployment scripts. A few are still using client secrets that were pasted into wikis during hackathons.

Scenario 1: The credential audit nobody wants to do manually. Your CISO wants a report on every long-lived secret in the tenant. You could click through the portal for hours, or you could run Scan-And-Report.ps1 and get a CSV with every credential, its age, and a risk score. Now you've got actionable data to build a migration roadmap.

Scenario 2: Identity Protection started alerting on a risky service principal. You're used to handling risky users, but this is new. What does a risky service principal even mean? Run the toolkit's risky workload identity triage and you'll see which apps are flagged, their risk levels, and recommendations for whether to confirm them as compromised or investigate further.

Scenario 3: You're migrating from secrets to workload identity federation. GitHub Actions just added OIDC support, and you want to stop storing AZURE_CLIENT_SECRET in every repository. Use the toolkit to inventory which apps are still using secrets, create federated credentials for the GitHub issuer, and track adoption over time by rerunning scans.

Scenario 4: The compliance team needs evidence. Auditors want proof that you're monitoring privileged app permissions and consent policies. The JSON artifacts the toolkit generates are timestamped, machine-readable compliance evidence. Drop them in an S3 bucket or Azure Storage container and you've got an audit trail.

Scenario 5: You want this in CI/CD. Run the scan nightly as a GitHub Actions workflow, publish the results as job summary markdown, and upload artifacts. If a new high-risk app appears, you'll see it in the workflow run without having to remember to check manually.

Why Not Just Rotate Secrets Faster?

I know what you're thinking: "We already have a secret rotation platform. Why not just rotate secrets every 90 days and call it done?"

Because rotation is a band-aid. It assumes the secret is the inevitable part of the design and tries to minimize exposure windows. But here's the thing—secrets don't have to exist at all.

Federated credentials (OIDC workload identity) and managed identities eliminate static secrets completely. Instead of storing a password-equivalent that could leak, you configure trust relationships. GitHub Actions proves it's running in your repository by presenting a signed OIDC token; Entra ID validates the token and issues a short-lived access token. No secret ever hits your CI/CD environment.

The advantages are huge:

• No exfiltration risk. There's nothing static to steal. An attacker would have to compromise the OIDC issuer itself (GitHub, Azure, AWS) which is significantly harder than grabbing a secret from a Key Vault or environment variable.

• No rotation schedules. Tokens are issued on-demand and expire in minutes or hours. You never have to coordinate "rotate this secret across 12 environments by Friday."

• Faster incident response. If a workload identity is compromised, you revoke the trust relationship in Entra ID. You don't have to hunt down every place a secret was copied.

• Better CI ergonomics. Developers don't need to know about secrets at all. They just configure the OIDC subject claim and it works.

• Policy enforcement at the identity layer. Conditional Access policies can apply to service principals. You can require MFA step-up, device compliance, or network restrictions without touching secret storage.

Where federation isn't an option—legacy systems, third-party integrations that don't support OIDC—short-lived certificates are the next best thing. A cert with a 30-day lifetime that auto-rotates is orders of magnitude safer than a 2-year client secret that someone pasted into Slack.

This toolkit exists to accelerate that transition: discover where secrets still exist, generate migration recommendations, and provide helpers to create federated credentials or rotate to short-lived certs. The goal isn't "rotate faster"; it's "remove the secret."

Layer adaptive controls: Once high-risk apps are identified, enforce Conditional Access for workload identities (requires Workload Identities Premium licensing) to block risky service principals based on location or risk signals. Pair this with Continuous Access Evaluation (CAE) so revocations—service principal disable, deletion, or risk escalation—take effect immediately without waiting for token expiry. Validate outcomes via the Service Principal sign-in logs to confirm that enforcement is working as expected. The toolkit's risky-service-principals.json and privileged-roles.json artifacts provide the candidate list for scoping these policies.

How It Works Under the Hood

The module is built on PowerShell 7.4 with strict mode, [CmdletBinding()] attributes, and proper parameter validation. It's designed to be testable (Pester tests with mocks) and pipeable (objects, not formatted text).

The Microsoft Graph PowerShell SDK is the engine. The v1.0 cmdlets handle apps, authorization policies, and role enumeration. For risky workload identities—which are currently in preview—it uses the beta endpoints. That means you need the Microsoft.Graph.Beta.* modules for some operations, and those APIs could change before they go GA. The toolkit makes that boundary explicit: cmdlets that touch beta data have Beta in the name (like Get-WiBetaRiskyServicePrincipal), and the documentation warns you upfront.

Authentication is context-aware. The Connect-WiGraph wrapper handles two modes: interactive delegated scopes for local runs (you authenticate as yourself and get prompted for consent), and automatic environment variable detection for CI/CD. When the toolkit sees AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_FEDERATED_TOKEN_FILE in the environment (which azure/login in GitHub Actions sets), it switches to Connect-MgGraph -EnvironmentVariable and authenticates as the pipeline's service principal with no interaction required. Local runs are unaffected—you just pass scopes like normal.

Discovery is read-only by default. When you run Scan-And-Report.ps1, it calls a series of cmdlets that enumerate applications, credentials, role assignments, app permissions, consent settings, and risky service principals. All of this uses the minimum Graph scopes required: Application.Read.All, Directory.Read.All, Policy.Read.All, IdentityRiskyServicePrincipal.Read.All. Nothing gets modified unless you explicitly invoke a remediation cmdlet.

Remediation cmdlets require higher privileges and support -WhatIf. Creating a federated credential needs Application.ReadWrite.All. Confirming a service principal as compromised needs IdentityRiskyServicePrincipal.ReadWrite.All and the Security Administrator role. Both scenarios use approved verbs (New-WiFederatedCredential, Set-WiRiskyServicePrincipalCompromised) with SupportsShouldProcess, so you can test with -WhatIf before committing changes.

Everything outputs structured data. The scan script writes JSON and CSV files to ./out/. Each artifact is timestamped and includes metadata like the tenant ID and when the scan ran. You can parse these with ConvertFrom-Json, load them into pandas, or push them to Azure Monitor Logs. There's no proprietary format—just standards.

Future enhancement: Optional CAE token capability detection and recommendation flags (proposed column SupportsCae in the credential inventory) would enable prioritization of workloads for real-time enforcement. Applications that send the xms_cc=cp1 claim in their token requests receive CAE-enabled long-lived tokens (24 hours) subject to instant revocation events—a powerful upgrade over traditional 1-hour token lifetimes.

The Discovery Side

The heavy lifting happens in a handful of cmdlets that map directly to Microsoft Graph queries:

Get-WiApplicationCredentialInventory pulls every app registration in the tenant and iterates over its passwordCredentials, keyCredentials, and federatedIdentityCredentials. For each credential, it calculates how long it's been active and how long until it expires. Long-lived (>180 days) or near-expiry (<30 days) credentials get flagged with a risk score. The output includes recommendations: "migrate to federated credential" for secrets, "shorten lifetime" for long-lived certs.

Get-WiServicePrincipalPrivilegedAssignments enumerates service principals with directory role assignments. It calls Get-MgDirectoryRole to list all roles, then fetches their members and filters for service principals. If you've got a CI pipeline with Global Administrator or an integration app with Privileged Role Administrator, it shows up here.

Get-WiHighPrivilegeAppPermissions looks for applications holding dangerous Graph permissions—things like Directory.ReadWrite.All, Application.ReadWrite.All, RoleManagement.ReadWrite.Directory. These are the permissions that let an app modify users, create new apps, or assign roles. You'd be surprised how many apps have these permissions "just in case."

Get-WiTenantConsentSettings fetches the authorization policy (Get-MgPolicyAuthorizationPolicy) and extracts the consent knobs: whether users can consent to apps, whether admin consent workflows are enabled, who can create apps, and whether email verification is required. This is the posture that controls how workload identities proliferate in your tenant.

Classification & Attributes: Beyond discovery, you can map discovered apps to custom security attributes (e.g., RiskTier, RemediationPhase, DataSensitivity) using Microsoft Graph PowerShell. Custom security attributes in Entra ID enable filtered views and targeted policy scope—for example, applying stricter Conditional Access policies to apps tagged with DataSensitivity=High or tracking migration progress with RemediationPhase=InProgress. While the toolkit doesn't automatically assign these attributes, the credential inventory and high-privilege permissions data provide the inputs for classification decisions. See https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/custom-security-attributes-apps for implementation guidance.

Get-WiBetaRiskyServicePrincipal and Get-WiBetaRiskyServicePrincipalHistory hit the Identity Protection beta endpoints to pull risky workload identities. These are service principals that Microsoft's risk detection systems have flagged—maybe they authenticated from an anonymous IP, or their credentials showed up in a breach, or there was anomalous sign-in behavior. The triage report (Get-WiRiskyServicePrincipalTriageReport) aggregates the distribution by risk level and risk state so you can see at a glance how many are at risk vs. confirmed compromised vs. dismissed.

The Remediation Side

Once you've identified problems, the toolkit provides helpers to fix them:

New-WiFederatedCredential creates a federated identity credential on an app registration. You specify the issuer (like https://token.actions.githubusercontent.com for GitHub Actions), the subject (like repo:myorg/myrepo:ref:refs/heads/main), and optionally the audience. The credential is created immediately and you can start using OIDC tokens to authenticate. No secret required.

Add-WiApplicationCertificateCredential generates a short-lived certificate credential. By default it's valid for 90 days, but you can configure shorter lifetimes. The cmdlet returns the certificate with private key so you can store it in Key Vault or another secure location. This is the fallback for systems that can't do federation.

Set-WiRiskyServicePrincipalCompromised and Clear-WiRiskyServicePrincipalRisk are the approved-verb wrappers around the Identity Protection risk action APIs. If a service principal is flagged and you've confirmed it's compromised (maybe you found the secret in a public repo), you mark it as compromised so Microsoft's signals improve. If it's a false positive, you dismiss the risk. Both cmdlets support -WhatIf so you can preview the action before committing.

All of these require elevated permissions: Application.ReadWrite.All for credential changes, IdentityRiskyServicePrincipal.ReadWrite.All plus the Security Administrator role for risk actions. The module won't prompt you for consent on the fly—you need to authenticate with those scopes upfront.

Post-remediation governance: After addressing immediate risks, seed Privileged Identity Management (PIM) recurring access reviews from the privileged-roles.json and high-privilege-app-permissions.json artifacts. Access reviews for service principals require Workload Identities Premium plus ID Governance licensing. Generate a CSV of candidate service principals with their role assignments, last sign-in dates, and permission counts, then import that scope into PIM to establish quarterly or semi-annual entitlement hygiene reviews. This closes the loop from discovery → remediation → ongoing governance. See https://learn.microsoft.com/en-us/entra/id-governance/privileged-identity-management/pim-create-roles-and-resource-roles-review for setup guidance.

Running It Yourself

The quickest way to see what you're dealing with is to run the scan locally. Here's what that looks like:

First, install the Microsoft Graph PowerShell modules:

./project-workload-identity/scripts/Install-Dependencies.ps1

This installs the Graph SDK and sets the PowerShell Gallery as trusted if it isn't already. You only need to do this once per machine.

Now import the module and authenticate:

Import-Module ./project-workload-identity/src/WorkloadIdentityTools/WorkloadIdentityTools.psd1
Connect-WiGraph -TenantId 'your-tenant-id'

By default, Connect-WiGraph requests delegated scopes for discovery (Application.Read.All, Directory.Read.All, etc.). You'll get an OAuth prompt asking for consent. Approve it and you're connected.

Now run the inventory:

$inventory = Get-WiApplicationCredentialInventory -All
$inventory | Where-Object { $_.RiskLevel -eq 'High' } | Format-Table DisplayName, CredentialType, DaysUntilExpiry, RiskReasons

This returns every high-risk credential in your tenant—secrets that are ancient, certificates about to expire, apps that should have migrated to federation months ago. The RiskReasons column tells you why it's flagged.

If you want to check risky service principals (beta), reconnect with the Identity Protection scope:

Connect-WiGraph -Scopes @('IdentityRiskyServicePrincipal.Read.All') -TenantId 'your-tenant-id'
$triage = Get-WiRiskyServicePrincipalTriageReport
$triage.Distribution.ByRiskLevel | Format-Table

This shows how many service principals are at each risk level and what states they're in. If you see any confirmed compromised, those need immediate action.

For a full scan with all the artifacts, just run:

./project-workload-identity/scripts/Scan-And-Report.ps1

The script connects, runs every discovery cmdlet, and writes JSON and CSV files to ./out/. You can open those in Excel, load them into Power BI, or push them to your SIEM.

Testing in a Dev Tenant

If you're running this in a brand-new dev tenant that doesn't have a ton of workload identities yet, the scan results might be underwhelming. You'll see a handful of app registrations, maybe none with high-risk credentials, and probably zero risky service principals because your tenant hasn't been around long enough for Identity Protection to build a baseline.

That's where the lab seeding scripts come in. Run:

./scripts/Bootstrap-WiLab.ps1 -TenantId 'your-dev-tenant-id'

This creates a set of wi-lab-* apps and service principals that cover the interesting cases: long-lived secrets, near-expiry secrets, certificate credentials, federated-only identities, and a few with high-privilege permissions. The script is idempotent—if you run it twice, it'll reuse the existing apps and update credentials as needed.

Now rerun the scan:

./scripts/Scan-And-Report.ps1

You'll see the lab identities show up in credential-inventory.json, high-privilege-app-permissions.json, and privileged-roles.json. This gives you realistic data to experiment with—try creating a federated credential on one of the secret-based apps, or rotate a certificate, and see how the scan results change.

When you're done, clean up:

./scripts/Cleanup-WiLab.ps1 -TenantId 'your-dev-tenant-id'

This removes all the wi-lab-* identities. Use -WhatIf first if you want to preview what it's going to delete.

Important: Do not run these scripts in production. They're designed for non-production tenants where you can safely create and delete app registrations. The bootstrap script doesn't manipulate Identity Protection risk state directly (you can't forge risk detections anyway), so the risky service principals report will stay empty in a fresh dev tenant—and that's fine.

Hooking It Into CI/CD

The real power comes from running this continuously. You want to catch new high-risk apps the day they're created, not during the next quarterly audit.

Here's how you set that up in GitHub Actions. First, create a service principal in Entra ID and configure a federated credential for your GitHub repo (see New-WiFederatedCredential or do it in the portal). Grant it the Graph application permissions it needs: Application.Read.All, Directory.Read.All, Policy.Read.All, IdentityRiskyServicePrincipal.Read.All. Make sure those permissions are admin-consented.

Add the service principal's client ID and your tenant ID as GitHub repository secrets:

• AZURE_CLIENT_ID

• AZURE_TENANT_ID

• AZURE_SUBSCRIPTION_ID (required by azure/login)

• WI_SCAN_TENANT_ID (can be the same as AZURE_TENANT_ID)

Now create a workflow file (.github/workflows/workload-identity-scan.yml) that looks like this:

name: Workload Identity Scan
on:
  schedule:
    - cron: "0 2 * * *" # Daily at 2 AM UTC
  workflow_dispatch:

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v3

      - name: Azure Login (OIDC)
        uses: azure/login@v1
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Install Dependencies
        shell: pwsh
        run: ./project-workload-identity/scripts/Install-Dependencies.ps1

      - name: Run Scan
        shell: pwsh
        env:
          WI_SCAN_TENANT_ID: ${{ secrets.WI_SCAN_TENANT_ID }}
        run: ./project-workload-identity/scripts/Scan-And-Report.ps1

      - name: Render HTML Report
        shell: pwsh
        run: ./project-workload-identity/scripts/Write-ScanReport.ps1 -OutputFolder ./out

      - name: Publish Report Summary
        shell: pwsh
        env:
          REPORT_PATH: ./out/workload-identity-report.html
        run: ./project-workload-identity/scripts/Publish-ScanReportSummary.ps1

      - name: Upload Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: wi-scan-artifacts
          path: ./out/

The azure/login step sets the AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_FEDERATED_TOKEN_FILE environment variables. When the scan script calls Connect-WiGraph, it detects those variables and uses Connect-MgGraph -EnvironmentVariable to authenticate as the service principal—no client secret required.

The workflow runs nightly, scans the tenant, generates an HTML report, publishes a summary to the GitHub Actions job summary (so you can see highlights without downloading artifacts), and uploads the full JSON/CSV artifacts for later analysis.

If a new high-risk app appears, you'll see it in the next morning's workflow run. If someone creates a service principal with Global Administrator, it shows up in privileged-roles.json. If Identity Protection flags a risky workload identity, it's in the triage report. All without manual intervention.

Optionally generate conditional-access-candidates.json: Extend the scan to produce a list of service principal object IDs exceeding defined risk thresholds (e.g., high-risk credentials + privileged roles, or confirmed risky status from Identity Protection). This artifact can drive out-of-band policy provisioning—import the object IDs into a Conditional Access policy scoped to block access from untrusted locations or at elevated risk levels. The candidates file becomes a living policy scope that updates nightly as new high-risk apps are discovered.

What You Get Out

Every scan writes a set of artifacts to ./out/. Here's what each one contains:

credential-inventory.json / .csv — Every credential across all app registrations: when it was created, when it expires, its type (secret/cert/federated), risk level, and recommended actions. This is your starting point for building a remediation roadmap.

privileged-roles.json — Service principals with directory role assignments. If a CI pipeline has Global Administrator or an integration app has Privileged Role Administrator, it's in here.

high-privilege-app-permissions.json — Applications holding dangerous Graph permissions like Directory.ReadWrite.All, Application.ReadWrite.All, or RoleManagement.ReadWrite.Directory. These are the apps that could wreak havoc if compromised.

consent-settings.json — Your tenant's authorization policy: whether users can consent to apps, whether admin consent workflows are enabled, who can create apps. This is the posture that controls how workload identities proliferate.

risky-service-principals.json — Identity Protection's list of risky workload identities (beta). Includes risk level, risk state (at risk, confirmed compromised, dismissed), and when the risk was detected.

risky-service-principal-triage.json — Aggregated summary of risky service principals: how many at each risk level, distribution by state, recommendations for action.

scan-summary.json — High-level counts: total apps, total credentials, how many are high-risk, how many are federated, etc. This is useful for dashboards or executive summaries.

workload-identity-report.html — An HTML dashboard that presents all of the above in a human-readable format. Open it in a browser and you've got a visual overview with sortable tables and color-coded risk levels.

Demo HTML Report - PowerShell:

Demo HTML Report - GitHub Actions:

All JSON files include metadata (tenant ID, scan timestamp) and follow a consistent schema. You can load them into Power BI, push them to Azure Monitor Logs, or just ConvertFrom-Json and analyze them in PowerShell.

What This Isn't

Let's be clear about scope. This toolkit is designed to discover workload identity risks and provide remediation helpers—it's not trying to be a full-blown identity governance platform.

It's not a SIEM pipeline. The artifacts are JSON and CSV files you can push to your SIEM, but the toolkit itself doesn't handle log ingestion, correlation, alerting, or retention policies. You'll need to wire that up yourself.

It's not a Conditional Access automation tool. You can use the privileged app permission data to inform CA policy design, but the toolkit doesn't create or modify Conditional Access policies. That's a separate problem domain.

It's not doing ML-based risk enrichment. The risk scoring for credentials is rule-based (age > 180 days = long-lived, expiry < 30 days = near-expiry). Identity Protection's risky service principal detections come from Microsoft's ML models, but this toolkit just surfaces them—it doesn't extend or retrain the models.

It's not bundling interactive dashboards. The HTML report is a standalone file you can open in a browser, but it's not a live dashboard with drill-downs and refresh buttons. If you want that, load the JSON artifacts into Power BI or Grafana.

The goal is to give you the raw material—discovery data, remediation helpers, structured output—so you can build the governance workflow that fits your organization. The toolkit handles the hard part (querying Graph, scoring risk, generating artifacts); you handle the integration layer.

Security and Governance Notes

A few things to keep in mind as you use this toolkit:

The artifacts don't contain secrets, but they do reveal privilege posture. The credential inventory includes metadata (credential IDs, start/end dates) but not the actual secrets or private keys. However, someone with access to these artifacts can see which apps have high-risk credentials, privileged role assignments, or dangerous permissions. Treat the output files accordingly—don't drop them in a public S3 bucket.

Beta APIs are subject to change. The risky workload identity endpoints are currently in preview. Microsoft could change the schema, retire properties, or move things to v1.0 with breaking changes. Always test in a non-production tenant first, and expect to update the toolkit when those APIs go GA.

Least privilege applies to the scanner too. The scan runs with read-only Graph permissions by default. Don't grant it Application.ReadWrite.All or Directory.ReadWrite.All unless you're actively using the remediation cmdlets. If you're running this in CI, consider using a separate service principal for discovery vs. remediation, so the nightly scan can't accidentally modify your tenant.

Use the artifacts for compliance evidence. The JSON files are timestamped and include the tenant ID. If you need to prove to auditors that you're monitoring workload identity risk, archive these artifacts in Azure Storage or an S3 bucket with immutability policies. Now you've got a tamper-evident audit trail.

Integrate with access reviews. If you're using Entra ID Governance access reviews for service principals, you can use the privileged role and high-privilege permission data from this toolkit to seed the review scope. Export the JSON, identify the high-risk apps, and kick off targeted reviews for those identities.

Enable CAE for eligible workload identities. Applications accessing Microsoft Graph can opt into Continuous Access Evaluation by requesting tokens with the xms_cc=cp1 claim. This enables 24-hour long-lived tokens subject to instant revocation on disable, delete, or risk state changes. Monitor revocations in the Service Principal sign-in logs—look for the "Continuous access evaluation" field and verify that blocked sessions show appropriate failure reasons. Track an adoption metric (percentage of high-privilege principals covered by Conditional Access policies) to measure your enforcement posture over time. Note: Conditional Access for workload identities requires Workload Identities Premium licensing and applies only to single-tenant service principals (managed identities and multi-tenant apps are excluded).

References

PowerShell / Testing:

• Pester overview: https://learn.microsoft.com/powershell/scripting/testing/overview?view=powershell-7.4

Graph SDK (v1.0):

• Connect-MgGraph: https://learn.microsoft.com/powershell/microsoftgraph/authentication/connect-mggraph?view=graph-powershell-1.0

• Get-MgApplication: https://learn.microsoft.com/powershell/module/microsoft.graph.applications/get-mgapplication?view=graph-powershell-1.0

• New-MgApplicationFederatedIdentityCredential: https://learn.microsoft.com/powershell/module/microsoft.graph.applications/new-mgapplicationfederatedidentitycredential?view=graph-powershell-1.0

• Add-MgApplicationKey: https://learn.microsoft.com/powershell/module/microsoft.graph.applications/add-mgapplicationkey?view=graph-powershell-1.0

• Get-MgPolicyAuthorizationPolicy: https://learn.microsoft.com/powershell/module/microsoft.graph.identity.signins/get-mgpolicyauthorizationpolicy?view=graph-powershell-1.0

Graph Beta (Risky Workload Identities):

• List risky SPs: https://learn.microsoft.com/en-us/graph/api/identityprotectionroot-list-riskyserviceprincipals?view=graph-rest-beta

• Risk history: https://learn.microsoft.com/en-us/graph/api/riskyserviceprincipal-list-history?view=graph-rest-beta

• Confirm compromised: https://learn.microsoft.com/en-us/graph/api/riskyserviceprincipal-confirmcompromised?view=graph-rest-beta

• Dismiss risk: https://learn.microsoft.com/en-us/graph/api/riskyserviceprincipal-dismiss?view=graph-rest-beta

Where to Go From Here

Workload identity risk isn't a "rotate secrets faster" problem. It's a "stop using secrets" problem. And until you get there, it's a "know what you have" problem.

This toolkit gives you visibility into the current state: which apps are using ancient secrets, which service principals have privileged access, which identities are already flagged by Identity Protection. That's the baseline. From there, you build a remediation roadmap: migrate GitHub Actions to OIDC federation, rotate long-lived certificates to short-lived ones, remove excessive Graph permissions, revoke privileged roles that aren't actively used.

The key is making this continuous. Run the scan nightly in CI/CD. Publish the results to your security team's dashboard. Alert on new high-risk apps. Track migration progress over time. When the next penetration test happens, you'll have months of audit data showing you've been actively managing workload identity risk—not just reacting to findings.

Extend the artifacts into whatever system you already use: Power BI for executive dashboards, Azure Monitor Logs for alerting, ServiceNow for ticketing, Jira for remediation tracking. The JSON schema is stable and documented; you're not locked into a proprietary format.

The end goal is a tenant where standing secrets don't exist, privileged assignments are time-bound and deliberate, and compliance evidence is generated automatically. That's achievable today with the tools Entra ID already provides—federated credentials, short-lived certificates, managed identities, Conditional Access for service principals, Identity Protection for workload identities. This project just gives you the automation to make it practical.

Start with a scan. See what you're dealing with. Build a plan. Automate the remediation. Repeat.

The blueprint is here. The rest is execution. 🚀’

For all the files and code snippets mentioned, check out my GitHub repository.

License: MIT

This all started from a very practical problem: I wanted a disposable, repeatable Active Directory lab I could spin up for demos, tutorials, and future blog posts (stay tuned). I needed something I could tear down and rebuild without fear—no hand-configured servers, no “click-next-until-it-works” wizards.

The goal was simple: run one command, get a fully functional AD domain in Azure; run another, and everything disappears again. Under the hood, though, that meant solving some surprisingly gnarly problems: secure credential handling, domain controller promotion across reboots, post-configuration of service accounts and test users, and enough logging that I could actually debug it at 2 a.m. when something went sideways. 🤣

This post walks through how that infrastructure works: the Bicep template that defines the environment, the Deploy-Complete.ps1 script that orchestrates it, and the PowerShell that runs inside the VM to actually stand up and configure the domain controller.

Architecture at a Glance

Before diving into the code, here's a bird's-eye view of what gets deployed:

flowchart TB
    subgraph Azure["Azure Resource Group"]
        subgraph VNet["Virtual Network (10.0.0.0/16)"]
            subgraph DCSub["DC Subnet (10.0.1.0/24)"]
                DC["Domain Controller VM
                (Windows Server 2022)"]
            end
            subgraph FuncSub["Function App Subnet (10.0.2.0/24)"]
                FA["Function App
                (PowerShell 7.4)"]
            end
        end
        KV["Key Vault
        (Secrets)"]
        LA["Log Analytics
        + App Insights"]
        ST["Storage Account"]
    end

    FA -->|Managed Identity| KV
    FA -->|LDAP/Password Reset| DC
    FA --> LA
    FA --> ST

The domain controller sits in its own subnet, the function app in another. Key Vault holds the service account credentials, and everything feeds telemetry into Log Analytics. Simple, but it took some iteration to get the automation right.

One of those iterations was networking. The Function App isn’t automatically “in your VNet,” and for this scenario that matters: the API needs a private path to the DC (LDAPS on 636) and it needs to resolve the DC’s internal name reliably.

So the infrastructure doesn’t just deploy a VNet—it makes the Function App a first-class citizen inside it: a delegated subnet for VNet integration, routing that keeps traffic on the private path, and DNS that intentionally points the function at the domain controller.

Prerequisites

Before you can deploy this lab, make sure you have:

• An Azure subscription with at least Contributor rights on the target resource group

• PowerShell 7.4+ installed locally (the deployment script requires it)

• The Az PowerShell module (Install-Module Az -Scope CurrentUser)

• The Bicep CLI (install instructions)

• A clone of the repo with the parameter files configured for your environment

With those in place, you're ready to go.

The Blueprint: Bicep as Our Architect

I started with Bicep, Azure's declarative language for infrastructure. Instead of clicking through endless Azure Portal screens, I wrote a template that describes everything:

• The domain controller VM, with spot pricing for cost savings (because why pay more for test/dev?)

• A dedicated VNet, subnets, and NSGs to keep traffic locked down

• Key Vault for secrets, Log Analytics for diagnostics, and all the glue that ties it together

The core of the VM definition in infra/main.bicep looks like this:

resource dcVm 'Microsoft.Compute/virtualMachines@2025-04-01' = if (deployDomainController) {
    name: dcVmName
    location: location
    tags: tags
    properties: {
        hardwareProfile: {
            vmSize: 'Standard_D2s_v3'
        }
        priority: 'Spot'
        evictionPolicy: 'Deallocate'
        billingProfile: {
            maxPrice: -1
        }
        osProfile: {
            computerName: take(dcVmName, 15)
            adminUsername: vmAdminUsername
            adminPassword: vmAdminPassword
            windowsConfiguration: {
                enableAutomaticUpdates: true
                provisionVMAgent: true
                timeZone: 'UTC'
            }
        }
        // ... storageProfile, networkProfile, diagnosticsProfile ...
    }
}

The priority: 'Spot' and evictionPolicy: 'Deallocate' combination gives me a cost‑effective lab that can be evicted without data loss, because the actual AD database lives on a managed data disk. The maxPrice: -1 setting tells Azure “go up to the regular pay‑as‑you‑go price if needed,” which keeps the lab resilient without me micromanaging spot pricing.

Around that VM, the Bicep file provisions:

• A VNet with separate subnets for the domain controller and the function app

• A Network Security Group that allows the handful of ports AD really needs

• A Key Vault with a JSON secret that stores the service account credentials

• A Log Analytics workspace and Application Insights for observability

Every parameter—domain name, NetBIOS name, admin credentials—can be set at deploy time. If you want to change the environment from dev to prod, it’s just a flag. The Bicep file is our single source of truth, and it’s versioned right alongside the rest of the repo.

And because the function app needs to reach the DC over the VNet, the template also bakes in a couple of important network choices:

• The Function App runs on Elastic Premium (EP1) (Consumption can’t do VNet integration)

• The Function App is integrated with the FunctionAppSubnet and configured to route outbound traffic via the VNet

• DNS for the Function App is pointed at the domain controller, so dcname.contoso.local resolves the same way it would from a domain-joined machine

If you want to go deeper on Bicep itself, the official docs are here:

• Azure Bicep overview: https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview

• Bicep deployment with CLI/PowerShell: https://learn.microsoft.com/azure/azure-resource-manager/bicep/deploy-cli

Orchestration: Deploy-Complete.ps1, the Maestro

Once the infrastructure is described, I need to bring it to life. That's where scripts/Deploy-Complete.ps1 comes in. This PowerShell script isn’t just a wrapper—it’s the conductor of our deployment symphony.

At the top, it does some basic but important hygiene:

#!/usr/bin/env pwsh
#Requires -Version 7.4

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

Set-StrictMode and $ErrorActionPreference = 'Stop' ensure that typos and unexpected errors don’t silently slip by—exactly what you want in an automation script that’s going to manipulate infrastructure. From there, it validates prerequisites (Az module, Bicep CLI, parameter files) and makes sure you’re logged in with Connect-AzAccount.

The real fun starts when you enable the domain controller flag. The script wires up secure parameters for the VM admin and service account passwords, then calls into Bicep using New-AzResourceGroupDeployment:

$deployment = New-AzResourceGroupDeployment @{
    ResourceGroupName     = $ResourceGroupName
    TemplateFile          = $bicepFile
    TemplateParameterFile = $parametersFile
    vmAdminPassword       = $VmAdminPassword
    serviceAccountPassword = $ServiceAccountPassword
}

Once the infrastructure is laid down, Deploy-Complete.ps1 moves into a second phase: in‑guest configuration. If you’ve asked for a domain controller, the script waits for the VM to be running, then uses Azure VM Run Command to invoke Bootstrap-ADDSDomain.ps1 on the VM itself:

$bootstrapScript = Get-Content (Join-Path $scriptDir 'Bootstrap-ADDSDomain.ps1') -Raw
$plainPassword   = [System.Net.NetworkCredential]::new('', $VmAdminPassword).Password
$passwordBase64  = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($plainPassword))

$null = Invoke-AzVMRunCommand -AsJob `
    -ResourceGroupName $ResourceGroupName `
    -VMName            $VmName `
    -CommandId         'RunPowerShellScript' `
    -ScriptString      $bootstrapScript `
    -Parameter         @{
        DomainName                  = $DomainName
        DomainNetBiosName           = $DomainNetBiosName
        SafeModeAdminPasswordBase64 = $passwordBase64
    }

The important detail here is the Base64 encoding of the Safe Mode password. Passing SecureString values across the Run Command boundary can lead to mangled data; by converting to UTF‑8 bytes, then to Base64, then reversing that inside the VM, I keep the password intact without logging it or exposing it in plain text outside controlled boundaries.

Azure Run Command docs if you want to explore this pattern yourself: https://learn.microsoft.com/azure/virtual-machines/run-command

The Heartbeat: Domain Controller Promotion

Promoting a Windows Server to a domain controller is a delicate dance. The script inside the VM, scripts/Bootstrap-ADDSDomain.ps1, handles the choreography.

First, it formats the attached data disk and mounts it to a stable drive letter so the AD database and SYSVOL have a predictable home. Then it installs the Active Directory Domain Services role and related management tools. Only after that does it generate the actual promotion script.

The interesting bit is how the promotion is launched:

$promotionScript = @'
Start-Transcript -Path "C:\temp\Promote-ADDSForest-Transcript.log" -Append

Import-Module ADDSDeployment -ErrorAction Stop

$passwordPlain = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('$SafeModeAdminPasswordBase64'))
$passwordSec   = ConvertTo-SecureString -String $passwordPlain -AsPlainText -Force

Install-ADDSForest -DomainName '$DomainName' -DomainNetbiosName '$DomainNetBiosName' `
    -SafeModeAdministratorPassword $passwordSec -Force:$true -NoRebootOnCompletion:$false

Stop-Transcript
'@

Set-Content -Path 'C:\temp\Promote-ADDSForest.ps1' -Value $promotionScript -Encoding UTF8
Start-Process -FilePath 'powershell.exe' -ArgumentList '-NoProfile','-ExecutionPolicy','Bypass','-File','C:\temp\Promote-ADDSForest.ps1' -WindowStyle Hidden

Two key design choices here:

1. The promotion runs in a detached Windows PowerShell 5.1 process. That means when the VM reboots, Azure Run Command doesn’t get “stuck” waiting on a process that no longer exists.

2. The Safe Mode password is reconstructed from Base64 and converted to SecureString inside the VM, which avoids all the strange quoting and whitespace issues you get when trying to pass complex strings across layers.

If you’re curious about the cmdlet doing the heavy lifting, Install-ADDSForest is documented here: https://learn.microsoft.com/powershell/module/addsdeployment/install-addsforest

Detecting the Reboot: Smarter Than PowerState

After the promotion, the VM reboots. But how do I know when it's back and ready? Early on, I tried watching the VM's PowerState, and it worked—until it didn't. There were edge cases where the VM reported running but AD services weren't ready yet.

The final approach lives in Invoke-DomainControllerPostConfig inside Deploy-Complete.ps1. It asks the VM for its boot time via CIM and watches for that value to change:

$bootTimeScript = 'Get-CimInstance -ClassName Win32_OperatingSystem | Select-Object -ExpandProperty LastBootUpTime'
$bootResult     = Invoke-AzVMRunCommand -ResourceGroupName $ResourceGroupName -VMName $VmName -CommandId 'RunPowerShellScript' -ScriptString $bootTimeScript

$initialBootTime = [DateTime]::Parse(($bootResult.Value[0].Message).Trim())

while ($elapsed -lt $timeout) {
    $currentBootResult = Invoke-AzVMRunCommand -ResourceGroupName $ResourceGroupName -VMName $VmName -CommandId 'RunPowerShellScript' -ScriptString $bootTimeScript -ErrorAction SilentlyContinue

    if (-not $currentBootResult) {
        $rebootWindowObserved = $true
    }
    else {
        $currentBootTime = [DateTime]::Parse(($currentBootResult.Value[0].Message).Trim())

        if ($initialBootTime -and $currentBootTime -and ($currentBootTime -ne $initialBootTime)) {
            $rebootDetected = $true
        }
        elseif ($rebootWindowObserved -and $currentBootTime) {
            $rebootDetected = $true
        }
    }

    if ($rebootDetected) { break }
    Start-Sleep -Seconds $checkInterval
}

Only after a reboot is confidently detected does the script run a second health check:

$testScript = 'try { Import-Module ActiveDirectory -ErrorAction Stop; Get-ADDomain -ErrorAction Stop | Out-Null; exit 0 } catch { exit 1 }'
$testResult = Invoke-AzVMRunCommand -ResourceGroupName $ResourceGroupName -VMName $VmName -CommandId 'RunPowerShellScript' -ScriptString $testScript -ErrorAction SilentlyContinue

When Get-ADDomain finally succeeds, I know that AD Web Services are up and the domain controller is genuinely ready for the next phase.

Post-Configuration: Making AD Useful

With the domain up, I run another script, scripts/Configure-ADPostPromotion.ps1, via Run Command. This is where the environment turns from “just a domain” into something that’s actually useful.

The script waits for AD Web Services to be available, then creates an Organizational Unit and a service account that will later be used by a function app. It also creates a handful of test users so you can validate the end‑to‑end reset flow.

And because the whole point of this lab is “real-world enough to be interesting,” it also wires up LDAPS on the domain controller. That ended up being one of the most important (and most finicky) pieces of the entire build.

The heart of the service account creation looks like this:

$serviceAccountPasswordSecure = ConvertTo-SecureString -String $ServiceAccountPassword -AsPlainText -Force

$serviceAccountParams = @{
    Name                 = $ServiceAccountName
    SamAccountName       = $ServiceAccountName
    UserPrincipalName    = "$ServiceAccountName@$DomainName"
    AccountPassword      = $serviceAccountPasswordSecure
    Enabled              = $true
    PasswordNeverExpires = $true
    CannotChangePassword = $true
    Path                 = $ouPath
    Description          = 'Service account for Azure Function App password reset operations'
}

New-ADUser @serviceAccountParams

If the account already exists, the script switches to an update path:

Set-ADAccountPassword -Identity $ServiceAccountName -NewPassword $serviceAccountPasswordSecure -Reset

Finally, it grants the service account reset password rights at the domain level by editing the ACL and adding an access rule for the “Reset Password” extended right. This lines up perfectly with the least‑privilege expectations of the function app.

Networking: Getting the Function App to “See” the DC

Once the pieces were in place, the actual connectivity requirement was simple: the Function App must be able to reach the DC’s private IP on the right ports, and it must be able to resolve internal AD DNS names.

The part that surprised me was how much of that comes down to DNS behavior.

In infra/main.bicep, the Function App is integrated into the VNet subnet and configured with a couple of app settings that make it behave like a VNet-attached workload:

• WEBSITE_VNET_ROUTE_ALL = 1 routes outbound traffic through the VNet (so LDAPS to the DC stays on the private path).
• WEBSITE_DNS_SERVER = 10.0.1.4 points the Function App at the DC for DNS, so it can resolve the AD domain and the DC’s FQDN.

But if the Function App uses the DC for DNS, the DC now has to resolve public names too—especially during authentication flows where it may need to reach Entra ID endpoints.

That’s why Configure-ADPostPromotion.ps1 configures DNS forwarders on the DC. The default is Azure’s VNet DNS forwarder 168.63.129.16, which keeps internal resolution authoritative while still allowing lookups for everything else.

LDAPS: Giving the DC a Real TLS Identity

LDAP over SSL (port 636) isn’t something you “turn on” with a checkbox. On Windows Server, AD DS will only present LDAPS if the DC has a usable certificate in the Local Machine Personal store.

Here’s the pattern that ended up being reliable and repeatable:

1. Generate a self-signed LDAPS certificate during deployment

   • Deploy-Complete.ps1 generates a cert using OpenSSL with the right constraints:

     • extendedKeyUsage = serverAuth

     • SANs for the DC FQDN (and a wildcard for the domain)

   • It exports two forms:

     • a PFX (private key included) for the domain controller

     • a DER .cer (public key only) that’s easy for clients to parse

2. Install the PFX on the domain controller

   • Configure-ADPostPromotion.ps1 imports the PFX into Cert:\LocalMachine\My.

   • It performs basic sanity checks (private key present + “Server Authentication” EKU) and then does a quick Test-NetConnection localhost -Port 636 to see if LDAPS is listening.

3. Publish the public cert for the client to pin

   • The public .cer is stored in Key Vault as LDAPS-Certificate-CER.

   • The Function App retrieves this value at runtime and uses it for strict certificate pinning + hostname validation.

That last step is the key architectural shift: rather than trying to “teach” the Function App host to trust a private PKI (which is often blocked in sandboxed hosting), the function validates the server cert directly during the LDAPS handshake. No hostname bypass, no trust-store hacks—just strict TLS with a pinned identity.

If you want to see the building blocks behind these cmdlets, the official docs are a great reference:

• New-ADUser: https://learn.microsoft.com/powershell/module/activedirectory/new-aduser

• New-ADOrganizationalUnit: https://learn.microsoft.com/powershell/module/activedirectory/new-adorganizationalunit

• Set-ADAccountPassword: https://learn.microsoft.com/powershell/module/activedirectory/set-adaccountpassword

Lessons Learned (and a Few Battle Scars)

I didn't get it right the first time. Not even close. Here are some of the detours I took along the way.

The SecureString Saga

My first attempt passed SecureString values directly through Azure Run Command parameters. That worked fine locally, but when the script ran inside the VM, the password came out garbled—random whitespace, truncated characters, the works. After way too much debugging, I landed on the Base64 approach: convert the password to UTF-8 bytes, encode as Base64, pass that string, then decode and convert back to SecureString inside the VM. It's an extra step, but it's reliable across every boundary.

Scheduled Tasks: A Dead End

Originally, the promotion script created a Windows Scheduled Task to run Install-ADDSForest. The idea was that the task would survive the reboot and finish the job. In practice, it was flaky—sometimes the task fired, sometimes it didn't, and debugging was a nightmare. Switching to a detached powershell.exe process (launched via Start-Process) was simpler and worked every time. The promotion runs, the VM reboots, and Run Command just times out gracefully while the real work continues in the background.

PowerState Lies (Sometimes)

I wasted hours watching the VM's PowerState flip to running and assuming AD was ready. It wasn't. The VM was up, but AD Web Services were still initializing. The fix was to query the VM's boot time via CIM and wait for it to actually change after the reboot. Even better, I treat Run Command failures during the reboot window as a signal that the VM is mid-restart. Once boot time updates and Get-ADDomain succeeds, I know the domain is genuinely online.

Log Everything to Disk

This sounds obvious, but it saved me more than once. Every script writes progress and errors to C:\temp. When something breaks, I can RDP in, open the logs, and see exactly where the process stopped. Transcripts, timestamps, and descriptive messages—don't skip them.

LDAPS Certificates Are Picky (and Schannel Will Tell You)

The fastest way to lose an afternoon is to generate a certificate that looks “fine” but isn’t usable by Schannel. If the certificate doesn’t have a private key, doesn’t include the right EKU, or doesn’t match the hostname the client is connecting to, LDAPS can fail with confusing symptoms.

The fix was to treat the certificate like a real production TLS credential: SANs, proper EKU, and a private key that actually imports correctly. Once that’s in place, LDAPS becomes boring—in the best way.

The End Result: Automated, Auditable, and Secure

Now, spinning up a new AD environment is as simple as running a script. Every step is automated, every credential is handled securely, and every log is there if you need it in less than 15 minutes! The infrastructure is ready for my password reset API, and I can redeploy, tear down, or troubleshoot with confidence.

If you’re building hybrid cloud solutions, don’t underestimate the value of good orchestration and clear logging. It’s the difference between a fragile dev/lab environment and a production-ready system.

How the Pieces Fit Together in the Repo

If you want to explore or reuse this setup, here’s the key structure of the repo:

project-functionapp-roles/
    infra/
        main.bicep                  # All Azure resources, including the domain controller VM
        parameters.dev.json         # Parameter file for deployments
    scripts/
        Deploy-Complete.ps1         # Orchestrates deployment, promotion, and post-config
        Bootstrap-ADDSDomain.ps1    # Runs inside the VM to install AD DS and promote to DC
        Configure-ADPostPromotion.ps1 # Creates OU, service account, and test users

You can clone the repo, tweak the parameters, and use it as your own disposable AD lab.

Azure PowerShell docs for some of the commands used here:

• New-AzResourceGroupDeployment: https://learn.microsoft.com/powershell/module/az.resources/new-azresourcegroupdeployment

• Get-AzVM and Invoke-AzVMRunCommand: https://learn.microsoft.com/powershell/module/az.compute/invoke-azvmruncommand

Tearing It All Down

The whole point of a disposable lab is that you can throw it away when you're done. Since everything lives in a single resource group, cleanup is one command:

Remove-AzResourceGroup -Name rg-pwdreset-dev -Force

That deletes the VM, disks, VNet, Key Vault, and everything else in one shot. No orphaned resources, no lingering costs. If you're doing iterative development or writing your own blog posts, this is the reset button.

Conclusion

At the end of the day, this whole setup is about confidence. I can spin up a full AD lab, break it in interesting ways, write about what I learned, and then throw it away—all without touching a production environment or repeating the same manual steps.

If you want to follow along or adapt it for your own scenarios, all of the code in this post lives in my GitHub repository:

• GitHub repo: https://github.com/broberts23/vsCode/project-functionapp-roles

Clone it, customize the parameters, and you’ve got your own disposable AD playground ready for experiments, demos, and (in future posts) the password reset API that sits on top of it. 🚀

Built with: Bicep • PowerShell 7.4 & 5.1 • Azure Run Command • Key Vault • Log Analytics

Ready for: Real-world hybrid deployments, not just lab experiments.

This post is a practical deep dive into running self‑hosted GitHub Actions runners on Azure Container Apps (ACA). The goal: ephemeral, on‑demand compute that scales up only when there are GitHub workflow jobs in the queue and scales to zero when idle. You’ll see how the resources fit together (Log Analytics, Container Apps environment, Azure Container Registry), how the runner containers register with GitHub, how workflows target these runners, and how KEDA automatically scales job executions based on load.

If you maintain repositories that need custom tooling, access to private networks, or predictable performance characteristics, self‑hosted runners on ACA jobs give you serverless elasticity with infrastructure‑as‑code repeatability.

Key references:

• Jobs in Azure Container Apps: https://learn.microsoft.com/azure/container-apps/jobs?tabs=azure-cli

• Containers in Azure Container Apps (registries, managed identities): https://learn.microsoft.com/azure/container-apps/containers?tabs=bicep

• Tutorial (GitHub pivot): https://learn.microsoft.com/azure/container-apps/tutorial-ci-cd-runners-jobs?tabs=bicep&pivots=container-apps-jobs-self-hosted-ci-cd-github-actions

• KEDA GitHub runner scaler: https://keda.sh/docs/latest/scalers/github-runner/

Project summary

The repo is intentionally split into two experiences:

• README.md is a quick-start guide: copy a parameters file, build an image, run one script, and point a workflow at the labels.

• blog.md (this post) is the design notebook: why the Bicep looks the way it does, why KEDA is wired this way, and what trade-offs I made around identity, networking, and security.

At a resource level, the composed Bicep template brings up everything this pattern needs in one shot: a Log Analytics workspace wired into a Container Apps managed environment, an Azure Container Registry (ACR) with managed identity pull configured, and a virtual network with a delegated subnet and network security group to keep traffic on your own address space. On top of that it defines the Azure Container Apps event‑driven job that runs the GitHub Actions runner image, registers with your repo or organization, and exits when the workflow completes, plus a KEDA github-runner scaler that watches your GitHub queue and decides when to trigger executions. The repo also includes a small container build scaffold (Dockerfile.github, github-actions-runner/entrypoint.sh, and scripts/Build-GitHubRunnerImage.ps1) that packages the upstream runner release (v2.329.0 at https://github.com/actions/runner/releases/tag/v2.329.0) with the extra tooling you are likely to need.

When the deployment finishes, it returns the environment ID, job ID, managed identity principal IDs, and ACR metadata so you can plug those identifiers into dashboards or additional automation without hunting for them in the portal.

Repository structure (relevant parts)

project-github-runner/
├─ Dockerfile.github             # Dockerfile for the GitHub Actions runner image
├─ github-actions-runner/
│  └─ entrypoint.sh              # Container entrypoint configuring the runner
├─ README.md                     # Deployment guide and architecture overview
├─ infra/
│  ├─ parameters.sample.json     # Template for parameter overrides
│  ├─ main.bicep                 # Composes workspace, environment, ACR, and the job
│  ├─ containerapps/             # Bicep modules (job, env, registry)
│  └─ network/
│     └─ vnet.bicep              # Virtual network, delegated subnet, and NSG for Container Apps
└─ scripts/
  ├─ ContainerApps-Deploy-Job.ps1        # Creates Container Apps job via Azure CLI
  ├─ ContainerInit.ps1                   # Optional container init hook to install modules
  ├─ Create-FederatedCredential.ps1      # Adds Entra federated credential for GitHub OIDC
  ├─ Build-GitHubRunnerImage.ps1         # Builds/pushes the Docker image defined in Dockerfile.github
  └─ Deploy-GitHubRunner.ps1             # End-to-end deployment wrapper using Bicep

Architecture overview

At a high level, the moving pieces line up in a pretty natural way. An Azure Monitor Log Analytics workspace captures container logs, scale events, and job execution history at the environment level. That is why infra/main.bicep computes the workspace name from baseName and location and then passes both the workspace ID and a shared key into the managed environment module. A single Container Apps environment then hosts the job and acts as the security and logging boundary for CI workloads—anything that can touch internal build systems or package feeds lives in this environment or its peered VNets.

Network-wise, a dedicated virtual network and delegated subnet isolate the environment, and a network security group lets you enforce egress controls or lock down ingress. This trades a bit of deployment complexity for the ability to keep runners off the public internet. The runner image is pulled from ACR (or another registry), and I default to managed identity authentication so there are no registry passwords or admin credentials in the deployment. The Azure Container Apps job has the system-assigned identity enabled with ACR pull rights and, by default, the deployment also creates and attaches a user-assigned managed identity that you can reuse across deployments or share with other workloads.

Secrets finish the picture. GitHub App metadata (App ID and installation ID) arrives via GitHub environment variables and the private key arrives as an environment secret. The bootstrap pipeline passes those into the Bicep deployment, which copies the PEM into Azure Key Vault and wires a secret reference into the Container Apps job so both the runner bootstrap and KEDA scaler can authenticate without hard-coding secrets in Bicep. On top of that, the KEDA scaler queries GitHub for queued jobs using either PAT or GitHub App credentials; when the queue length exceeds your target, KEDA triggers ACA job executions and each execution runs one ephemeral runner container that exits when the workflow completes.

Flow:

1. A GitHub workflow queues a job targeting your self‑hosted labels.

2. The KEDA scaler polls the GitHub API, scoped to your org/repo and labels, and detects queued work.

3. ACA starts N job executions (bounded by min/max per interval). Each execution creates a pod with the runner container.

4. The runner registers with GitHub, picks up the job, executes steps, and exits.

5. ACA marks the execution complete. With no pending work, subsequent polls result in zero executions and the job scales to zero.

The rest of this post walks through the Bicep and runner image design in more detail, explaining why certain patterns look “heavier” than a minimal sample but pay off in day‑2 operations.

Demo GitHub Actions pipeline

To make the experience tangible, the repository includes .github/workflows/demo-self-hosted-runner.yml. When you dispatch this workflow from the Actions tab it spins up a simple matrix of nine parallel jobs, each targeting the self-hosted and azure-container-apps labels so work naturally lands on the Container Apps runners created by the Bicep deployment. The matrix uses max-parallel: 9 so all jobs can run at once, which forces the KEDA scaler to scale the job up to nine containers (bounded by maxExecutions) and gives you something interesting to watch.

Inside each job, the steps record the runner host name, verify that PowerShell 7.4 is available, and simulate a short workload so the container stays alive long enough for you to observe behavior. When you trigger the workflow, GitHub places nine jobs in the queue (your runnerLabels parameter must match the labels in the workflow), the scaler sees the queue depth (with targetWorkflowQueueLength defaulting to 1), and schedules executions in the Container Apps environment. Each execution registers an ephemeral runner, processes its slice of the matrix, and exits. You can monitor progress with az containerapp job execution list --name <jobName> --resource-group <rg>, drill into individual executions with az containerapp job execution show --name <executionName> --job-name <jobName> --resource-group <rg>, and use Log Analytics to look at job output.

In practice this little pipeline becomes a “smoke test” for the whole setup: it exercises scaling, confirms network access, and gives you telemetry before you trust the pattern with production workloads.

Container image build workflow

The runner image is built locally from Dockerfile.github, which uses the official GitHub Actions runner base image (ghcr.io/actions/actions-runner:2.329.0) and adds an entrypoint script to handle registration. The scripts/Build-GitHubRunnerImage.ps1 PowerShell script simplifies building and pushing the image to your ACR:

./scripts/Build-GitHubRunnerImage.ps1 `
  -ImageTag "$ACR_NAME.azurecr.io/github-actions-runner:2.329.0" `
  -Push

The script wraps docker build/docker push, allowing you to target alternative architectures or versions by adjusting parameters. Authenticate to your registry (for example, az acr login --name $ACR_NAME) before pushing. Because the Bicep deployment provisions the Azure Container Registry and grants the job managed identity AcrPull, update containerImage in your Bicep parameters to reference the new tag and redeploy.

Networking uplift and VNet integration

Enterprise deployments often require private networking, static routing requirements, or traffic inspection. The network/vnet.bicep module provisions a virtual network, delegated subnet, and optional custom NSG rules so the Container Apps environment can attach directly to your address space. During deployment, the main Bicep template passes the subnet resource ID to the environment module, enabling VNet integration.

Key parameters are exposed to keep address planning flexible:

• virtualNetworkAddressPrefix and containerAppsSubnetPrefix define the VNet and infrastructure subnet CIDR blocks.

• platformReservedCidr, platformReservedDnsIp, and dockerBridgeCidr surface the optional networking ranges documented in Networking parameters for Container Apps environments, preventing conflicts with peered VNets.

• internalEnvironment toggles whether the managed environment is created as internal-only, removing the public VIP. See https://learn.microsoft.com/azure/container-apps/networking?tabs=bash#accessibility-level.

By managing the VNet resources in Bicep you can apply Azure Policy, configure diagnostics, and enforce NSG rules consistently. Downstream workloads—build agents, package feeds, artifact stores—can live in the same VNet or attached spokes, enabling end-to-end private networking without exposing the runners to the public internet.

I deliberately stopped short of deploying auxiliary perimeter services (Azure Firewall, Private Endpoints, or private DNS zones) in this repo to keep the focus on the runner pattern itself. Those pieces tend to be very environment‑specific. The VNet module is designed so you can plug those in later without re‑architecting the job.

How GitHub runners work in ACA jobs (end‑to‑end)

1) Resource creation (Bicep)

The main template (infra/main.bicep) composes a few focused modules:

• logAnalytics.bicep provisions a workspace (retention configurable) and returns its IDs.

• managedEnvironment.bicep creates the Container Apps environment and connects it to Log Analytics.

• containerRegistry.bicep creates ACR and assigns AcrPull to a supplied principal.

• githubRunnerJob.bicep defines the event‑driven job (Microsoft.App/jobs) and KEDA scale rules.

The interesting parts are the glue and the identity wiring in main.bicep. For example, runner configuration URLs are normalized up front:

var githubApiUrlNormalized = endsWith(githubApiUrl, '/')
  ? substring(githubApiUrl, 0, max(length(githubApiUrl) - 1, 0))
  : githubApiUrl

var githubServerUrlNormalized = endsWith(githubServerUrl, '/')
  ? substring(githubServerUrl, 0, max(length(githubServerUrl) - 1, 0))
  : githubServerUrl

Normalizing here avoids subtle bugs later (for example double slashes in REST URLs or mismatched hostnames between the runner and the scaler) and keeps the job module simpler. Similarly, the template computes the runner registration URL and token endpoint based on the runnerScope parameter:

var githubRunnerUrl = githubRunnerScope == 'org'
  ? '${githubServerUrlNormalized}/${githubOwner}'
  : (githubRunnerScope == 'ent'
      ? '${githubServerUrlNormalized}/enterprises/${githubOwner}'
      : '${githubServerUrlNormalized}/${githubOwner}/${githubRepo}')

var githubRegistrationTokenApiUrl = githubRunnerScope == 'org'
  ? '${githubApiUrlNormalized}/orgs/${githubOwner}/actions/runners/registration-token'
  : (githubRunnerScope == 'ent'
      ? '${githubApiUrlNormalized}/enterprises/${githubOwner}/actions/runners/registration-token'
      : '${githubApiUrlNormalized}/repos/${githubOwner}/${githubRepo}/actions/runners/registration-token')

This gives you one template that works for repo, org, or enterprise‑scoped runners without changing the job module.

2) Deploying the job

In day‑to‑day use, the deployment flow is straightforward. You create or reuse a resource group and deploy infra/main.bicep with parameters for your GitHub owner and repository (or org scope), the container image you want to use for the runner (an ACR path or external registry), and your scaling preferences such as minExecutions, maxExecutions, pollingInterval, and targetWorkflowQueueLength. Network and identity parameters control how the job reaches ACR and any internal resources your builds might need. The deployment returns the job and environment IDs, and logs start flowing to Log Analytics automatically.

To keep long‑lived credentials out of source control, the GitHub Actions workflow reads GH_APP_PRIVATE_KEY from an environment secret (see https://docs.github.com/actions/security-guides/using-secrets-in-github-actions). The Bicep deployment writes that value into Azure Key Vault and assigns Key Vault Secrets User to the job identity, so at runtime the Container Apps secret can reference the vault URI and both the runner entrypoint and KEDA scaler can mint JWTs and installation tokens following https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.

The KEDA scaler only needs a handful of GitHub details to do its work: who owns the workloads (owner), how they are scoped (runnerScope as repo, org, or ent), which repositories to watch, which labels to honor, and how aggressively to scale (targetWorkflowQueueLength and pollingInterval). The job module receives these via parameters such as runnerScope, githubRepositories, and scaleRunnerLabels, so you can tune behavior just by changing parameter values instead of touching the module code.

3) Runner bootstrap and registration with GitHub

When a job execution starts, ACA launches the runner container with environment variables and secrets provided by Bicep. The runner process performs the following steps:

1. Exchanges the GitHub App installation token or PAT for a short‑lived registration token via GitHub REST: POST /repos/{owner}/{repo}/actions/runners/registration-token (or org/ent variant). The job template includes REGISTRATION_TOKEN_API_URL and GH_URL/repo for clarity.

1. Configures the runner with your labels and repository/organization context.

2. Registers the runner; it shows up as an online self‑hosted runner in GitHub.

3. Waits for a workflow job assignment; when received, executes all steps.

4. On completion, the container exits. Ephemeral patterns typically remove the runner registration automatically on shutdown.

This lifecycle ensures no idle, permanently registered VMs—each execution is purpose‑built and disposed.

4) Using the runners in GitHub Actions

In your workflow YAML, you point jobs at these runners simply by targeting the right labels:

runs-on: [self-hosted, azure-container-apps]

You can add repo, org, or language-specific labels—dotnet, arm64, build-tools, and so on—to steer jobs toward particular images or toolchains. From GitHub’s perspective, jobs just queue until a matching self‑hosted runner comes online; behind the scenes, the KEDA scaler is the component that responds to that queue depth and triggers ACA job executions. Concurrency and parallelism end up being a combination of your workflow’s matrix/strategy choices in GitHub, the KEDA scaling parameters (min/max executions per polling interval), and the container resources (CPU/memory) and job settings like parallelism and replicaCompletionCount if you ever decide to run multiple containers per execution. Most of the time, the simple 1:1 mapping between a job execution and a single runner container works well.

5) KEDA scaling behavior

The github-runner scaler periodically queries the GitHub API to estimate queued work for the scope and labels you configured. Whenever the queue length meets or exceeds targetWorkflowQueueLength, KEDA triggers job executions up to maxExecutions for that polling interval. There are a couple of practical tuning knobs here. A lower pollingInterval reduces start latency at the cost of more API calls, so it is worth enabling ETags (enableEtags=true) to ease rate‑limit pressure. Narrowing the scope with explicit repos lists and well‑chosen labels both improves responsiveness and avoids over‑scaling generic runners for jobs that really need specialized images. Finally, remember that PATs have lower rate limits than GitHub Apps, so if you expect high throughput or many repositories, GitHub App auth is usually the better choice. For full details, see the KEDA scaler docs at https://keda.sh/docs/latest/scalers/github-runner/.

Permissions, identity, and secrets

This design leans hard on managed identities and GitHub Apps so you do not have to scatter long‑lived secrets across scripts and parameter files. For registry access, the job pulls from ACR using a managed identity rather than a username and password: you assign AcrPull to the job’s user‑assigned identity and configure the registry identity as either the UAMI resource ID or system for system‑assigned identity (see https://learn.microsoft.com/azure/container-apps/containers?tabs=bicep#managed-identity-with-azure-container-registry).

On the GitHub side, the recommended path is to use a GitHub App, not a PAT. The environment’s GH_APP_ID and GH_APP_INSTALLATION_ID variables and the GH_APP_PRIVATE_KEY secret supply the app metadata and PEM key to the bootstrap workflow (per https://docs.github.com/actions/security-guides/using-secrets-in-github-actions). The workflow passes these values into the Bicep deployment, which persists the key in Azure Key Vault and grants the job identity Key Vault Secrets User. At runtime the runner and scaler can mint JWTs and installation tokens on demand (see https://learn.microsoft.com/en-us/azure/container-apps/manage-secrets?tabs=arm-bicep and https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). A minimal‑scope PAT remains supported as a fallback if you need it, but the intent is that most deployments never have to rely on it.

Scope selection matters as well. When you use a personal GitHub user (for example broberts23) as githubOwner, you should set githubRunnerScope to repo so the scaler and runner use /repos/{owner}/{repo} endpoints and the GitHub App only needs Repository → Administration (Read & write) on that repo. Reserve githubRunnerScope: "org" for situations where githubOwner is a real GitHub Organization, /orgs/{org} and /orgs/{org}/repos resolve successfully, and the app is installed on that organization with Organization → Self-hosted runners (Read & write).

GitHub’s own REST reference is very explicit about what permissions are required for the various registration endpoints, which is summarized in the table below.

GitHub App permission matrix:

These requirements come directly from the GitHub REST reference (see https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-a-registration-token-for-a-repository and https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-a-registration-token-for-an-organization). If the installation token lacks the relevant permission or repository access, the API returns 403 Resource not accessible by integration per https://docs.github.com/en/rest/using-the-rest-api/troubleshooting#resource-not-accessible. Whenever you change app permissions or repository selections, it is worth re‑authorizing the installation so GitHub issues tokens with the expanded scope.

Beyond these specifics, the security posture is intentionally conservative: there are no long‑lived runner nodes (job executions are ephemeral, which reduces standing privilege and image drift), images are versioned and tags pinned, and secrets never live directly in parameter files or scripts. Instead, you retrieve sensitive values locally with SecretManagement or GitHub environments, let the deployment write them into Key Vault, and rely on secret references at runtime while being careful not to log secret material.

Observability and operations

Once everything is deployed, most of your day‑to‑day operational work happens in Log Analytics and through the Container Apps APIs. Container stdout/stderr and scale events flow into the workspace automatically, so you can use Kusto queries to investigate runner bootstrap behavior and job logs. For a quick health check, az containerapp job execution list (or the Azure portal) shows you recent executions and statuses, and you can drill into specific runs when something fails.

Because the pattern uses event‑driven jobs, cost tends to track actual work closely—you pay while containers run and effectively nothing when there is no queued work. It is still worth keeping an eye on image hygiene: keep runner images minimal, refresh them regularly, and, if your builds need large toolchains, consider splitting into multiple label‑targeted images so not every job has to carry every dependency.

Troubleshooting GitHub App 403 responses

If you ever run into 403 Resource not accessible by integration responses from GitHub, the logs from github-actions-runner/entrypoint.sh are your first stop. The script logs both the HTTP status code and response body whenever GitHub rejects a request, so instead of a silent curl failure you will see something like GitHub API POST ...registration-token failed (403): {"message":"Resource not accessible by integration"...} along with whatever additional detail GitHub provides.

From there, work through a short checklist. First, confirm that the GitHub App’s permissions align with the githubRunnerScope you chose, using the permission matrix above as a guide and the REST docs for the exact endpoint you are calling (for example https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-a-registration-token-for-a-repository). Next, look at the X-Accepted-GitHub-Permissions response header; GitHub includes it when a permission is missing, and it tells you exactly what the API expected (see https://docs.github.com/en/rest/using-the-rest-api/troubleshooting#resource-not-accessible). Finally, open the GitHub App installation page and make sure every repository listed in githubRunnerRepositories is actually selected (or that you have chosen “All repositories”). After changing either permissions or repository selection, re‑authorize the installation so new tokens pick up the broadened scope.

Finally, verify that the GH_APP_PRIVATE_KEY secret contains the full PEM content. When looking at the secret in Azure Key Vault, it should be in the form:

-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----\n

Another tip is to use Get-AzSecret to pull the secret locally and confirm it has the expected format:

az keyvault secret show \
  --vault-name <kv-name> \
  --name github-app-key \
  --query value \
  --output tsv > /tmp/app-key.txt

cat /tmp/app-key.txt

Then use openssl to validate the PEM:

openssl rsa -in ./github-app-private-key.pem -check

When the scaler has successfully authenticated with GitHub, you will see the ScaledJob is ready for scaling event log in Log Analystics

Implementation details in this repo

The composed infra/main.bicep surface area is intentionally small but flexible. You tell it which image to run and how much CPU/memory it should have, provide GitHub details like githubOwner, githubRepo, and runnerLabels, and then choose your scaling behavior with parameters such as minExecutions, maxExecutions, pollingInterval, and targetWorkflowQueueLength. Additional knobs control how the scaler talks to GitHub (githubApiUrl, githubRunnerScope, githubRunnerRepositories, disableDefaultRunnerLabels, matchUnlabeledRunnerJobs, enableGithubEtags, and additionalScaleRuleAuth) and how the job authenticates to Azure resources (acrName, userAssignedIdentityId).

The containerapps/githubRunnerJob.bicep module takes those inputs and renders the actual job resource, including the rules: [ { type: 'github-runner', metadata, auth } ] block for KEDA. That split keeps the job specification clean and auditable while still giving you the levers you need at deployment time.

GitHub Actions infrastructure bootstrap workflow

The repository includes .github/workflows/bootstrap-infra.yml, a GitHub Actions pipeline that builds the runner image and deploys the Bicep template end to end.

High-level behavior:

• Trigger and inputs: The workflow runs on workflow_dispatch with inputs for environment (dev or prod), an optional imageTagSuffix, and an optional parametersFile override.

• Environment resolution: The Resolve deployment configuration step maps the logical environment to concrete values:

  • dev → rg-github-runner-dev, eastus, ghrunnerdevacr, parameters file project-github-runner/infra/parameters.dev.json.

  • prod → rg-github-runner-prod, eastus, ghrunnerprodacr, parameters file project-github-runner/infra/parameters.prod.json.

  • If parametersFile is provided, it overrides the default; the step fails fast if the file does not exist.

• Image tagging: The same step computes a container image tag of the form <acrName>.azurecr.io/github-actions-runner:<suffix>, where <suffix> defaults to v${{ github.run_number }} unless overridden by imageTagSuffix.

Deployment sequence in the job:

1. Checkout: actions/checkout@v4 pulls the repo so Docker and Bicep can see project-github-runner.

2. Azure login (OIDC): azure/login@v2 authenticates to Azure using federated credentials, driven by AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_SUBSCRIPTION_ID in GitHub secrets. This follows the guidance in Deploy Bicep with GitHub Actions.

3. Resource group creation: azure/cli@v2 runs az group create to ensure the target resource group exists (see az group create).

4. Prepare infrastructure deployment: An initial azure/bicep-deploy@v2 step (Deploy infrastructure (Bicep - prepare)) runs against infra/main.bicep with the resolved parameters file and overrides for:

   • containerImage: the computed ACR image tag.

   • acrName: the resolved registry name.

   • githubAppApplicationId, githubAppInstallationId, githubAppPrivateKey: sourced from environment variables GH_APP_ID, GH_APP_INSTALLATION_ID, and secret GH_APP_PRIVATE_KEY respectively. This step is continue-on-error: true so the image build can proceed even if the first deployment attempt fails (for example, on a cold start).

5. ACR login: A plain az acr login signs the Docker client into the target ACR so the subsequent build can push the image.

6. Build and push image: docker/setup-buildx-action@v3 prepares Buildx, and docker/build-push-action@v6 builds project-github-runner/Dockerfile.github with context project-github-runner and pushes it to the tag computed earlier.

7. Finalize infrastructure deployment: A second azure/bicep-deploy@v2 step reruns the deployment of infra/main.bicep with the same parameters file and overrides, guaranteeing that the Container Apps job uses the freshly pushed image tag.

8. Summary: The final step appends a summary to the GitHub Actions job log containing the environment, resource group, image tag, and the Container Apps job and environment IDs returned by the Bicep deployment.

Required GitHub configuration for the workflow:

• Azure OIDC: Secrets AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID for federated authentication.

• GitHub App metadata: Environment variables GH_APP_ID and GH_APP_INSTALLATION_ID (environment-level vars in GitHub) supplying the GitHub App ID and installation ID; see Authenticating as a GitHub App installation for ways to discover the installation ID.

• GitHub App private key: Environment secret GH_APP_PRIVATE_KEY, generated from the GitHub App settings per Managing private keys for GitHub Apps. The Bicep deployment writes this value into Azure Key Vault so the job and KEDA scaler can authenticate without embedding secrets in templates.

• Optional PAT: A repository secret such as GITHUB_PAT_RUNNER remains supported for PAT-based deployments when you do not want to (or cannot) use a GitHub App.

When dispatching manually you can override the parameters file (for example project-github-runner/infra/parameters.prod.json for a production deployment) or supply a custom image tag suffix; the Resolve deployment configuration step ensures the final image tag and parameter file are consistent with the chosen environment.

Example flow (putting it all together)

In a typical run, you deploy the Bicep template to your resource group with the parameters that describe your environment, GitHub owner/repository, and scaling preferences. Once the deployment completes, you confirm that the Container Apps environment and job exist and that the job template has the expected environment variables and secret wiring. You then point a GitHub workflow at runs-on: [self-hosted, azure-container-apps, <your-labels>], matching <your-labels> to what you configured on the runner.

From there, the experience is pleasantly boring: you queue a workflow, KEDA notices the queued job within roughly pollingInterval seconds, and ACA starts the necessary job executions. Runners register, process their assigned work, and exit. When there is no more work in the queue, subsequent polls result in zero executions and the job scales down to zero again.

Troubleshooting tips

• No job executions: Verify scaler metadata (owner/scope/repos), confirm the GitHub App secret name in scaleRuleAuth aligns with the Key Vault-backed secretRef, and ensure the job identity retains Key Vault Secrets User. Labels in your workflow must match the runner configuration.

• Image pull errors: Check ACR AcrPull assignment and that the registries.identity matches the enabled identity. Confirm ACR “authentication as ARM” status when using MI pulls.

• Rate limiting: Reduce API calls via more selective repos, enableEtags, or switch to GitHub App auth.

• Runner not registering: Confirm the container env includes REGISTRATION_TOKEN_API_URL, repository URL, APP_ID, and APP_INSTALLATION_ID, and that the Key Vault reference can resolve the private key (review logs for secret retrieval errors). If you revert to PAT fallback, regenerate the PAT and verify network egress to https://api.github.com.

Conclusion

This project now represents a complete, opinionated pattern for running GitHub Actions workloads on Azure Container Apps jobs:

• Infrastructure as code: A single composed Bicep template (infra/main.bicep) stands up the Container Apps environment, job, virtual network, Log Analytics, ACR, managed identities, and KEDA github-runner scaler with environment-specific parameter files.

• Hardened runner image: Dockerfile.github builds on the official GitHub Actions runner image and layers in PowerShell 7.4, Azure CLI, Bicep, and Az/Microsoft.Graph modules so typical cloud build/test/deploy pipelines work out of the box.

• GitHub App–first authentication: The default path uses a GitHub App with narrowly scoped permissions, Key Vault–backed private key storage, and a KEDA scaler that authenticates via the same app; PAT-based auth remains available as a fallback.

• Automated bootstrap workflow: .github/workflows/bootstrap-infra.yml ties everything together—building and pushing the runner image, deploying the Bicep template with the correct tag and GitHub App metadata, and emitting IDs you can plug into downstream automation.

• Ephemeral, scalable execution: Runners are created per job execution, register just long enough to process a workflow, and then exit. KEDA scales executions up and down based on queue depth so you only pay for active work while avoiding long-lived build agents.

Taken together, the templates, scripts, and workflows in this repository give you a reusable starting point for production-ready self‑hosted runners: auditable, parameterized, and easy to adapt to additional environments, images, or GitHub organizations as your CI footprint grows. 🚀

References

• My GitHub Repo: broberts23/vsCode/project-github-runner

• Jobs in Azure Container Apps: https://learn.microsoft.com/azure/container-apps/jobs?tabs=azure-cli

• Containers in Azure Container Apps (registries, MI): https://learn.microsoft.com/azure/container-apps/containers?tabs=bicep

• Azure Container Apps environments (logs): https://learn.microsoft.com/azure/container-apps/environment?tabs=bicep#logs

• Monitor logs in Azure Container Apps with Log Analytics: https://learn.microsoft.com/azure/container-apps/log-monitoring?tabs=bash

• View log streams in Azure Container Apps: https://learn.microsoft.com/azure/container-apps/log-streaming?tabs=bash

• Tutorial: GitHub Actions runners on ACA jobs: https://learn.microsoft.com/azure/container-apps/tutorial-ci-cd-runners-jobs?tabs=bicep&pivots=container-apps-jobs-self-hosted-ci-cd-github-actions

• KEDA GitHub runner scaler: https://keda.sh/docs/latest/scalers/github-runner/

This project demonstrates an end-to-end ephemeral pull request (PR) environment pattern using:

• Microsoft Graph Bicep to provision an application, service principal, security group, test accounts, custom OAuth2 permission scopes, and an application role.

• Azure resource deployment (Key Vault with RBAC, Storage, App Service Plan, Web App) as disposable per‑PR infrastructure.

• .NET 8 Minimal API with standardized v2 JwtBearer authentication accepting both identifier URI and clientId audiences.

• GitHub Actions OIDC workload identity federation (no client secrets) to deploy and test.

• PowerShell automation for post‑deploy Graph operations (federated credential, app role assignment, ephemeral test users lifecycle).

• Smoke tests validating Web App (service) readiness, role claim propagation, authenticated access, and data-plane RBAC for Key Vault and Storage.

The design focus here is NOT deep functional testing of business endpoints, although the smoke tests could easily be extended to include more comprehensive API validation. Instead, it highlights how identity artifacts (scopes, roles, group membership, users) can be created and wired programmatically as part of an ephemeral environment. The only required application tests are:

• A role-gated /healthz endpoint (requires Swagger.Admin application role) proving role claim emission and authorization works.

• An authenticated /health endpoint (accepts any valid v2 token for the application) proving basic bearer auth wiring works.

Swagger/UI endpoints and scope-gated API surface are intentionally optional and can be explored manually with the generated test identities while a PR is open.

Project summary

This repository delivers a per‑PR ephemeral environment pattern that automates identity artifacts (application, service principal, scopes, roles, and a tester group) alongside disposable Azure resources (Key Vault, Storage, Web App). It standardizes on v2 Graph tokens for the Minimal API using a single JwtBearer scheme (valid audiences include the identifier URI and clientId). CI provisions the environment, deploys the API, runs smoke tests against the /healthz (role-gated) and /health (any authenticated token), and preserves results as artifacts. Resources remain until a PR is labeled destroy, at which point a gated tear-down removes the Graph objects and the Azure resource group.

Repository structure

project-bicep-graph/
  bicepconfig.json
  blog.md
  README.md
  infra/
    main.bicep
    modules/
      appInfra.bicep
      identity.bicep
  scripts/
    Assign-AppRoleToGroup.ps1
    Cleanup-GraphEphemeral.ps1
    Create-TestUsers.ps1
    Delete-TestUsers.ps1
    GraphFederation.ps1
    SmokeTests.ps1
  src/
    WebApi/
      appsettings.json
      Program.cs
      WebApi.csproj
  tests/
    SmokeTests.Tests.ps1

Scenarios / use cases

Below are practical, real-world scenarios where this pattern adds value:

• Feature-branch validation environments

  • Spin up a complete stack per PR, run smoke tests, and keep the environment available for iterative commits until explicitly destroyed.

• Identity wiring and RBAC regression checks

  • Prove role claim propagation (Swagger.Admin → /healthz) and audience/issuer correctness (/health) before merge; catch config drift early.

• Contract and SDK change verification

  • Validate changes to Minimal API endpoints or OpenAPI contracts with generated clients; exercise Swagger.Read policy gating (optionally) without impacting shared envs.

• Dependency upgrade confidence

  • Test .NET minor/patch upgrades, App Service runtime updates, Az CLI/PowerShell module bumps, and Graph API changes in isolation per PR.

• Cross-service integration tests

  • Verify Key Vault and Storage data‑plane RBAC using the workload identity; ensure least‑privilege roles still allow the required operations.

• Secrets rotation rehearsal

  • Rehearse secret or certificate rotation patterns (paired with a JIT RBAC activation workflow) and verify the app consumes new versions without downtime.

• Conditional Access and role policy previews

  • Trial tenant policy changes that may affect service‑to‑service flows; confirm protected endpoints still authorize correctly with v2 tokens.

• Multi-tenant app hardening

  • Exercise deterministic identifier URIs and dual accepted audiences (audience + clientId) to ensure consistent v2 auth in multi‑tenant setups.

• Performance smoke and cold‑start checks

  • Measure first‑hit latency and basic throughput after deploy; compare over time as dependencies change.

• Chaos/resiliency drills (lightweight)

  • Intentionally deny KV or Storage access (temporary RBAC change) to confirm the app and pipeline report actionable errors.

• PR demos and review sandboxes

  • Provide reviewers with test users and a safe, isolated environment for manual exploration during the review window.

• Bug reproduction and fix validation

  • Reproduce production issues in a throwaway env with the same identity wiring and app settings; validate fixes without risking shared dev/test.

• Bicep module canary testing

  • Validate changes to shared modules (identity/infra) behind a PR; confirm outputs, RBAC assignments, and app settings are correct end‑to‑end.

• Workflow and OIDC trust changes

  • Safely evolve GitHub Actions workflow steps (OIDC, artifact handling, smoke steps) and verify behavior in isolation before rolling to other repos.

• Testing team regression suites

  • Provide QA teams with ephemeral test accounts and a disposable environment to run regression test suites; each PR gets fresh test users with known credentials and role assignments, ensuring repeatable and isolated test runs.

Architecture overview

Components

• Identity (Entra/Microsoft Graph Bicep beta): application, service principal, OAuth2 scopes (Swagger.Read/Write), and an app role (Swagger.Admin); tester security group.

• Azure resources: Key Vault (RBAC), Storage (V2), App Service Plan (B1), Web App with app settings for AzureAd__TenantId, AzureAd__Audience, and AzureAd__ClientId.

• Application: .NET 8 Minimal API; single v2 JwtBearer scheme; policies for SwaggerAdmin, SwaggerRead, and AnyAuthenticated.

• Automation: PowerShell scripts for role assignment and test user lifecycle; GitHub Actions workflow for provision → smoke-tests → destroy.

Flow (high level)

1. PR opened/reopened → OIDC login → Bicep deploys identity + infra → Web API published via zip deploy → role assigned to tester group; optional test users created.

2. Smoke tests acquire a v2 token via <identifierUri>/.default (fallback to <clientId>/.default), call /healthz with the admin token and /health with an authenticated token, and validate KV/Storage access.

3. Artifacts (env-outputs.json, test-users.json, smoke-results.json) are uploaded; tokens are not decoded or persisted in results.

4. When the PR is labeled destroy, CI deletes test users, Graph objects (assignments, group, SP, app), and the resource group.

Goals vs Non‑Goals

Implementation

Identity Layer (Bicep Graph Beta)

• Application + Service Principal created via Microsoft.Graph/*@beta resources.

• Application identifier URI (audience) declared as api://pr-<prNumber>-<uniqueSuffix> deterministically; output as appAudience for token acquisition and API configuration.

• Two OAuth2 permission scopes defined: Swagger.Read, Swagger.Write (deterministic IDs via guid() seeding).

• One application role Swagger.Admin (allowed for User & Application principals) with deterministic ID.

• Security group grp-<pr>-<suffix>-testers created unconditionally for ephemeral test accounts; app is configured with groupMembershipClaims: SecurityGroup so role/group claims flow into user tokens (if requested interactively later).

• Outputs: appId (clientId), appObjectId, servicePrincipalObjectId, appAudience (identifier URI), scope IDs, role ID, group display name and objectId.

Infrastructure Layer

• Storage Account (Standard_LRS, StorageV2 kind) and Key Vault (RBAC permission model, soft delete enabled) deployed.

• Web App (Minimal API .NET 8) + Basic App Service Plan (B1 tier).

• RBAC role assignments:

  • Service principal (API) granted "Key Vault Secrets User" on Key Vault.

  • GitHub runner service principal (OIDC workload identity) optionally granted "Key Vault Secrets User" for smoke test access.

• App settings: AzureAd__TenantId (subscription tenant), AzureAd__Audience (app audience URI from Bicep output), AzureAd__ClientId (application appId for secondary accepted audience).

Application (Minimal API) — Standardized v2 Authentication

• Endpoints:

  • /healthz — role-protected heartbeat; requires Swagger.Admin role to authorize (verifies role assignment propagation in CI).

  • /health — requires any authenticated bearer token issued by the tenant for this application (no scope enforcement in CI).

  • /api/mock — requires Swagger.Read scope (demonstrates scope-based policy; not exercised automatically).

  • /swagger redirect — protected by Swagger.Admin role (manual exploration only).

• Authentication pipeline (single JWT Bearer scheme) configured via environment variables: AzureAd__TenantId, AzureAd__Audience, AzureAd__ClientId.

  • Uses v2 authority: https://login.microsoftonline.com/<tenantId>/v2.0.

  • Accepts either the identifier URI (AzureAd__Audience) or the clientId as valid audience (ValidAudiences = [ audience, clientId ]).

  • Explicit issuer validation (https://login.microsoftonline.com/<tenantId>/v2.0) prevents cross‑version token mismatches.

  • Policies:

    • SwaggerAdmin — role claim (roles or http://schemas.microsoft.com/ws/2008/06/identity/claims/role) contains Swagger.Admin.

    • SwaggerRead — scope claim (scp) contains Swagger.Read.

    • AnyAuthenticated — generic authenticated user (used for /health).

• Rationale for v2-only standardization: avoids issuer/audience ambiguity between v1 (https://sts.windows.net/...) and v2 (https://login.microsoftonline.com/...), simplifies smoke testing token acquisition, and ensures consistent claim shape (e.g., consolidated scp multi‑space scope string).

Automation Scripts (scripts/)

• Assign-AppRoleToGroup.ps1 — Assigns the Swagger.Admin app role to the tester group using Graph REST API. Supports group lookup by display name or direct objectId (preferred). Safely handles pagination and property existence checks to avoid Graph API filter limitations. Also assigns application permission to the runner SP if provided.

• Create-TestUsers.ps1 — Generates ephemeral test users with aliasing pattern pr<PR_NUMBER>tester<index><6hex>, sets SecureString passwords, adds each user to the tester group via Graph /members/$ref, outputs JSON with plaintext passwords for artifact (demo only; production should use Key Vault or avoid password-based auth).

• Delete-TestUsers.ps1 — Cleans up users matching the PR prefix heuristic (mailNickname, displayName). Deletes users from directory; group membership implicitly removed.

• Cleanup-GraphEphemeral.ps1 — Removes app role assignments (group + runner SP principals), deletes security group, service principal, and application. Uses client-side filtering to work around Graph filter limitations on relationship endpoints. Outputs JSON summary of deletion operations (type, id, status, error).

• SmokeTests.ps1 — Dot-sourceable PowerShell module; Invoke-EphemeralSmokeTests function validates environment context, Key Vault access (Get-AzKeyVaultSecret), Storage access (Get-AzStorageAccountKey), and API endpoints (/healthz with admin role token, /health with any app token). Returns structured object; captures HTTP status codes for diagnostics and gracefully handles missing properties (stores null/error objects) under StrictMode.

GitHub Actions Workflow (.github/workflows/ephemeral-env.yml)

• Jobs: provision → smoke-tests → destroy.

• Provision: Checks out repo; logs in via OIDC; resolves runner service principal objectId; creates resource group; deploys Bicep (identity + infrastructure); builds and publishes .NET 8 Minimal API; zips and deploys to App Service; assigns Swagger.Admin app role to tester group; creates ephemeral test users; uploads artifacts.

• Smoke Tests: Downloads infra outputs; acquires a v2 access token using <identifierUri>/.default (fallback to <clientId>/.default if needed) ensuring correct issuer/audience; sources SmokeTests.ps1 and runs Invoke-EphemeralSmokeTests to validate /healthz (role-gated via admin token), /health (any authenticated token), Key Vault access (RBAC), and Storage access (RBAC); generates a concise summary (auth/config and API/resource checks); outputs structured JSON and preserves artifacts even on failure. Tokens are not printed or decoded in logs/artifacts.

• Destroy: Triggered only when destroy label is applied to the PR; downloads artifacts from provision job; logs in via OIDC; deletes test users; cleans up Graph objects (app role assignments, group, service principal, application); deletes resource group asynchronously.

• Artifacts: env-outputs.json (Bicep outputs), test-users.json (ephemeral account credentials), smoke-results.json (test results structure).

• Triggers & Conditions:

  • Runs on PR opened, reopened, and labeled events.

  • provision and smoke-tests run only on PR open/reopen (github.event.action != 'labeled').

  • destroy runs only when "destroy" label is added (github.event.action == 'labeled' && contains(...labels...*.name, 'destroy')).

• PR Merge Protection: Configure branch protection rules in GitHub repository settings to require provision and smoke-tests status checks to pass before merging. This prevents merging until the pipeline completes successfully, ensuring resources are validated before integration. The pipeline can run independently of merge; resources persist until the destroy label is applied.

Clarification: App Roles & Swagger Scopes Are Demonstrative

The project intentionally provisions OAuth2 scopes and an app role to show how they can be:

1. Declared with deterministic GUIDs in Bicep (ensuring stability across redeployment so consent/assignments remain valid), and

2. Assigned programmatically (role to group) post-deployment.

However:

• CI pipelines do NOT depend on or validate Swagger.Read / Swagger.Write scopes today (scope policy is illustrative).

• The /api/mock and /swagger endpoints are not part of the automated testing and are merely placeholders to demonstrate how the testing framework could be used.

• Test users exist so a human reviewer (during the PR window) could optionally sign in and verify roles/scopes manually. They could also be used for user-based delegated claim auth validation.

Automated testing focuses solely on:

• Role claim propagation for Swagger.Admin (/healthz access).

• Basic bearer auth wiring (/health access) with v2 tokens.

Ephemeral Identity Lifecycle

• Groups are always created (no conditional logic) simplifying downstream steps.

• Test users are generated with prefix pr<PR_NUMBER>tester and appended random hex for uniqueness.

• Users added to tester group enabling potential role claim emission if interactive delegated tokens are later acquired manually.

• Tear down removes users and groups

Security and governance considerations

• Authentication: Use GitHub Actions OIDC for CI login (no secrets). Azure OIDC guidance: https://learn.microsoft.com/azure/developer/github/connect-from-azure-openid-connect

• Token hygiene: Tokens are used only in-memory to call protected endpoints; token contents are not written to smoke-results.json or job summaries.

• Least privilege: Prefer Key Vault Secrets User over broader roles; scope assignments to only what smoke tests require.

• RBAC model: Key Vault uses the RBAC permission model (enableRbacAuthorization=true) to align with identity-first, secretless automation.

• Governance: Protect main branches by requiring provision and smoke-tests checks. Use Destroy label to gate cleanup and preserve artifacts for audit.

• Secrets: Test user passwords are demo-only; in production, store in Key Vault or avoid password-based flows entirely.

• Preview note: Microsoft Graph Bicep beta types are subject to change; pin tooling versions and validate in a test tenant first.

Demo / walk-through — end-to-end PR flow

1. Open or reopen a PR.

   • CI logs into Azure via OIDC and deploys Bicep (identity + infra).

   • Builds and zips the Minimal API, deploys to the Web App.

   • Assigns Swagger.Admin app role to the tester group; optionally creates ephemeral test users and uploads artifacts.

2. Smoke tests run.

   • Acquire a v2 token for <identifierUri>/.default (fallback to <clientId>/.default).

   • Call /healthz with the admin token; call /health with an authenticated token.

   • Validate Key Vault and Storage access via Azure AD; upload smoke-results.json (no token contents).

3. Review results in the PR summary and artifacts. Merge when checks pass.

3. Apply the Destroy label when you’re done.

   • CI deletes test users, revokes app role assignments, deletes the tester group, service principal, application, and the resource group.\

Potential Future Enhancements

• Introduce TTL scan job to clean orphaned PR resource groups/users if a workflow run is interrupted or "Destroy" label is never applied.

• Encrypt or secret-manage test user credentials (Key Vault + GitHub OIDC retrieval) for improved hygiene; avoid emitting plaintext to artifacts.

• Pester unit tests for PowerShell scripts (Mock Graph calls, test error paths).

• Conditional destroy (not just label-driven) to clean up on PR merge/close as fallback.

Conclusion

This project emphasizes identity resource automation (app, SP, scopes, roles, group, users) and ephemeral infrastructure rather than broad functional API test coverage. The minimal smoke test (/healthz + authenticated /health) gives just enough validation that identity wiring and deployment succeeded. Everything else—the Swagger-related scopes, role policies, and test users—serves as demonstrative scaffolding that reviewers can manually exercise during a PR’s lifetime.

Key References

• Graph app/service principal Bicep (beta): https://learn.microsoft.com/graph/templates/bicep/reference/applications?view=graph-bicep-beta

• Azure OIDC federation (GitHub): https://learn.microsoft.com/azure/developer/github/connect-from-azure-openid-connect

• Access tokens & claims: https://learn.microsoft.com/azure/active-directory/develop/access-tokens

• Key Vault RBAC: https://learn.microsoft.com/azure/key-vault/general/rbac-guide

This post was born from the idea of, "gee I wonder if you could create a Just-In-Time (JIT) privileged access workflow using GitHub Actions?" After some experimentation and much debugging, the answer is yes 😆 — and the resulting pattern is a powerful way to give automation identities just‑enough, just‑in‑time access to perform high‑value, sensitive tasks while preserving auditability and minimizing standing privilege.

This post demonstrates a practical, secure pattern for integrating PIM-like (Privileged Identity Management) functionality into a CI/CD pipeline so that automation — for example, a GitHub Actions runner — can request, use, and then release elevated privileges in a repeatable, auditable way.

Traditional Entra ID Privileged Identity Manged (PIM) activation is useful for ad-hoc human tasks, but they aren't supported for Workload Identities (at the time of writing). A programmatic PIM activation flow using Microsoft Graph and identity-first automation brings several tangible benefits:

• Repeatability and reproducibility: the activation → perform → revoke sequence is defined as code and can be replayed across tenants and environments.

• CI/CD integration: pipelines can request just‑in‑time privileges for a specific deployment run and attach PR/build metadata for clear traceability.

• Principle of least privilege: request the smallest role and shortest duration necessary for the job instead of maintaining standing privileges.

• Policy-as-code and testability: activation flows can be reviewed in pull requests, linted, and run through CI tests before applying changes to production.

• Audit and compliance: workflows produce machine-readable activation records that can be stored with build artifacts or forwarded to SIEM for longer retention.

• Faster recovery and consistent rollback: automation can detect activation failures and run deterministic rollback or remediation flows.

This repository contains a working scaffold that illustrates the pattern: PowerShell modules that uses Graph/Azure authentication patterns, a small wrapper script to request activation's from a runner, and a GitHub Actions workflow that demonstrates an approval-gated activation.

Project summary

The implementation in this repository is geared toward CI-driven automation (GitHub Actions) and contains a few pragmatic decisions you'll see reflected throughout the module and workflow:

• Automation-first JIT: for non-human actors (managed identities or OIDC workload identities) the flow creates a temporary, scoped Azure RBAC assignment, performs the privileged operation, then removes the assignment immediately—capturing structured metadata (vault, rotated secrets, timestamps) for audit and traceability.

I’ve covered using OIDC to authenticate Github to Azure in depth in previous blogs. You can find more information on how to set up OIDC authentication in parts 4 and 5 of Azure MLOps Challenge Blog

• Vault‑wide secret rotation: secret rotation is implemented at the vault level. Set-PimKeyVaultSecret enumerates all secrets in a vault with Get-AzKeyVaultSecret -VaultName, rotates each secret with Set-AzKeyVaultSecret and returns an array of rotation result objects (vault, secret, rotatedAt, secretVersion) so CI can act on and report every change.

• Clear CI reporting: the module includes Write-PimSecretSummary, which appends a compact Markdown table of rotated secrets to the file indicated by GITHUB_STEP_SUMMARY so runs that perform rotations display a readable summary in the Actions UI.

• Robust RBAC cleanup: removal code was hardened to use supported Remove-AzRoleAssignment parameter sets (preferring -InputObject and falling back to the objectId+roleDefinitionId+scope set) and to defensively handle differences in PSRoleAssignment object shapes across Az versions.

• Quiet, predictable CI logs: module imports of Az.* are performed with verbose output suppressed (temporary $VerbosePreference change plus -Verbose:$false) so the Actions log focuses on the steps and results rather than import chatter.

• Caller ergonomics: lifecycle functions and the run script return machine‑friendly objects and were updated to accept the multi‑secret rotation return shape so downstream jobs and artifact writers can consume rotation metadata programmatically.

Read on for how the pieces fit together and how to validate the flow in a test subscription.

Repository structure

Key folders and files and how they fit together (paths relative to the repository root):

• project-jit-pim/scripts/

  • project-jit-pim/scripts/PimAutomation.psm1 — PowerShell 7.4 module that encapsulates Graph and RBAC logic. Key functions:

    • Get-GraphAccessToken — prefers Azure CLI token when available; supports interactive Graph login in dev.

    • Connect-PimGraph — normalizes Graph connection with the token.

    • Invoke-PimGraphRequest — Graph v1.0/beta compatibility wrapper for GET/POST/PATCH/DELETE.

      • Set-PimAzContext — establishes Az PowerShell context using OIDC federated token or managed identity; required for RBAC and Key Vault operations. Imports of Az.* modules are intentionally performed with verbose output suppressed to keep CI logs clean.

    • Resolve-PimRoleResourcePairs — robust pairing of roleIds/resourceIds (zip, one-to-many, or Cartesian product).

    • Set-PimKeyVaultSecret — enumerates all secrets in a vault using Get-AzKeyVaultSecret -VaultName and rotates each secret using Set-AzKeyVaultSecret. The function includes Forbidden-aware retry/backoff to tolerate short RBAC propagation delays and returns an array of rotation result objects for reporting.

    • Write-PimSecretSummary — new helper that appends a Markdown table of rotated secrets to the GITHUB_STEP_SUMMARY file (when the environment variable is present), making a concise summary visible in GitHub Actions UI.

    • New-TemporaryKeyVaultRoleAssignment / Remove-TemporaryKeyVaultRoleAssignment — creates/removes a scoped RBAC assignment on the Key Vault. Remove-TemporaryKeyVaultRoleAssignment was hardened to use supported Remove-AzRoleAssignment parameter sets and defensively handle different property shapes returned by Get-AzRoleAssignment across Az versions.

    • Invoke-TempKeyVaultRotationLifecycle — orchestrates create → rotate secret → delete, and validates removal; used by CI.

    • project-jit-pim/scripts/run-activation.ps1 — Entry point for the workflow. Imports the module, determines whether the target is a Key Vault, and runs Invoke-TempKeyVaultRotationLifecycle when appropriate. Emits structured JSON for the pipeline and relies on ASSIGNEE_OBJECT_ID from the workflow environment.

• .github/workflows/

  • .github/workflows/pim-elevate.yml — Reusable workflow that collects role/resource inputs, builds an approval table (via project-jit-pim/scripts/build-approval.ps1), blocks on a GitHub Environment gate, then runs the privileged step via project-jit-pim/scripts/run-activation.ps1.

• project-jit-pim/infra/

  • project-jit-pim/infra/main.bicep — Demo infrastructure to support the JIT scenario: provisions a user-assigned managed identity (UAMI), an RBAC-enabled Key Vault, a Microsoft Entra application and service principal using the Microsoft Graph Bicep extension, and a resource group–scoped role assignment that grants the service principal User Access Administrator at the RG scope. Emits outputs (vault name/id, identity clientId/principalId/id, Graph appId/SP id, storage account id/name) for wiring into CI.

Scenarios and use cases

Below are practical scenarios where a CI runner (or other automation) would request a PIM-like activation via Microsoft Graph. Each example explains why a JIT activation is preferable to a permanent role assignment.

1. Privileged infrastructure deployments

   • Pipelines that need to modify RBAC, create or update management groups or subscriptions, or perform owner-level deployments. A JIT activation grants only the needed privileges for the deployment window and records the build/PR that requested it.

2. Emergency or hotfix changes in production

   • Automated runbooks that apply urgent network or configuration changes during incidents. JIT allows automation to act quickly while keeping the elevated window short and auditable.

3. Secrets, certificate, or key rotation tasks

   • Workflows that rotate Key Vault secrets, service principal certificates or subscription keys. Because these operations are high-sensitivity, they should run with time-limited elevation rather than a long-lived owner/service principal.

4. High-impact configuration changes

   • Actions like scaling a managed database, changing VM scale set properties, or upgrading infrastructure control-plane settings. These are low-frequency but risky operations — a JIT window reduces blast radius.

5. Onboard/offboard flows that require temporary promotion

   • Lifecycle workflows that temporarily promote a user or test identity to verify on‑boarding or off‑boarding steps (for example: run verification tests as an eligible admin then remove privileges automatically).

6. Incident-response diagnostics and remediation

   • Automated IR playbooks that need to query sensitive logs, alter firewall rules, or apply containment steps. JIT activations enable automation to remediate rapidly while ensuring short-lived privileges and full audit trails.

7. Governance and testing of access‑review flows

   • CI jobs that exercise access reviews, entitlement-management or PIM workflows in a test tenant by temporarily elevating a test identity. Useful for continuous verification of governance automation.

8. Multi-tenant or partner delegated operations

   • Managed services that perform privileged operations across customer tenants or external environments can request scoped JIT activations per-customer rather than holding standing privileges across all tenants.

9. Identity configuration changes

   • Deployments that create or update app registrations, add federated credentials, or change conditional access policies should run under a temporary, audited elevation rather than a permanent global admin assignment.

10. Scheduled maintenance and controlled windows

    • Scheduled jobs that perform approved maintenance during a defined window can programmatically request elevation (including ticket/maintenance ID justification) so the run is traceable and constrained to the maintenance period.

Each scenario benefits from: scoped, time-limited access; machine-readable justification and metadata (PR/build IDs); and an auditable activation lifecycle that can be retained in CI artifacts or forwarded to SIEM and compliance tooling.

Benefits vs Permanent assignments

• Minimized attack surface (short TTL)
• Tighter auditability (attach PR/build/ticket metadata)
• Easier compliance evidence (machine readable)
• Predictable rollback & revoke patterns

Background and motivation

Traditional automation patterns often rely on a broadly privileged service principal with a long-lived secret. That’s convenient but risky: secrets leak, and standing privileges widen blast radius. PIM shifts that posture to “trust, but timebound”: elevation requires a specific reason, duration, and an approver. For non-human actors (CI/CD), the right approximation is to programmatically create a temporary role assignment guarded by an approval gate, then remove it. This keeps privileges short-lived and auditable while still enabling fully automated flows (no portal clicks).

Compared with static service principals:

• No long-lived secret material is required when you use OIDC or managed identity.

• Privileges are granted just-in-time and automatically revoked.

• Every activation is traceable to a PR or run — easier audits and incident reconstruction.

Architecture overview

Actors

• CI runner (GitHub Actions): requests elevation, renders an approval table, waits for approval (GitHub Environment), and executes privileged operations once approved.

• Automation identity: either a user-assigned managed identity (UAMI) deployed by Bicep for demos, or an OIDC-federated workload identity for production pipelines.

• Azure Resource Manager (ARM): enforces role assignments and scopes; Key Vault is configured with RBAC data-plane permissions.

• Approver(s): GitHub Environment approvers; optionally, an automated approver (Function/Logic App) or notification to external systems like Teams/Slack can be integrated later.

Flow (high level)

1. CI job starts, logs into Azure via OIDC, and gathers requested role/resource pairs.

2. CI builds a Markdown approval table (role names, resource names) and posts it to the run; job waits for GitHub Environment approval.

3. On approval, CI executes a lifecycle function that:

   • Creates a temporary Key Vault–scoped role assignment for the automation identity (for example, Key Vault Secrets Officer),

   • Performs the privileged action (e.g., rotate a secret),

   • Removes the temporary role assignment and validates removal.

4. CI records structured output (vault, rotated secrets, timestamps, secret version) as artifacts.

Implementation

• Infrastructure: A Bicep template provisions a demo Key Vault with RBAC, a user-assigned managed identity, and emits helpful outputs (clientId, principalId, resource ids). See infra/main.bicep.

• Authentication: OIDC in GitHub Actions for the workflow; for local tests, you can log in interactively. Avoid long-lived secrets.

• PowerShell automation: module scripts/PimAutomation.psm1 implements a Graph wrapper (v1.0/beta compatibility) and the lifecycle for temporary RBAC assignments and secret rotation.

• CI/CD workflow: reusable workflow .github/workflows/pim-elevate.yml accepts roleIds/resourceIds, builds an approval table, blocks on environment approval, then runs scripts/run-activation.ps1 to execute the lifecycle.

• Approval automation (optional): future enhancement — an Azure Function approver for certain low-risk policies.

Demo infrastructure: project-jit-pim/infra/main.bicep

What it deploys

• Storage account (for a simple demo resource)

• User-assigned managed identity (UAMI) for automation

• Azure Key Vault configured with the RBAC permission model (enableRbacAuthorization: true)

• Microsoft Entra application and service principal via the Microsoft Graph Bicep extension

• A role assignment at the resource group scope that grants the service principal the built-in User Access Administrator role (roleDefinitionId GUID 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9) to create/remove role assignments within the RG

Key details reflected in the template

• Graph extension imports at top of file:

  • extension graphV1

  • extension graphBeta

• Graph resources declared using Microsoft.Graph/*@beta types for applications and servicePrincipals.

• Role assignment uses deterministic name via guid(...), principalId: ghSp.id, and subscription-scoped roleDefinitionId built with subscriptionResourceId('Microsoft.Authorization/roleDefinitions', userAccessAdminRoleId).

• Key Vault enables RBAC model for data-plane operations to align with this JIT pattern.

Outputs (used by CI/workflows)

• Key Vault: keyVaultName, keyVaultId

• UAMI: userIdentityClientId, userIdentityPrincipalId, userIdentityResourceId

• Graph: githubAppId, githubServicePrincipalId, githubServicePrincipalResourceId

• Storage: storageAccountId, storageAccountName

Quick deploy and validate

• Ensure your Bicep CLI is up to date and the Graph Bicep extensions are enabled via bicepconfig.json (see next section).

az bicep upgrade

# Create a demo resource group (choose a location)
az group create --name MyDemoRG --location eastus

# Validate the template
az deployment group validate \
    --resource-group MyDemoRG \
    --template-file project-jit-pim/infra/main.bicep \
    --parameters location=eastus

# Deploy
az deployment group create \
    --resource-group MyDemoRG \
    --template-file project-jit-pim/infra/main.bicep \
    --parameters location=eastus

Note: The role used in the demo (User Access Administrator) is convenient for a JIT RBAC demo because it can create/delete role assignments. In production, choose the least-privileged role and scope that fits your policy. Built-in roles reference: https://learn.microsoft.com/azure/role-based-access-control/built-in-roles

Using Microsoft Graph resources in Bicep (beta)

You can author Entra resources (applications / service principals) directly from Bicep using the Microsoft Graph Bicep templates. This is a preview extensibility feature in Bicep and requires two things:

• enabling Bicep extensibility in your repo-level bicepconfig.json, and

• importing the Microsoft Graph extension in any Bicep file that declares Microsoft.Graph/* resources.

What you need

• A recent Bicep CLI (or Azure CLI with the Bicep command) and the VS Code Bicep extension.

• A repo-level bicepconfig.json that enables the extensibility feature and maps extension aliases to the registry artifacts. Ensure extensibility is enabled. Example:

{
    "experimentalFeaturesEnabled": {},
    "extensions": {
        "graphV1": "br:mcr.microsoft.com/bicep/extensions/microsoftgraph/v1.0:1.0.0",
        "graphBeta": "br:mcr.microsoft.com/bicep/extensions/microsoftgraph/beta:1.0.0"
    }
}

See the Bicep configuration docs for details: https://learn.microsoft.com/azure/azure-resource-manager/bicep/bicep-config and the experimental features overview: https://github.com/Azure/bicep/blob/main/docs/experimental-features.md

Importing the Graph extension

Once bicepconfig.json is present and extensibility is enabled, import the Graph extensions at the top of your Bicep file using the aliases defined in bicepconfig.json:

// imports by alias (preferred when you've mapped the extension in bicepconfig.json)
extension graphV1
extension graphBeta

After the extension import, you can declare Microsoft Graph types in Bicep. Example (beta) — consult the Graph Bicep reference for available properties and schema:

```bicep
resource ghApp 'Microsoft.Graph/applications@beta' = {
  uniqueName: toLower('pim-github-app-${uniqueString(resourceGroup().id)}')
  displayName: 'pim-github-oidc-app-${uniqueString(resourceGroup().id)}'
  signInAudience: 'AzureADMyOrg'
}

resource ghSp 'Microsoft.Graph/servicePrincipals@beta' = {
  appId: ghApp.appId
  displayName: ghApp.displayName
}

Reference: Microsoft Graph Bicep templates — https://learn.microsoft.com/graph/templates/bicep/reference/serviceprincipals?view=graph-bicep-beta

Validate and deploy

See the quick commands in the previous section for validation and deployment to a resource group.

Troubleshooting and fallback strategy

• If you get "resource type is not valid" or similar validation errors, ensure:

  • Bicep CLI and the VS Code Bicep extension are up to date.

  • bicepconfig.json is in the repository root (or a parent folder) and contains "experimentalFeaturesEnabled": { "extensibility": true }.

  • The extension import line appears before any Microsoft.Graph/* resource declarations.

• Some developer or CI environments may still lack the provider metadata required to author Graph types (the extensibility path is still evolving). If your environment cannot use the Graph Bicep extension, you can adapt the template to accept githubAppId and githubServicePrincipalId as parameters and only create the role assignment when the service principal id is supplied. This lets teams either:

  1. Create the app/service principal ahead of time (via CLI or Graph APIs) and pass the returned appId/principalId into the Bicep deployment, or

  2. Enable Bicep extensibility in their dev/CI images and let the template create the app/SP directly.

Related discussion and issues: https://github.com/Azure/bicep/issues/16447

GitHub Actions workflow: .github/workflows/pim-elevate.yml

Purpose: provide a generic, approval-gated JIT elevation workflow reusable across repos and branches.

Inputs (from the caller):

• roleIds — JSON array of role definition GUIDs to request (e.g., Key Vault Secrets Officer).

• resourceIds — JSON array of Azure resource IDs to scope the request/assignment (e.g., Key Vault resource ID).

• vaultName, secretName — Optional; if provided, the workflow will perform a secret rotation using the lifecycle function after approval.

Jobs and flow:

1. request-elevation

   • Auth: Logs into Azure using OIDC (federated credentials) so az lookups can run without secrets.

   • Pairing logic: Builds pairs of roleId/resourceId with the following rules:

     • If arrays are equal length → zip items by index.

     • If one array has length 1 and the other >1 → pair the single item across all items of the other array.

     • Otherwise → produce a Cartesian product (all combinations).

   • Reverse lookups + approval table: Implemented by project-jit-pim/scripts/build-approval.ps1 — resolves human-readable names/types and renders a Markdown table (IDs and names wrapped in inline code; pipes/backticks/newlines escaped). The table is posted as a comment (for PRs) or added to the job summary.

   • Gate: The job emits metadata and ends; the next job is gated by a GitHub Environment (for example, pim-rotation-approval).

2. approve-and-rotate

   • Gate: Requires the GitHub Environment approval. Approvers can review the comment table before proceeding.

     • Another option is to implement approval in the pull request itself (for example, require a specific label or review) and skip the Environment gate. This is left as an exercise for the reader.

   • Auth: Logs into Azure using OIDC for RBAC operations.

   • Action: Resolves role/resource pairs via the module, selects the first pair for the demo, and runs project-jit-pim/scripts/run-activation.ps1 which orchestrates Invoke-TempKeyVaultRotationLifecycle to create the temporary Key Vault assignment → rotate the secret → remove the assignment → validate removal.

   • Outputs: Emits structured JSON and can publish artifacts with rotation details.

Requirements:

• A GitHub Environment configured with approvers (e.g., pim-rotation-approval).

• Federated identity (OIDC) configured in Azure with minimal RBAC to create/delete role assignments at the scopes you target.

• The target Key Vault must be RBAC-enabled (enableRbacAuthorization: true).

Notes:

• The workflow is designed to be reusable; use the demo caller as a reference for input wiring.

• For managed identities, PIM eligibility is not applicable; the workflow relies on temporary RBAC during the approved window and records rotation metadata for traceability.

PowerShell module: project-jit-pim/scripts/PimAutomation.psm1

Design goals:

• PowerShell 7.4, cross-platform, non-interactive by default in CI.

• Testability: Supports an environment flag to skip live Graph calls during Pester runs.

• Clear separation between Graph (request/trace) and Azure RBAC (enforcement at resource scope).

Key functions and behavior:

• Get-GraphAccessToken and Connect-PimGraph: establish Graph access using an Azure CLI token when present; fall back to Connect-MgGraph in dev.

• Invoke-PimGraphRequest: sends requests to v1.0 or beta, with a predictable return shape and error handling for future Graph integrations.

• Set-PimAzContext: establishes Az PowerShell context using OIDC federated token or managed identity for non-interactive CI runs.

• Resolve-PimRoleResourcePairs: flexible pairing logic used by the workflow to map roleIds to resourceIds.

• New-TemporaryKeyVaultRoleAssignment and Remove-TemporaryKeyVaultRoleAssignment: create/delete RBAC assignments at the Key Vault scope for a specific principal (the automation identity). Output uses RoleAssignmentId/RoleAssignmentName (per Az.Resources).

• Set-PimKeyVaultSecret: sets or rotates a secret using Az.KeyVault under the short-lived RBAC assignment, with Forbidden-aware retry to handle eventual consistency of new role assignments.

• Invoke-TempKeyVaultRotationLifecycle: orchestrates the full sequence, validates removal, and returns a structured object suitable for CI logs and artifacts.

Contract (high level):

• Inputs: role definition ID, target resource ID (Key Vault), principal object ID, vault and secret names, and optional justification/metadata.

• Error modes: Graph unavailability (handled via stub/test mode), RBAC propagation delays (should be retried with backoff), and Azure API transient failures (retryable).

• Outputs: rotation metadata (vault, secret name, secret version, timestamps), RBAC assignment details (id, scope), and any contextual lifecycle information surfaced by the helper.

Security and governance considerations

• Permissions: Use least-privilege scopes and roles; prefer RBAC scopes at the minimal resource level required.

• Authentication: Prefer OIDC for CI runners and managed identities for Azure-hosted automation; avoid long-lived client secrets.

• Approval: Require human approval (GitHub Environment) for production; optionally add policy-based automated approvals for low-risk cases.

• TTLs: Keep elevation windows as short as practical. Validate that RBAC propagation is complete before proceeding.

• Audit: Persist machine-readable activation artifacts for retention and SIEM ingestion.

• Workload identity hardening: This just-in-time + just-enough access pattern pairs well with Microsoft Entra Workload Identity Protection to further restrict token acquisition and usage. By combining time-limited RBAC assignments with workload identity restrictions (e.g., OIDC token validation, IP allow listing, and token binding), you create a defense-in-depth posture that makes lateral movement and token replay attacks significantly harder.

Testing and validation

• Unit tests: When you add tests, prefer Pester with Graph calls disabled via an environment flag; mock Az/Graph cmdlets to validate logic paths.

• Integration tests: Use a test subscription and a disposable Key Vault. Ensure cleanup of temporary role assignments.

• Failure modes: Validate behavior for denied approvals, RBAC propagation delays (Forbidden), and transient Azure API errors (retries with back off).

Demo / walk-through — Secret / Key Rotation

This walk-through focuses on a concrete, high-value scenario: rotating a Key Vault secret (for example, a service principal client secret or an application key) under a just-in-time privileged activation requested by the CI runner. Rotating secrets is a common operational task that requires elevated privileges and benefits from short-lived, auditable elevation.

High-level steps for the demo

1. Prerequisites

   • An Azure Key Vault configured to use the Azure RBAC permission model (enableRbacAuthorization: true). This allows data-plane permissions via RBAC.

   • A CI runner identity: GitHub OIDC for the workflow, or a user-assigned managed identity for Azure-hosted runs.

2. CI job starts and validates context

   • The GitHub Action runner verifies branch/ticket/PR metadata and ensures the job is allowed to request elevation (demo mode may allow auto-approvals).

3. Prepare activation context programmatically

   • The workflow calls Resolve-PimRoleResourcePairs to expand role/resource combinations into discrete activation targets.

   • For automation identities (managed identities), the flow focuses on short-lived RBAC assignments rather than PIM request objects, keeping the footprint minimal for CI.

4. Approval and activation

   • The reusable workflow posts an approval table and pauses at a GitHub Environment gate. Approvers can review the requested role/resource pairs before proceeding.

   • A future enhancement may add an optional automated approver (Function/Logic App) for specific policies or send notifications to Teams/Slack.

5. Rotate the secret (performed under the JIT activation)

   • The automation generates a new secret value and calls Set-AzKeyVaultSecret under a temporary, Key Vault–scoped RBAC assignment. The flow implemented here is:

     1. Wait for approval at the GitHub Environment gate.

     2. Create a temporary Key Vault data-plane RBAC assignment (e.g., Key Vault Secrets Officer) for the automation identity. New assignments may take a short time to propagate; the module retries on Forbidden.

     3. Perform the secret write while the assignment is active.

     4. Remove the temporary assignment and validate removal.

     5. Return rotation metadata (vault name, secret name, version, timestamps) to the caller.

   • The repository includes scripts/PimAutomation.psm1 with helper functions and a lifecycle function Invoke-TempKeyVaultRotationLifecycle that orchestrates the create → rotate → delete sequence.

   • Optionally rotate dependent credentials and notify consumers in a follow-up step (future enhancement with a safe consumer-rotation harness).

6. Revoke/expire and audit

   • After the rotation completes, the activation ends (either automatically by PIM TTL or by an explicit revocation step). The pipeline records a machine-readable artifact containing activation timing, rotated secret versions, and build/PR metadata.

   • Upload that artifact to the run's artifacts and forward structured events to SIEM or a compliance store.

7. Post-rotation validation

   • Run integration smoke tests that verify the rotated secret works for consumers (use a test consumer identity and avoid printing secrets to logs).

   • If validation fails, run an automated rollback plan (store previous secret version reference and use it to restore if necessary).

Conclusion

JIT elevation for automation brings the control and auditability of PIM into your delivery pipelines. By replacing standing privileges with an approval-gated, short-lived role assignment, you reduce risk without sacrificing speed. The patterns here give you a pragmatic starting point you can adapt — start with the reusable workflow and lifecycle helper, then layer in Graph-backed requests and richer approvals as you mature. 🚀

References

• Github Repo: https://github.com/broberts23/vsCode/tree/main/project-jit-pim

• Microsoft Entra PIM docs: https://learn.microsoft.com/en-us/entra/id-governance/privileged-identity-management/pim-configure

• Microsoft Graph PIM APIs: https://learn.microsoft.com/en-us/graph/api/resources/privilegedidentitymanagementv3-overview?view=graph-rest-1.0

• Azure RBAC for Key Vault: https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide

• Az PowerShell: Connect-AzAccount — https://learn.microsoft.com/powershell/module/az.accounts/connect-azaccount?view=azps-latest

• Az PowerShell: Set-AzKeyVaultSecret — https://learn.microsoft.com/powershell/module/az.keyvault/set-azkeyvaultsecret?view=azps-latest

• Az PowerShell: New-AzRoleAssignment — https://learn.microsoft.com/powershell/module/az.resources/new-azroleassignment?view=azps-latest

Reference: Azure Blob Storage Lifecycle Management

What Are Lifecycle Management Policies?

A lifecycle management policy is a JSON ruleset attached to a Storage Account that tells Azure, "Here's what I want you to do with blobs that match certain criteria." The Azure Storage service evaluates these rules periodically (timing is internal and service-managed) and applies actions like deleting old blobs, moving them to cooler storage tiers, or cleaning up versions and snapshots.

You define:

• Filters: Which blobs to target (by type, container prefix, blob name prefix)

• Actions: What to do with them (delete, tier to Cool/Archive, etc.)

• Thresholds: Time-based conditions (days since creation, modification, or last access)

The policy runs automatically, transparently, and scales with your data—no servers, no invocation logs to parse, no scaling concerns.

Anatomy of a Lifecycle Rule

Here's the simplest possible rule: delete block blobs older than 7 days.

{
  "rules": [
    {
      "name": "DeleteOldBlobs",
      "enabled": true,
      "type": "Lifecycle",
      "definition": {
        "filters": {
          "blobTypes": ["blockBlob"]
        },
        "actions": {
          "baseBlob": {
            "delete": {
              "daysAfterModificationGreaterThan": 7
            }
          }
        }
      }
    }
  ]
}

This rule:

• Targets all block blobs (blobTypes)

• Deletes base blobs (baseBlob.delete) if LastModified is more than 7 days ago

• -Runs periodically (service-managed schedule)

Filtering by Container

In production, you rarely want to apply a policy to every blob in the account. The prefixMatch filter lets you target specific containers or blob prefixes.

"filters": {
  "blobTypes": ["blockBlob"],
  "prefixMatch": ["signin", "audit", "logs"]
}

This matches:

• signin/anything

• audit/anything

• logs/anything

Blob paths are virtual (Azure Storage is flat), so signin/entra/20251123.json matches the signin prefix. You can be more granular: "prefixMatch": ["signin/entra"] would only target that subtree.

Azure allows up to 100 rules per Storage Account. By consolidating multiple containers into a single rule with an array of prefixes, you stay well under quota and keep the policy maintainable.

Handling Snapshots

Blobs can have snapshots (point-in-time immutable copies). If you delete a base blob but leave snapshots orphaned, they continue consuming storage and cost. Lifecycle policies have a dedicated snapshot action:

"actions": {
  "baseBlob": {
    "delete": {
      "daysAfterModificationGreaterThan": 7
    }
  },
  "snapshot": {
    "delete": {
      "daysAfterCreationGreaterThan": 7
    }
  }
}

Note the difference:

• Base blobs use daysAfterModificationGreaterThan (when the blob was last written)

• Snapshots use daysAfterCreationGreaterThan (when the snapshot was created, which is immutable)

This ensures snapshots older than 7 days are purged alongside their parent, keeping storage tidy.

Tiering Before Deletion (Cost Optimization)

If your access patterns allow, you can tier blobs to cooler storage (Cool or Archive) before deleting them entirely. This reduces storage costs while retaining data for a grace period.

"actions": {
  "baseBlob": {
    "tierToCool": {
      "daysAfterModificationGreaterThan": 7
    },
    "tierToArchive": {
      "daysAfterModificationGreaterThan": 30
    },
    "delete": {
      "daysAfterModificationGreaterThan": 90
    }
  }
}

Lifecycle:

1. Day 7: Blob moves to Cool tier (lower storage cost, higher access cost)

2. Day 30: Blob moves to Archive tier (lowest storage cost, high rehydration cost)

3. Day 90: Blob deleted permanently

This staged approach is common in compliance scenarios where you need to retain data for auditing but can tolerate slower access as it ages.

Reference: Access tiers for blob data

Blob Versioning and Lifecycle Policies

If versioning is enabled on your Storage Account, every overwrite creates a new version. Old versions can accumulate quickly. Lifecycle policies support version-specific actions:

"actions": {
  "version": {
    "delete": {
      "daysAfterCreationGreaterThan": 30
    }
  }
}

This deletes non-current versions older than 30 days, keeping only the latest version and recent history.

Reference: Blob versioning

Last Access Time Tracking

Azure Storage can optionally track when each blob was last read (requires enabling access time tracking on the account). Policies can then delete blobs that haven't been accessed recently, even if they're modified frequently:

"actions": {
  "baseBlob": {
    "tierToCool": {
      "daysAfterLastAccessTimeGreaterThan": 30
    },
    "enableAutoTierToHotFromCool": true,
    "delete": {
      "daysAfterLastAccessTimeGreaterThan": 90
    }
  }
}

This is powerful for log archives or cold data lakes where "staleness" means "nobody's reading this anymore" rather than "nobody's writing to this anymore."

Reference: Optimize costs by automatically managing the data lifecycle

Deploying with Bicep

Bicep lets you version, test, and deploy lifecycle policies as infrastructure-as-code. Here's a minimal module:

// lifecyclePolicy.bicep
param storageAccountName string
param containerPrefixes array
param retentionDays int = 7

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
  name: storageAccountName
}

resource managementPolicy 'Microsoft.Storage/storageAccounts/managementPolicies@2025-06-01' = {
  name: 'default'
  parent: storageAccount
  properties: {
    policy: {
      rules: [
        {
          name: 'DeleteOldBlobs'
          enabled: true
          type: 'Lifecycle'
          definition: {
            filters: {
              blobTypes: ['blockBlob']
              prefixMatch: containerPrefixes
            }
            actions: {
              baseBlob: {
                delete: {
                  daysAfterModificationGreaterThan: retentionDays
                }
              }
              snapshot: {
                delete: {
                  daysAfterCreationGreaterThan: retentionDays
                }
              }
            }
          }
        }
      ]
    }
  }
}

Reference: Microsoft.Storage/storageAccounts/managementPolicies

Deploy with environment-specific parameters:

New-AzResourceGroupDeployment `
  -ResourceGroupName "rg-prod" `
  -TemplateFile ./infra/main.bicep `
  -TemplateParameterFile ./infra/parameters.prod.json

Parameter files let you vary container lists and retention periods across dev/test/prod without duplicating Bicep code.

Reference: New-AzResourceGroupDeployment

Multi-Environment Strategy

Structure parameter files like this:

parameters.dev.json (aggressive cleanup for fast iteration):

{
  "storageAccountName": { "value": "stdevblobcleanup001" },
  "containerPrefixes": { "value": ["testA", "testB"] },
  "retentionDays": { "value": 2 }
}

parameters.prod.json (conservative retention):

{
  "storageAccountName": { "value": "stprodblobcleanup001" },
  "containerPrefixes": { "value": ["signin", "audit", "logs"] },
  "retentionDays": { "value": 90 }
}

Same Bicep template, different behavior per environment. Version control tracks changes; CI/CD pipelines enforce review gates before production deployments.

When to Use Lifecycle Policies vs Custom Code

Use lifecycle policies when:

• Retention logic is purely time-based (days since modification/creation/access)

• You want zero operational overhead (no Functions, no logs to monitor)

• Filters are simple (blob type, container prefix, blob name prefix)

• Tiering and deletion are sufficient actions

Use custom code (e.g., Azure Functions) when:

• You need filename parsing or complex business logic (e.g., "delete if filename matches pattern X")

• Per-run reporting is required (deletion counts per container logged to App Insights)

• You need conditional behavior (demo mode vs real mode, dry-run logic)

• Integration with external systems (send notifications, update databases, emit custom metrics)

Lifecycle policies are elegant for straightforward retention; custom code is the escape hatch for everything else.

Testing Your Policy

Before enabling a policy in production, seed test data with the provided Seed-StorageContainers.ps1 script:

./scripts/Seed-StorageContainers.ps1 `
  -StorageAccountName "stdevblobcleanup001" `
  -ResourceGroup "rg-dev" `
  -PastDays 10 `
  -FutureDays 2

This creates blobs with filenames encoding timestamps (e.g., signin/entra/20251113000000.json). Deploy your policy with a short retention window (retentionDays: 2) and check after the next daily evaluation cycle (typically within 24 hours) whether old blobs were deleted.

Important caveat: Lifecycle policies evaluate LastModified or creation time, not filename content. The seeding script creates blobs with timestamps in their filenames, but all blobs will have LastModified set to the upload time. To test retention policies effectively, you need to wait for blobs to age naturally—there is no supported way to backdate blob timestamps. For rapid testing, use very short retention periods (1-2 days) and verify policy execution after 24-48 hours.

Validating the Policy in the Azure Portal

After deployment (Bicep or ARM), you can confirm the lifecycle policy configuration and observe its effects directly in the Azure Portal.

Verify Rule Definition

1. Navigate to the Storage Account.

2. In the left menu, under Data management, select Lifecycle management.

3. Use the List view tab to confirm your rule appears (e.g., DeleteOldBlobs) and its status is Enabled.

4. Switch to Code view to inspect the JSON that the portal stored. It should reflect the Bicep deployment (prefixes, daysAfterModificationGreaterThan, snapshot settings).

If the rule was just deployed or modified, allow up to 24 hours for the first evaluation cycle (per Microsoft guidance). The presence of the rule in the portal does not mean deletions have already occurred.

Reference: Configure a lifecycle management policy (Azure Portal)

Monitoring and Observability

Lifecycle policy executions don't emit logs to Application Insights or Azure Functions invocation history. To track deletions:

1. Storage Analytics Logs: Enable logging on the Storage Account; deletion operations appear in $logs container

2. Azure Monitor Metrics: Track container-level metrics (blob count, capacity)

3. Log Analytics Integration: Route diagnostic logs to a Log Analytics workspace and query StorageBlobLogs

Reference: Monitor Azure Blob Storage

Example Kusto query for deletion tracking:

StorageBlobLogs
| where OperationName == "DeleteBlob"
| where TimeGenerated > ago(7d)
| summarize DeletionCount = count() by ContainerName = split(Uri, "/")[3]
| order by DeletionCount desc

Extending the Bicep Module

The lifecycle policy module can grow with your needs. Add parameters for:

• Tiering actions: Expose tierToCool, tierToArchive with separate thresholds

• Version cleanup: Add version.delete action if versioning enabled

• Multiple rules: Loop over an array of rule definitions for complex scenarios

• Conditional deployment: Use Bicep conditionals to deploy policies only if certain features are enabled (e.g., versioning, soft delete)

Bicep's modular design keeps the core template simple while allowing opt-in complexity.

Reference: Bicep Best Practices

Wrapping Up

Azure Storage Lifecycle Management Policies are the right tool when retention is time-based and you value operational simplicity over granular control. Deploy them with Bicep, test with realistic data, and let the service handle the rest. Your infrastructure stays declarative, your storage costs stay predictable, and you avoid the operational overhead of maintaining yet another background job.

For scenarios demanding filename parsing, per-run reporting, or conditional logic, custom code remains the escape hatch—but for most cleanup workloads, the built-in lifecycle engine is enough. 🚀

References

• My GitHub Repo
• Azure Blob Storage Lifecycle Management
• Bicep Best Practices
• Monitor Azure Blob Storage
• Enable access time tracking
• Lifecycle management policy monitoring

We’ll cover the problem, the design, some tricky implementation details (Managed Identity auth, CloudQueue vs QueueClient data paths), and how to visualize the results. Everything shown lives in this repository so you can clone and run it end-to-end.

The problem and the constraints

• Azure Monitor’s built-in QueueMessageCount for storage accounts is hourly and not split per queue. You can’t retrieve per-queue counts via Azure Monitor metrics.

• Teams need per-queue counts at a 5 minute cadence to alert on spikes and monitor backlog trends.

• We want secure auth (Managed Identity), no keys in code, and a minimal footprint.

Solution overview

We poll each queue in a storage account with Az.Storage and emit a custom metric per queue to Application Insights using the v2 ingestion endpoint. Workbooks and Metrics Explorer can then visualize and alert on these metrics by the QueueName dimension.

High level flow:

1. Timer-trigger function runs every 5 minutes.

2. Uses Managed Identity to authenticate to the storage account data plane.

3. Enumerates queues and queries an approximate visible message count per queue.

4. Sends a custom metric item per queue to Application Insights with dimensions StorageAccount and QueueName.

Prerequisites and configuration

RBAC and Managed Identity

The Function App uses a system-assigned managed identity. Assign one of these data-plane roles at the storage account:

• Storage Queue Data Reader (read-only)

• Storage Queue Data Contributor (read/write)

Then authenticate with New-AzStorageContext -UseConnectedAccount. This avoids keys and works well in Functions.

App settings (environment variables)

The function expects these settings (set as Function App application settings or local environment variables):

• APPLICATIONINSIGHTS_CONNECTION_STRING (or APPINSIGHTS_CONNECTION_STRING)

• AZURE_SUBSCRIPTION_ID

• STORAGE_RESOURCE_GROUP

• STORAGE_ACCOUNT_NAME

Function implementation (PowerShell)

The function is functionApp/QueueMessageCount/run.ps1. It uses Managed Identity via New-AzStorageContext -UseConnectedAccount and supports both the legacy WindowsAzure.Storage path and the modern Azure.Storage.Queues path.

Key setup and auth:

# Build OAuth data-plane context for queues using the Function App's managed identity
$ctx = New-AzStorageContext -StorageAccountName $StorageAccountName -UseConnectedAccount -ErrorAction Stop

# List queues with AAD context
$queues = Get-AzStorageQueue -Context $ctx -ErrorAction Stop

Why -UseConnectedAccount matters

-UseConnectedAccount tells Az.Storage to use the Azure AD token from your current Az context (in Functions, the system-assigned managed identity from Connect-AzAccount -Identity) to authenticate to the Storage data plane. That has a few important implications:

• With -UseConnectedAccount:

  • Data-plane calls are authorized by RBAC. Grant the identity a data-plane role like Storage Queue Data Reader/Contributor and you’re good—no keys in code.

  • The returned queue objects are typically backed by the modern Azure.Storage.Queues client, so you’ll find QueueClient and should read counts via QueueClient.GetProperties().Value.ApproximateMessagesCount.

• Without -UseConnectedAccount:

  • New-AzStorageContext will fall back to shared key or connection-string auth. If you didn’t provide keys/connection string, the context can’t authorize queue data-plane calls and you’ll see 403s or empty/null properties—leading to zeros sent to App Insights.

  • If you try to reuse $storage.Context from Get-AzStorageAccount, it may not contain keys under a managed-identity scenario (listing keys requires management-plane permissions). You’ll end up with an unusable data-plane context.

In short: Managed Identity + no keys means use -UseConnectedAccount.

• The legacy CloudQueue path often isn’t available under AAD; preference the QueueClient path when using MI.

Reading the data path:

# Modern (Azure.Storage.Queues) path
$props = $qref.QueueClient.GetProperties()
$approx = $props.Value.ApproximateMessagesCount
if ($null -ne $approx) { $value = [int]$approx }

Sending a metric to Application Insights (v2 track endpoint):

$endpoint = $IngestionEndpoint.TrimEnd('/') + '/v2/track'
$env = @{ 
  name = 'Microsoft.ApplicationInsights.Metric'
  time = (Get-Date).ToString('o')
  iKey = $ikey
  data = @{ 
    baseType = 'MetricData'
    baseData = @{ 
      ver = 2
      metrics = @( @{ name = 'QueueMessageCount'; value = [double]$value } )
      properties = @{ StorageAccount = $StorageAccountName; QueueName = $queueName }
    }
  }
}
Invoke-RestMethod -Method Post -Uri $endpoint -ContentType 'application/json' -Body ($env | ConvertTo-Json -Depth 10)

How the custom metric works:

• Endpoint and identity:

  • We post to the ingestion endpoint from your connection string (APPLICATIONINSIGHTS_CONNECTION_STRING) at .../v2/track.

  • The envelope includes iKey (Instrumentation Key); the service uses it to attribute telemetry to your App Insights resource. If it’s missing/invalid, ingestion fails.

• Envelope shape (metrics v2):

  • name = 'Microsoft.ApplicationInsights.Metric' with data.baseType = 'MetricData' and baseData.ver = 2.

  • baseData.metrics is an array of one or more metrics. Each item has name and a numeric value (double). We send one metric: QueueMessageCount.

  • baseData.properties carries dimensions (key/value strings). We set StorageAccount and QueueName. In Metrics Explorer these become metric dimensions; in Logs they appear under customDimensions.

• Aggregation and visualization:

  • App Insights treats each posted item as a metric sample. In Metrics Explorer, you can aggregate (Avg, Sum, Min, Max) over time and split by QueueName to chart per-queue trends.

  • In KQL (Logs > customMetrics), numeric samples are available as value, and dimensions in customDimensions. Example:

      customMetrics
      | where name == "QueueMessageCount"
      | summarize avg(value) by tostring(customDimensions.QueueName), bin(timestamp, 5m)
    

• Cardinality and cost:

  • Keep dimension cardinality reasonable (queue names are fine). Very high-cardinality dimensions increase metric series and cost.

  • Batch by sending an array of envelopes if needed; my function sends one envelope per queue per run, which is typically acceptable.

Connection string notes and validating ingestion:

• Connection string vs iKey parsing:

  • The modern APPLICATIONINSIGHTS_CONNECTION_STRING contains both the ingestion endpoint and the Instrumentation Key. Our function parses the iKey and sets it on each envelope because the raw /v2/track endpoint expects an iKey on every item.

  • If you’d prefer not to parse the iKey yourself, consider using the official Application Insights/ Azure Monitor SDKs which read the connection string and sign telemetry automatically. For direct HTTP calls to /v2/track, keep including iKey in the envelope.

• Validate ingestion quickly:

  • Check the HTTP response body from /v2/track — it returns counts. Example:

      $resp = Invoke-RestMethod -Method Post -Uri $endpoint -ContentType 'application/json' -Body $bodyJson -ErrorAction Stop
      if ($resp.itemsAccepted -lt $resp.itemsReceived) {
        Write-Warning ("AI ingestion partial success: Accepted={0} Received={1} Errors={2}" -f $resp.itemsAccepted, $resp.itemsReceived, ($resp.errors | ConvertTo-Json -Depth 5))
      }
    

  • Live Metrics: open Live Metrics in your App Insights resource to confirm the instance is receiving telemetry (requests/dependencies/traces). Custom metrics typically appear in Metrics Explorer within ~1–2 minutes even if they don’t show in Live Metrics streams directly.

Why per-queue via SDK and not Azure Monitor metrics?

Azure’s built-in metric QueueMessageCount for Microsoft.Storage/storageAccounts/queueServices is sampled hourly and has no per-queue dimension. That’s great for account-level trends, but not for operational backlogs per queue. Reading the approximate visible count with the SDK provides timely, per-queue values suitable for dashboards and alerts.

Infrastructure as Code (Bicep)

The Bicep file infra/main.bicep provisions:

• Storage account (Standard_LRS)

• Queue service and six randomly named queues

• App Insights instance

• Consumption Function App (PowerShell) with a system-assigned managed identity

• A file share for function content settings

Notable settings injected into the Function App:

siteConfig: {
  appSettings: [
    { name: 'APPLICATIONINSIGHTS_CONNECTION_STRING', value: appInsights.properties.ConnectionString }
    { name: 'STORAGE_ACCOUNT_NAME', value: st.name }
    { name: 'STORAGE_RESOURCE_GROUP', value: resourceGroup().name }
    { name: 'AZURE_SUBSCRIPTION_ID', value: subscription().subscriptionId }
  ]
}

Outputs include the queue names and the storage/account info, which our scripts consume.

CI/CD with GitHub Actions

Two workflows are included:

• .github/workflows/deploy.yml — end-to-end infra + function:

  • Logs into Azure via OIDC (don’t forget to store the service principal details as repository secrets. I’ve covered using OIDC to authenticate Github to Azure in depth in previous blogs. You can find more information on how to set up OIDC authentication in parts 4 and 5 of Azure MLOps Challenge Blog)

  • Deploys infra/main.bicep

  • Zips functionApp/ and deploys the Function App

  • Runs scripts/populate-queues.ps1 to add messages

• .github/workflows/deploy-function.yml — function-only redeploy.

These workflows take optional inputs for names, otherwise they auto-generate compliant names.

Seeding data and repeatable tests (scripts)

Two helper scripts in scripts/ create sample queues and populate messages using Azure CLI:

• create-queues.ps1 reads deployment outputs and creates queues:

$out = az deployment group show --resource-group $ResourceGroup --name $DeploymentName --query properties.outputs -o json | ConvertFrom-Json
$storageName = $out.storageAccount.value
$queues = $out.queueNames.value
$conn = az storage account show-connection-string --resource-group $ResourceGroup --name $storageName -o tsv
foreach ($q in $queues) { az storage queue create --name $q --connection-string $conn }

• populate-queues.ps1 fills each queue with a random number of messages:

$out = az deployment group show --resource-group $ResourceGroup --name $DeploymentName --query properties.outputs -o json | ConvertFrom-Json
$storageName = $out.storageAccount.value
$queues = $out.queueNames.value
$conn = az storage account show-connection-string --resource-group $ResourceGroup --name $storageName -o tsv
foreach ($q in $queues) {
  $count = Get-Random -Minimum $MinMessages -Maximum ($MaxMessages + 1)
  for ($i = 0; $i -lt $count; $i++) { az storage message put --queue-name $q --content "msg-$([random]::new().Next(100000,999999))" --connection-string $conn }
}

These are used automatically in the GitHub workflow after deployment to generate a non-zero baseline for monitoring.

Visualizing and alerting

You can use either Metrics Explorer or Workbooks.

• Metrics Explorer (App Insights):

  • Metric namespace: Custom

  • Metric: QueueMessageCount

  • Split by: QueueName

  • Filter by: StorageAccount if needed

• Workbooks (Logs):

customMetrics
| where name == "QueueMessageCount"
| summarize avg(value) by tostring(customDimensions.QueueName), bin(timestamp, 5m)
| order by timestamp desc

Create a metric alert on the custom metric (dimension: QueueName) or a Log Analytics alert using a scheduled query. You can use the same query to visual the data in Workbooks

Troubleshooting: why would counts be 0?

• Missing data-plane role: assign Storage Queue Data Reader/Contributor to the Function’s managed identity.

• Using account keys but wrong context: prefer -UseConnectedAccount with MI.

• Wrong data path: on AAD auth, QueueClient.GetProperties().Value.ApproximateMessagesCount is the reliable path; CloudQueue may not be present.

• Immediate staleness: approximate counts lag slightly; verify via a quick Peek if in doubt.

Conclusion

Per-queue message counts are not available via Azure Monitor metrics, but they’re straightforward to gather the metrics with Az.Storage and publish as custom metrics in Application Insights. With Managed Identities, Bicep, and GitHub Actions, you can deploy the whole pipeline, seed data, and put dashboards/alerts in front of your team in an hour.

The code here is ready to use with a small footprint and clear extension points (retry/backoff, filtering queues, sampling). Clone the repo, deploy, and start monitoring. 🚀

References

• Azure Storage Queues overview: https://learn.microsoft.com/azure/storage/queues/

• Application Insights custom metrics: https://learn.microsoft.com/azure/azure-monitor/app/metrics

• Az.Storage PowerShell: https://learn.microsoft.com/powershell/module/az.storage/

When I ran into this problem, I found a lot of old and conflicting information online. This post aims to clarify the current best practices for configuring proxies in Azure Function Apps, particularly in enterprise scenarios.

Why Proxy Configuration Matters

In large organizations, outbound traffic from cloud workloads often needs to be controlled for security, auditing, and compliance. Proxies and firewalls are the primary tools for this, but knowing when and how to use each is key to a robust architecture.

Azure Function App Networking Overview

Azure Function Apps can be integrated with Virtual Networks (VNets), use private endpoints, and route outbound traffic through Azure Firewall or a corporate proxy. Key networking features include:

• VNet Integration: Allows your function app to access resources in a private network. When you enable VNet integration, you can use user-defined routes (UDRs) to control how outbound traffic is routed—either directly to the internet, through an Azure Firewall, or to a proxy server. This enables granular control over which traffic is inspected, filtered, or bypassed based on your security requirements.

• Azure Firewall: Controls and logs outbound traffic at the network level, providing centralized security and compliance enforcement for all protocols.

• Proxies: Enforce outbound HTTP(S) traffic policies, authentication, and logging. Proxies are typically used for HTTP/S traffic, while firewalls handle all protocols.

Proxy vs. Azure Firewall: When to Use Each

• Azure Firewall is ideal for controlling all outbound traffic, including non-HTTP protocols, and provides centralized logging and threat protection.

• Proxy Servers are best for HTTP(S) traffic, providing granular control, authentication, and content filtering.

• Combined Approach: In many enterprises, HTTP(S) traffic is routed through a proxy, while other protocols go through Azure Firewall. Use route tables (UDRs) and NSGs to direct traffic appropriately.

The exception is when you need to route traffic to Azure services, or Microsoft peered services available via express route. In these cases, you may need to bypass the proxy for specific domains or IP ranges

How Azure Functions Use Proxy Environment Variables

Azure Functions (and App Service) support standard proxy environment variables:

• ALL_PROXY or HTTPS_PROXY: URL of the proxy server for all outbound HTTP(S) traffic.

• NO_PROXY: Comma-separated list of hostnames, domains, or IPs to bypass the proxy (e.g., internal APIs, Azure services).

Example values:

ALL_PROXY: http://proxy.corp.local:8080
NO_PROXY: localhost, .azurewebsites.net, .loganalytics.net, .monitor.azure.com

Including domains like .azurewebsites.net, .loganalytics.net, and .monitor.azure.com in your NO_PROXY configuration is important because these are core Azure service endpoints that your Function App may need to communicate with directly. For example, .azurewebsites.net is used for platform management, Kudu (deployment), and internal service calls; .loganalytics.net is required for sending telemetry and diagnostic logs to Azure Monitor; and .monitor.azure.com is used for health checks and monitoring integrations. If these domains are routed through a corporate proxy, it can introduce latency, authentication issues, or even block critical platform operations. By explicitly bypassing the proxy for these domains, you ensure reliable connectivity to essential Azure services and avoid disruptions in monitoring, diagnostics, and platform management features. Remembering that NSG and firewall rules should also allow traffic to these domains is crucial.

Note: These variables are picked up by most language runtimes and libraries (e.g., .NET, Node.js, Python) automatically. No code changes are required—set them in the app configuration.

Default Network Behavior and Environment Proxy Variables

By default, outbound network traffic from Azure Function Apps is routed directly to the internet or through any configured virtual network and firewall, depending on your app’s networking setup. When you set environment variables like ALL_PROXY and NO_PROXY, the Azure Functions host and the underlying platform automatically use these values to determine which outbound HTTP(S) requests should be sent through a proxy and which should bypass it. This system-level approach ensures that all supported language runtime and libraries (such as .NET, Node.js, and Python) consistently honor your proxy configuration without requiring any changes to your application code. Using environment variables for proxy settings is preferred over hard-coding proxy logic in your function app because it centralizes control, reduces code complexity, and allows you to update proxy settings without redeploying or modifying your application. This method also aligns with enterprise security and compliance practices by ensuring that proxy policies are enforced uniformly across all workloads.

Setting Proxy Variables in Azure Function App Configuration

1. Go to your Function App in the Azure Portal.

2. Navigate to Configuration > Application settings.

3. Add ALL_PROXY and NO_PROXY as new application settings.

4. Save and restart the app.

This ensures all outbound HTTP(S) traffic from your function app uses the proxy, except for destinations listed in NO_PROXY.

Example: Enterprise Scenario

Suppose your organization requires all internet-bound HTTP(S) traffic to go through a proxy, but traffic to Azure Storage and internal APIs should bypass the proxy and go through Azure Firewall. You would:

• Set ALL_PROXY to your corporate proxy URL.

• Set NO_PROXY to include Azure service domains and internal address ranges.

• Use VNet integration and route tables to ensure non-HTTP(S) traffic is inspected by Azure Firewall.

CI/CD: Setting Proxy Variables in Azure DevOps Pipeline

To automate proxy configuration during deployment (e.g., zipdeploy), add the following to your Azure DevOps YAML pipeline:

- task: AzureFunctionApp@1
  displayName: 'Deploy Function App'
  inputs:
    azureSubscription: '$(azureSubscription)'
    appType: functionApp
    appName: '$(functionAppName)'
    package: '$(System.DefaultWorkingDirectory)/drop/yourapp.zip'
    appSettings: -ALL_PROXY "http://proxy.corp.local:8080" -NO_PROXY "localhost, .azurewebsites.net, .loganalytics.net"

This YAML snippet sets the proxy environment variables as application settings during the deployment process, ensuring they are applied without needing to modify your function app code.

If your proxy requirements change after deployment, you can update these environment variables directly in the Azure Portal or automate the update using Azure CLI or ARM/Bicep templates as part of your release process. This flexibility allows you to adapt to evolving network and security requirements without redeploying your application code.

Troubleshooting and Best Practices

• Test connectivity: Use the Kudu console or diagnostic tools to verify outbound connectivity and proxy usage.

• Monitor logs: Ensure your proxy and firewall logs are capturing expected traffic.

• Least privilege: Only allow required destinations in NO_PROXY.

• No code changes: Always prefer environment variable configuration over hardcoding proxy settings in code.

• Document and review exceptions: Maintain documentation of all domains and IPs included in your NO_PROXY configuration, and review them regularly to ensure they are still required and up to date with Microsoft’s published service tags.

Conclusion

Configuring proxy settings for Azure Function Apps in an enterprise environment is straightforward and robust when using environment variables and infrastructure-as-code. By combining proxy and firewall controls, you can meet security and compliance requirements without sacrificing developer productivity.

For more tips to manage your function app check out the microsoft documentation at learn.microsoft.com.

Why PowerShell + WPF?

While PowerShell is phenomenal for automation and scripting, sometimes a command-line interface isn't the most user-friendly option, particularly for less technical users. WPF provides a modern, flexible UI framework that can be seamlessly integrated with PowerShell scripts, giving you the best of both worlds:

• Rich, responsive user interfaces
• Access to PowerShell's powerful automation capabilities
• Professional-looking applications without needing to learn C# or Visual Studio

The Sample Application

Our demonstration application is a service desk utility that validates and submits user inputs to an Azure Function using a secret provided by the user. The app includes:

• Multiple input fields with different validation patterns
• Authentication
• Responsive UI feedback with a progress bar
• Error handling and validation messaging

Let's break down the key components.

Setting Up the WPF Environment

First, we need to load the necessary WPF assembly:

# Load required WPF assembly
Add-Type -AssemblyName PresentationFramework

Defining the UI with XAML

WPF uses XAML (eXtensible Application Markup Language) to define user interfaces. In PowerShell, we can define our XAML as a here-string:

[xml]$xaml = @"
<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        Title="Multi-Input - Authentication Demo" Height="500" Width="500">
    <!-- Window contents defined here -->
</Window>
"@

The XAML defines:

1. A window with grid layout
2. Text input fields for various data entries
3. A password box for secure input
4. Buttons for submitting data and quitting the application
5. A progress bar for visual feedback
6. A result area to display messages

Loading the XAML and Accessing UI Elements

After defining the XAML, we need to transform it into a live WPF window:

$reader = (New-Object System.Xml.XmlNodeReader $xaml)
$window = [Windows.Markup.XamlReader]::Load($reader)

# Retrieve controls by their names.
$Input1 = $window.FindName("Input1")
$Input2 = $window.FindName("Input2")
$Input3 = $window.FindName("Input3")
$Input4 = $window.FindName("Input4")
$PasswordInput = $window.FindName("PasswordInput") # PasswordBox control
$SubmitButton = $window.FindName("SubmitButton")
$QuitButton = $window.FindName("QuitButton")
$ProgressBar = $window.FindName("ProgressBar")
$ResultTextBlock = $window.FindName("ResultTextBlock")

The FindName method allows us to retrieve UI elements by their defined names in the XAML.

Input Validation with Regular Expressions

A highlight of our application is the ability to validate different inputs using specific regex patterns:

# Define regex patterns for validation
$regexPatternCase = '^(RITM|INC)\d{7}$'  # ServiceNow case format
$regexPatternEmail = '^[A-Za-z]+\.[A-Za-z]+@[A-Za-z]+\.com\.au$'  # Email format

The application uses these patterns to validate that:

• Input conforms to a ServiceNow case ID format (RITM or INC followed by 7 digits)
• Inputs follow an email format (firstname.lastname@domain.com.au)
• Other input validation like match a user ID, sAMAccountName or Department.

Event Handling in PowerShell WPF

WPF applications are event-driven. We add event handlers using PowerShell script blocks:

$SubmitButton.Add_Click({
    # Button click handling code
})

$QuitButton.Add_Click({
    $window.Close()
})

The Submit button's event handler contains the core logic of our application, while the Quit button simply closes the window.

Security Considerations: Handling Passwords

For secure input, we use the WPF PasswordBox control:

<PasswordBox Name="PasswordInput" Width="330" Height="25"/>

This displays input as asterisks, and doesn't hard code the secret.

This helps protect sensitive information in memory but ideally this would be handled using machine identities. In my use case I didn't have programmatic access to a secret store to retrieve the secrets, but if you In an Azure environment or have Arc enables machines this could be substituted.

Advanced Input Validation with PowerShell

Our application takes a sophisticated approach to validation by defining a collection of input definitions:

$inputs = @(
    @{ Control = $Input1; Label = "Input 1 (Case)"; Pattern = $regexPatternCase; GetValue = { param($ctrl) $ctrl.Text.Trim() } },
    @{ Control = $Input2; Label = "Input 2"; Pattern = $regexPatternEmail; GetValue = { param($ctrl) $ctrl.Text.Trim() } },
    @{ Control = $Input3; Label = "Input 3"; Pattern = $regexPatternEmail; GetValue = { param($ctrl) $ctrl.Text.Trim() } },
    @{ Control = $Input4; Label = "Input 4"; Pattern = $regexPatternEmail; GetValue = { param($ctrl) $ctrl.Text.Trim() } },
    @{ Control = $window.FindName("PasswordInput"); Label = "Client Secret"; Pattern = $null; GetValue = { param($ctrl) $ctrl.Password.Trim() } }
)

# Initialize a variable to store validation failures.
$validationFailures = @()

# Validate each input in the list.
foreach ($i in $inputs) {
    $value = & $i.GetValue $i.Control

    if ([string]::IsNullOrWhiteSpace($value)) {
        $validationFailures += "$($i.Label) failure: No value provided."
    }
    elseif ($i.Pattern -and -not [System.Text.RegularExpressions.Regex]::IsMatch($value, $i.Pattern)) {
        $validationFailures += "$($i.Label) failure: '$value' does not match the required pattern."
    }
}
# Additionally, validate the password field.
$passwordValue = $PasswordInput.Password.Trim()
if ([string]::IsNullOrWhiteSpace($passwordValue)) {
    $validationFailures += "Client Secret failure: No value provided."
}

# If there are any validation failures, output them and re-enable the button.
if ($validationFailures.Count -gt 0) {
    $ResultTextBlock.Text = ($validationFailures -join "`n")
    $ResultTextBlock.Foreground = [System.Windows.Media.Brushes]::Red
    $SubmitButton.IsEnabled = $true
    return
}

This approach allows for:

• Centralized validation logic
• Different validation rules for each input
• Specialized value extraction (notice how password values are handled differently)
• Captures null values
• Clear, descriptive error messaging

Keeping the UI Responsive

One common challenge in GUI applications is keeping the interface responsive during long-running operations. Our example addresses this using the Dispatcher:

$window.Dispatcher.Invoke([Action] {}, [System.Windows.Threading.DispatcherPriority]::Render)

This forces the UI to refresh after updating progress indicators, ensuring users see the current state of the application.

Making HTTP Requests from PowerShell WPF

The following code demonstrates making HTTP requests to an API endpoint using Bearer token authentication.

For context, this use case was the allow users to manually create an account which was only accessible from an API hosted in Azure.

We're using a service principle with App Role authorization to the API to authenticate. If you'd like more information of Entra Application authentication and bearer tokens I cover it here.

$tenant = "YOUR_TENANT_ID"
$appId = "YOUR_SERVICE_PRINCIPAL_APP_ID"
$secret = $passwordValue
$scope = "api://your-api-client-id/.default"

# Construct the token endpoint URL
$tokenEndpoint = "https://login.microsoftonline.com/$tenant/oauth2/v2.0/token"

# Define the body for the token request
$body = @{
    client_id     = $appId
    client_secret = $secret
    scope         = $scope
    grant_type    = "client_credentials"
}

# Request the token
$response = Invoke-RestMethod -Method Post -Uri $tokenEndpoint -Body $body
$accessToken = $response.access_token

# Use the access token to call an API
$headers = @{
    Authorization = "Bearer $accessToken"
}

# Example: Call your Azure Function App (update the URL accordingly).
$Uri = "https://<your-wep-app-name>.azurewebsites.net/api/CreateAccount"

# Build a payload including all inputs.
$payload = @{
  input1 = $Input1.Text.Trim()
  input2 = $Input2.Text.Trim()
  input3 = $Input3.Text.Trim()
  input4 = $Input4.Text.Trim()
} | ConvertTo-Json

Invoke-WebRequest -Method POST -Uri $Uri -Headers $headers -ContentType 'application/json' -Body $payload -UseBasicParsing

This illustrates how PowerShell GUI applications can interact with external services while maintaining a user-friendly interface.

Conclusion

This PowerShell WPF example demonstrates how administrators and developers can create sophisticated, user-friendly interfaces for their automation tools. By combining the flexibility of PowerShell with the rich UI capabilities of WPF, we can build professional applications that:

1. Validate user input with clear error messages
2. Provide visual feedback on progress
3. Handle passwords securely
4. Interact with external services
5. Present complex functionality through a simple interface The full code example includes additional features like preventing multiple submissions and properly reporting errors to users.

Whether you're building tools for service desk staff, administrators, or end users, PowerShell and WPF together provide a powerful platform for creating maintainable, effective GUI applications without leaving the PowerShell ecosystem.

You can find the code in full on GitHub

Thanks for reading! 🚀

The Challenge with Service Principal Authentication

When authenticating to Azure APIs using service principals, you typically need to:

1. Create an app registration in Entra
2. Generate and securely store a client secret
3. Request tokens using that secret

This approach works but has several drawbacks:

- Secrets require secure storage, rotation and governance
- Leaked secrets pose significant security risks
- Managing secret lifetimes adds operational overhead

Here's what a typical authentication flow using service principal credentials looks like:

# Define your tenant, client ID and client secret
$tenant = "YOUR_TENANT_ID"
$appId = "YOUR_SERVICE_PRINCIPAL_APP_ID"
$secret = "YOUR_SERVICE_PRINCIPAL_SECRET"
$scope = "api://your-api-client-id/.default"

# Construct the token endpoint URL
$tokenEndpoint = "https://login.microsoftonline.com/$tenant/oauth2/v2.0/token"

# Define the body for the token request
$body = @{
    client_id     = $appId
    client_secret = $secret
    scope         = $scope
    grant_type    = "client_credentials"
}

# Request the token
$response = Invoke-RestMethod -Method Post -Uri $tokenEndpoint -Body $body
$accessToken = $response.access_token

# Use the access token to call an API
$headers = @{
    Authorization = "Bearer $accessToken"
}

Invoke-WebRequest -Method POST -Uri "https://your-api-endpoint" -Headers $headers -ContentType 'application/json'

Introducing Azure Managed Identity

Managed Identity provides Azure resources with an automatically managed identity in Entra ID. This eliminates credential management completely, as Azure handles everything behind the scenes.

Benefits of Managed Identity

• No credential management: Azure creates and rotates credentials automatically

• Enhanced security: No secrets to store in code or configuration

• Simplified operations: No rotation schedules to maintain

• Seamless integration: Works natively with Azure services

How to Use Managed Identity for API Authentication

Step 1: Enable Managed Identity on Your Azure Resource

First, enable a system-assigned managed identity on your Azure VM, App Service, or other supported resource through the Azure Portal or via PowerShell/CLI.

Step 2: Grant the Managed Identity Access to Your Application

The managed identity operates as a service principal in Entra ID. You'll need to assign it appropriate permissions after identifying your Service Principals by Display Name or Application ID:

# Required Modules
Import-Module Az.Accounts
Import-Module Az.Resources

# Connect to Azure AD
Connect-AzAccount

# Get the managed identity's service principal
$managedIdentitySP = Get-AzADServicePrincipal -DisplayName "Your-VM-DisplayName"

# Get your API's service principal
$apiSP = Get-AzADServicePrincipal -ApplicationId "YOUR_API_APP_ID"

# Get your Application Role ID
$appRoleId = ($apiSP.AppRoles | Where-Object {$_.DisplayName -eq "YourRequiredRole"}).Id

# Assign the role to the managed identity
New-AzADServicePrincipalAppRoleAssignment `
    -ServicePrincipalId $managedIdentitySP.Id `
    -ResourceId $apiSP.Id `
    -AppRoleId $appRoleId

The assignment will be visible in Users and Group of the Enterprise Application

Step 3.1: Request a Token Using Managed Identity (Virtual Machine)

From within an Azure resource with managed identity enabled (like a VM), you can request a token using the local IMDS endpoint. The Instance Metadata Service (IMDS) provides a simple HTTP interface for obtaining tokens.

# Define your target resource/audience
$resource = "api://your-api-client-id"
$apiVersion = "2018-02-01"


# Construct the token request URL
$tokenUrl = "http://169.254.169.254/metadata/identity/oauth2/token?api-version=$apiVersion&resource=$([uri]::EscapeDataString($resource))"

# Request the token
$response = Invoke-RestMethod -Method GET -Uri $tokenUrl -Headers @{Metadata="true"}
$accessToken = $response.access_token

# Use the token to call your API
$headers = @{
    Authorization = "Bearer $accessToken"
}

Invoke-WebRequest -Method POST -Uri "https://your-service/endpoint" -Headers $headers -ContentType 'application/json'

You can find example code for different languages, and more information about managed identity access tokens here: https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-to-use-vm-token

Step 3.2: Request a Token Using Managed Identity (Web and Function Apps)

For Azure Web Apps and Function Apps, you can use the built-in endpoint to request a token once the managed identity is enabled. This is available through the IDENTITY_ENDPOINT and IDENTITY_HEADER environment variables. These are REST API endpoints that provide a simple way to obtain tokens. e.g. http://127.0.0.1:41854/MSI/token/, IDENTITY_HEADER is the secret used to authenticate the request.

# Define your target resource/audience
$resourceURI = "api://your-api-client-id"
$tokenAuthURI = $env:IDENTITY_ENDPOINT + "?resource=$resourceURI&api-version=2019-08-01"
$tokenResponse = Invoke-RestMethod -Method Get -Headers @{"X-IDENTITY-HEADER"="$env:IDENTITY_HEADER"} -Uri $tokenAuthURI
$accessToken = $tokenResponse.access_token

# Use the token to call your API
$headers = @{
    Authorization = "Bearer $($accessToken)"
}

Invoke-WebRequest -Method POST -Uri "https://your-service/endpoint" -Headers $headers -ContentType 'application/json'

If you would like more information on how to use managed identity in Azure Functions, or examples for other languages, you can refer to the official documentation

Troubleshooting Common Issues

401 Unauthorized Errors

If you receive a 401 Unauthorized response, check:

• Is the managed identity properly enabled?

• Has the identity been granted appropriate permissions (Roles) on your API?

• Are you requesting a token for the correct resource/audience?

415 Unsupported Media Type

This error indicates the API doesn't support the Content-Type of your request. Ensure you're setting the appropriate Content-Type header (e.g., 'application/json') that your API expects.

Detailed Error Information

For more detailed error information, use the -Verbose flag with your requests:

$webResponse = Invoke-WebRequest -Uri $apiUrl -Headers $headers -Method Get -Verbose

Or catch exceptions to see detailed error messages:

try {
    $response = Invoke-RestMethod -Uri $apiUrl -Headers $headers -Method Get
} catch {
    Write-Host "Error: $_"
    Write-Host "Status Code: $($_.Exception.Response.StatusCode.value__)"
}

Conclusion

Azure Managed Identity simplifies authentication flows, enhances security posture, and reduces operational overhead by eliminating credential management. By adopting managed identities for your inter-service authentication needs, you can build more secure and maintainable solutions in Azure.

This modern approach to authentication represents a significant improvement over traditional service principal authentication methods, particularly for services running within the Azure ecosystem.

What is Checkov?

Checkov is an open-source static code analysis tool designed to help developers prevent cloud misconfigurations during the build phase of infrastructure development. Developed by Bridgecrew (aquired by Palo Alto Networks in 2021), a company specializing in cloud security, Checkov is available under the Apache License 2.0, allowing anyone to freely use, modify, and distribute it. It supports scanning a variety of infrastructure as code (IaC) formats including Terraform, CloudFormation, Kubernetes, ARM Templates, and notably, Azure Bicep. A key advantage of Checkov is its native support for Azure Bicep, meaning it can directly scan Bicep files without needing to compile them into JSON format first. This capability enhances the “shift left” approach of DevSecOps by integrating security checks early into the development workflow, thus enabling developers to detect and rectify potential security issues before they become embedded in the deployment process. By using Checkov, teams can significantly reduce vulnerabilities and ensure robust compliance and security practices from the outset of their projects.

Benefits of Using Checkov with Azure Bicep

Checkov provides several advantages for teams working with Azure Bicep files, enhancing security and compliance throughout the development lifecycle:

• Prevention of Misconfigurations: By scanning Azure Bicep files, Checkov identifies potential security issues and misconfigurations before they are deployed, helping to prevent costly and risky errors in live environments.

• Comprehensive Policy Library: Checkov includes over 1000 built-in policies that cover a wide range of security best practices and compliance standards across multiple cloud providers, including Azure. This extensive library ensures that your infrastructure meets rigorous security and compliance benchmarks.

• Custom Policy Creation: Users have the flexibility to create custom policies in Checkov. This feature allows organizations to tailor the tool to meet specific security needs and organizational standards, providing a highly adaptable security solution.

• Seamless Integration: Checkov can be easily integrated into CI/CD pipelines, providing continuous security and compliance assessments without disrupting development workflows.

• Scanning for CVEs: Checkov performs Software Composition Analysis (SCA) to scan open source packages and container images for Common Vulnerabilities and Exposures (CVEs), adding an additional layer of security by identifying known vulnerabilities in dependencies.

These features make Checkov an invaluable tool for teams aiming to enhance the security and integrity of their Azure Bicep deployments.

Aligning Checkov with Azure Cloud Security Benchmarks

While Checkov provides extensive coverage of security best practices and compliance rules, its direct alignment with the Azure Cloud Security Benchmark might not be explicitly detailed for every rule. However, many of Checkov’s rules are broadly applicable to Azure and adhere to general security best practices that overlap significantly with Azure’s benchmarks. For organizations aiming to specifically meet Azure’s security standards, Checkov allows for the customization and extension of rules (defined in yaml), enabling teams to tailor security checks to the unique requirements of the Azure Cloud Security Benchmark or custom Azure Policy definitions. . This combination ensures a robust compliance and security strategy that is well-aligned with Microsoft’s cloud security benchmark (MCSB).

Integrating Checkov with GitHub Actions for Azure Bicep Scanning

Incorporating Checkov into your GitHub Actions workflow can significantly enhance the security posture of your Azure Bicep deployments. Checkov, a static code analysis tool (SCAT), scans infrastructure as code (IaC) for misconfigurations and potential security issues. Here’s how to set up Checkov with GitHub Actions for Azure Bicep files.

In this example, the Bicep file creates a storage account with public network access enabled and allows public access to blobs. Running Checkov on this file will flag these configurations as security issues, helping you identify and rectify potential vulnerabilities before deployment.

Workflow Setup

Start by defining the workflow in your repository’s .github/workflows folder. Here’s an effective configuration example:

name: Azure Bicep Template Analysis

on:
  pull_request:
    branches: [main]
  push:
    branches: [/release/*]

jobs:
  checkov-scan:
    runs-on: ubuntu-latest
    name: Checkov Bicep Analysis
    permissions:
      contents: read # Allows actions/checkout to fetch the code
      security-events: write # Allows github/codeql-action/upload-sarif to upload SARIF results

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Run Checkov Action
        id: checkov
        uses: bridgecrewio/checkov-action@v12
        with:
          directory: templates/
          quiet: true # Display only failed checks
          soft_fail: true # Do not return an error code if there are failed checks
          framework: bicep # Specify to run checks only on Azure Bicep templates
          output_format: sarif # Set output format to SARIF for integration with GitHub security tab
          output_file_path: results.sarif # Specify the file path for the SARIF output
          download_external_modules: true # Enable downloading external modules

      - name: Upload SARIF Results to GitHub
        if: always() # Ensure this step runs regardless of previous steps' success or failure
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Benefits of Using SARIF Output

• SARIF (Static Analysis Results Interchange Format) is a standard output format that enhances the interoperability between different security tools and services. By configuring Checkov to generate SARIF output, you can leverage GitHub’s native capabilities to display and manage security findings effectively:

• Centralized Security Findings: The SARIF file generated by Checkov is uploaded to GitHub where it integrates seamlessly within th pull request. This centralization makes it easier for teams to review, discuss, and remediate any detected issues directly within their development environment.

Next, define the bicep files you want to scan in the templates/ directory. You can adjust the directory parameter in the workflow configuration to match your repository’s structure. Once you’ve set up the workflow, every pull request targeting the main branch or any push to the release/* branches will trigger the Checkov scan for Azure Bicep templates.

param location string = resourceGroup().location

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: 'examplestorageaccount'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    publicNetworkAccess: 'Enabled'
    allowBlobPublicAccess: true
  }
}

After the workflow runs, validate that the Checkov scan results are displayed in the GitHub Security tab. This integration provides a clear overview of the security findings, allowing you to address any issues promptly.

The Checkov scan results are also populate in the pull request and highlight the offending resource:

Securing Infrastructure as Code with Advanced Compliance and Privacy Controls

Enterprises, particularly those operating within highly regulated industries or handling sensitive data, must prioritize robust security measures. The use of Checkov for scanning Azure Bicep files can be a cornerstone of such an approach, ensuring that infrastructure deployments are secure by design. However, for these organizations, using public GitHub Actions might not align with their stringent security protocols due to concerns about data privacy and unauthorized access.

A viable solution for these enterprises is to integrate Checkov within a privately hosted GitHub Actions runner. This setup combines the flexibility and power of GitHub Actions with the security controls that enterprises require. For instance, by using private runners, enterprises can ensure that their codebase and critical infrastructure configurations do not leave their controlled environments. Moreover, using paid solutions like Prisma Cloud Enterprise or Snyk IaC+ can further enhance this setup. Prisma Cloud, a comprehensive cloud security product, incorporates Checkov to provide advanced security scanning, compliance monitoring, and threat detection capabilities tailored to enterprise needs.

Conclusion

Using Checkov with GitHub Actions to scan Azure Bicep files introduces a robust layer of security to your infrastructure deployment practices. By automating the security scanning process, this integration ensures that your cloud resources are deployed not only efficiently but also with a high standard of security. This proactive approach significantly reduces the risk of deploying flawed or vulnerable infrastructure, thereby safeguarding your systems against potential threats.

As cloud environments grow in complexity, the integration of sophisticated tools like Checkov into CI/CD pipelines becomes indispensable. Such tools enable organizations to adhere to best practices effortlessly, ensuring continuous compliance and security. In summary, leveraging Checkov with GitHub Actions empowers organizations to maintain rigorous security standards while fully embracing the benefits of infrastructure as code. This is crucial for building resilient systems that can thrive in today’s dynamic and challenging digital landscape.

In this blog , we’ll explore how to improve the resiliency of your workloads using Azure Traffic Manager and Azure Chaos Studio. We’ll delve into the concepts of chaos engineering, Traffic Manager, and Chaos Studio, outlining their functionalities and how they work together to ensure application robustness. Additionally, we’ll provide a step-by-step guide for deploying Traffic Manager and Chaos Studio to test your workload’s ability to handle failures.

Chaos Engineering: Embracing Failure for Success

Chaos engineering is a proactive approach to building reliable systems. It involves intentionally introducing controlled disruptions (faults) to identify weaknesses and potential failure points in your application. By simulating real-world failure scenarios, chaos engineering helps you proactively strengthen your system’s ability to handle unexpected events.

Azure Chaos Studio: A Playground for Controlled Chaos

Azure Chaos Studio is a managed service specifically designed for chaos engineering within Azure. It provides a platform to define and execute experiments that introduce faults into your applications and infrastructure. Chaos Studio helps you:

• Identify vulnerabilities: By simulating failures, you can uncover hidden weaknesses in your system before they cause outages in production.

• Validate recovery mechanisms: Chaos Studio allows you to test your system’s ability to recover from failures, ensuring your redundancy and failover mechanisms function as expected.

• Build confidence in your deployments: By successfully navigating simulated failures, you gain confidence in your application’s ability to withstand real-world disruptions.

Azure Traffic Manager: A Balancing Act for Optimal Performance

Azure Traffic Manager is a DNS-based traffic routing service that distributes incoming traffic across your applications and services in a geographically optimal manner. It offers various routing methods, allowing you to tailor traffic flow based on your specific needs. Here’s how Traffic Manager contributes to workload resiliency:

• High Availability: Traffic Manager ensures traffic reaches a healthy endpoint even if one of your application instances becomes unavailable. It automatically routes requests to the remaining healthy instances, minimizing downtime and maintaining service continuity.

• Performance Optimization: Traffic Manager can route users to the closest available endpoint, reducing latency and improving user experience.

The Synergy of Chaos Studio and Traffic Manager

Chaos Studio and Traffic Manager work hand-in-hand to bolster your workload’s resilience. Chaos Studio helps you identify potential failure points in your application, while Traffic Manager provides a safety net by ensuring traffic continues to flow even during disruptions.

Here’s a scenario: Imagine you have an e-commerce application deployed across two regions. Using Chaos Studio, you can simulate a failure in one region. If you have Traffic Manager configured, it will automatically route traffic to the healthy region, minimizing the impact on your customers. By combining these tools, you can proactively build resilience into your system and ensure it can withstand real-world disruptions.

The Importance of Site Reliability Engineering (SRE) and Observability

Site Reliability Engineering (SRE) is a practice focused on building and maintaining highly reliable and scalable systems. Chaos engineering and Traffic Manager are valuable tools within the SRE toolbox. Observability, the ability to monitor and understand system behavior, plays a crucial role in chaos engineering.

By monitoring system behavior during chaos experiments, you can gain valuable insights into how your application handles faults. This information can be used to identify areas for improvement and enhance your system’s overall resilience.

Deploying Traffic Manager and Chaos Studio: A Step-by-Step Guide

Let’s walk through the process of deploying Traffic Manager and Chaos Studio to test your workload’s resiliency. As always, we’ll only be using the Portal as a visual aid to validate our progress and change. All steps will be complete using Azure CLI and Bicep templates.

Step 1: Check Azure Resource Providers

To check the registration status of Choas Studio on your subscripton, run the following command:

az provider list --query "[?namespace=='Microsoft.Chaos'].registrationState"

If you need to register the provider, run the following command:

az provider register --namespace Microsoft.Chaos

This can take between two to five minutes to complete. Rerun the az provider list query to confirm the registration has completed.

Step 2: Deploy Azure Web Apps

We’ll be using Azure Web Apps as our workload for this scenario. Deploy two web apps in different regions to simulate a multi-region deployment. Note: Chaos Studio endpoints aren’t available in all regions, so ensure your web apps are deployed in supported regions here.

We’ll be using the following Bicep template to deploy the web apps:

resource asp 'Microsoft.Web/serverfarms@2023-01-01' = {
  name: aspName
  location: location
  properties: {
    reserved: true
  }
  sku: {
    name: 'S1'
    tier: 'Standard'
    size: 'S1'
    family: 'S'
    capacity: 1
  }
  kind: 'linux'
}

resource webapp 'Microsoft.Web/sites@2023-01-01' = {
  name: webAppName
  location: location
  kind: 'linux'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${umi.id}': {}
    }
  }
  properties: {
    enabled: true
    // required for the webapp to REALLY be linux. If this is set to false
    // the webapp will be Windows, even though the Kind is set to linux.
    reserved: true
    serverFarmId: asp.id
    publicNetworkAccess: 'Enabled'
    siteConfig: {
      acrUseManagedIdentityCreds: true
      acrUserManagedIdentityID: umi.properties.clientId // not the resource id!
      numberOfWorkers: 1
      linuxFxVersion: 'DOCKER|${acrName}.azurecr.io/${appName}:${appVersion}'
      healthCheckPath: '/'
      alwaysOn: true
    }
  }
}

The container image is stored in an Azure Container Registry (ACR). Ensure you have the necessary configurations in place to pull the image during deployment. I covered this in a previous blog post, Deploying Azure Web Apps with Azure Container Registry.

Step 3: Create a Chaos Studio Endpoints

Next, we’ll create Chaos Studio endpoints for our web apps. This will allow Chaos Studio to interact with our web apps during experiments. We’ll use the following Bicep template to create the endpoints:

resource target_appservice 'Microsoft.Chaos/targets@2024-01-01' = {
  scope: webapp
  name: 'microsoft-appservice'
  location: location
  properties: {}
  dependsOn: []
}

resource microsoft_appservice_Stop_1_0 'Microsoft.Chaos/targets/capabilities@2024-01-01' = {
  parent: target_appservice
  name: 'Stop-1.0'
}

Stop-1.0 is a capability that allows Chaos Studio to stop the web app. You can define additional capabilities based on your requirements. See the full list of capabilities here for more information. Some of the capabilities include simulating high CPU usage, network latency, and disk I/O, just to name a few. Most of capabilities are limited to VM/VMSS (AKS) workloads however.

The scope property in the target_appservice resource should be set to the resource ID of the web app you want to target. This will allow Chaos Studio to interact with the web app during experiments.

Maintaining the Chaos Studio endpoint within the same module as the web app resources simplifies management and enhances code readability. However, you have the option to organize the endpoint in a separate module, should that better suit your architectural preferences.

Step 4: Role Based Access Control (RBAC)

To allow Chaos Studio to interact with your web apps, you’ll need to grant the necessary permissions to stop the web app site. This requires the Microsoft.Web/sites/restart/Action, Microsoft.Web/sites/start/Action and Microsoft.Web/sites/Read permissions. Using the principle of least privilege, you can create a custom role with these permissions and assign it to the Chaos Studio service principal. However, for the sake of simplicity, we’ll use the built-in Website Contributor role for this example.

Now that we’ve laid the groundwork for our experiment, let’s move on to the Traffic Manager configuration.

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(resourceGroup().id, umi.name, 'Website Contributor')
  scope: webapp
  properties: {
    principalType: 'ServicePrincipal'
    principalId: umi.properties.principalId
    roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', 'de139f84-1756-47ae-9be6-808fbbe84772')
  }
}

Step 5: Deploy Traffic Manager

Deploy Traffic Manager to route traffic to the web apps in different regions. We’ll use the following Bicep template to create the Traffic Manager profile:

resource webappAUE 'Microsoft.Web/sites@2023-01-01' existing = {
  scope: resourceGroup(aue_rg)
  name: webAppNameAUE
}

resource webappSEA 'Microsoft.Web/sites@2023-01-01' existing = {
  scope: resourceGroup(sea_rg)
  name: webAppNameSEA
}

resource trafficManagerProfiles 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = {
  name: profilesName
  location: 'global'
  properties: {
    profileStatus: 'Enabled'
    trafficRoutingMethod: 'Priority'
    dnsConfig: {
      relativeName: profilesName
      ttl: 5
    }
    monitorConfig: {
      protocol: 'HTTPS'
      port: 443
      path: '/'
      intervalInSeconds: 30
      toleratedNumberOfFailures: 3
      timeoutInSeconds: 10
    }
    endpoints: [
      {
        name: '${webAppNameAUE}-endpoint'
        type: 'Microsoft.Network/trafficManagerProfiles/azureEndpoints'
        properties: {
          endpointStatus: 'Enabled'
          endpointMonitorStatus: 'Online'
          targetResourceId: webappAUE.id
          weight: 1
          priority: 1
          endpointLocation: 'Australia East'
          alwaysServe: 'Disabled'
        }
      }
      {
        name: '${webAppNameSEA}-endpoint'
        type: 'Microsoft.Network/trafficManagerProfiles/azureEndpoints'
        properties: {
          endpointStatus: 'Enabled'
          endpointMonitorStatus: 'Online'
          targetResourceId: webappSEA.id
          weight: 1
          priority: 2
          endpointLocation: 'Southeast Asia' // Chaos Studio not available in 'Australia SouthEast'
          alwaysServe: 'Disabled'
        }
      }
    ]
    trafficViewEnrollmentStatus: 'Disabled'
  }
}

In this template, we’re creating a Traffic Manager profile with two endpoints: one for each web app in different regions. The trafficRoutingMethod is set to Priority, meaning traffic will be routed to the endpoint with the highest priority (lowest number) that is healthy. The monitorConfig section defines the health check settings for the endpoints.

Step 6: Deploy Chaos Studio Experiments

Now that we have our web apps, Chaos Studio endpoints, and Traffic Manager in place, we can create a Chaos Studio experiment to test the resiliency of our workload. We’ll use the following Bicep template to define the experiment:

resource umi 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-07-31-preview' existing = {
  name: umiName
}

resource choasStudio 'Microsoft.Chaos/experiments@2024-01-01' = {
  name: 'dev-aue-cs'
  location: location
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${umi.id}': {}
    }
  }
  properties: {
    selectors: [
      {
        type: 'List'
        targets: [
          {
            id: extensionResourceId(resourceId(aue_rg,'Microsoft.Web/sites',webAppNameAUE),'Microsoft.Chaos/targets','microsoft-appservice')
            type: 'ChaosTarget'
          }
          {
            id: extensionResourceId(resourceId(sea_rg,'Microsoft.Web/sites',webAppNameSEA),'Microsoft.Chaos/targets','microsoft-appservice')
            type: 'ChaosTarget'
          }
        ]
        id: 'ReferenceThisSelector'
      }
    ]
    steps: [
      {
        name: 'Step 1: Failover an App Service web app'
        branches: [
          {
            name: 'Branch 1: Emulate an App Service failure'
            actions: [
              {
                type: 'continuous'
                selectorId: 'ReferenceThisSelector'
                duration: 'PT10M'
                parameters: []
                name: 'urn:csci:microsoft:appService:stop/1.0'
              }
            ]
          }
        ]
      }
    ]
  }
}

In the experiment, we’re targeting the Chaos Studio endpoints we created earlier. The experiment consists of a single step that emulates an App Service failure by stopping the web app. The experiment runs for 10 minutes, allowing us to observe how Traffic Manager responds to the failure and routes traffic to the healthy endpoint.

We’re also assigning the user-assigned identity (UMI) to the Chaos Studio experiment we created earlier.

For reference you can find the pipelines and code in my repo:

https://github.com/broberts23/workload-resiliency

Validation

We’re finally at the point where we can validate our setup! To do this, we’ll run the Chaos Studio experiment and observe the behavior of Traffic Manager. You can monitor the experiment’s progress and view the results in the Chaos Studio portal.

After starting the experiment, we can verify that the web app in the affected region has stopped and that Traffic Manager has successfully routed traffic to the healthy endpoint. This demonstrates the resiliency of our workload and the effectiveness of our Traffic Manager configuration.

Conclusion

In today’s dynamic and interconnected digital landscape, ensuring the resiliency of cloud workloads is crucial for maintaining business continuity and delivering exceptional user experiences. Technologies like Azure Chaos Studio and Azure Traffic Manager provide organizations with powerful tools to validate system resilience, optimize application availability, and mitigate the impact of failures. By embracing chaos engineering principles, leveraging traffic management solutions, and adopting SRE practices, organizations can build more resilient, scalable, and reliable cloud-based applications.

Overview of Custom Script Extension

The Azure Custom Script Extension is a powerful tool designed to streamline the execution of custom scripts on Azure virtual machines. This facilitates a variety of tasks such as post-deployment configurations, software installations, and other system customization. It supports a wide range of scripting languages, including PowerShell and Azure CLI, and integrates seamlessly with domain-specific languages (DSLs) such as Ansible, Bicep, and Terraform. Scripts can be sourced from Azure Storage, GitHub, or any accessible URL, ensuring flexibility across different deployment scenarios.

Key Features

• Script Execution: The extension can execute scripts stored in locations like Azure Storage or GitHub, or directly from a specified URL.

• Secure Execution: Scripts are executed using Azure Managed Identity, enhancing security by eliminating the need for explicit credentials.

• Script Output Logging: Detailed logs are provided for script outputs, aiding in troubleshooting and audit processes.

• Versioning and Updating: Scripts can be version-controlled and updated seamlessly, ensuring consistency across deployments.

For more Features and Tips for Custom Script Extension, refer to the Azure documentation.

It’s important to keep in mind that the Custom Script Extensions executes scripts directly on the VM, inheriting the VM’s permissions and environment. Authentication mechanisms and network connectivity should be carefully managed to access internal and external resources securely.

Custom Script Extension Use Cases

Custom Script Extensions (CSE) offer a versatile way to enhance and automate the configuration and management of Azure virtual machines (VMs) and virtual machine scale sets (VMSS). Here are several practical use cases where Custom Script Extensions can be particularly beneficial:

Enhancing a Base or Golden Image

• Scenario: When deploying VMs from a standardized base image (often referred to as a “golden image”), it might lack specific software or configuration tweaks needed for particular applications or environments.

• Use Case: Use a Custom Script Extension to automatically install additional software packages, apply security patches, or configure system settings after the VM is instantiated from the golden image. This ensures that each deployed VM is immediately tailored to meet specific operational requirements without manual intervention.

Automated Software Deployment

• Scenario: Continuous Integration/Continuous Deployment (CI/CD) environments require frequent updates and consistent configurations across multiple VMs.

• Use Case: Integrate Custom Script Extensions to deploy the latest version of your application automatically or perform necessary pre-deployment and post-deployment tasks such as configuring software or updating dependencies.

Environment Configuration

• Scenario: Different environments (development, testing, production) often require different configurations and settings to function correctly.

• Use Case: Use Custom Script Extensions to modify configuration files, adjust environment variables, or execute scripts that tailor the VM’s environment to fit its intended role. This can include setting up database connections, configuring logging levels, or modifying network settings.

Security Hardening and Compliance

• Scenario: Ensuring that VMs comply with organizational or regulatory security standards is crucial but can be time-consuming if performed manually.

• Use Case: Automate the process of hardening VMs by using Custom Script Extensions to apply security configurations, install security tools, enforce password policies, and disable unnecessary services. Scripts can be maintained in a central repository and updated as standards evolve.

Performance Tuning

• Scenario: Optimal performance tuning often requires adjustments that are specific to the workload or the software that the VM is hosting.

• Use Case: Deploy scripts via Custom Script Extensions to tweak system parameters such as memory management settings, networking stack adjustments, or disk I/O performance settings. These enhancements can be crucial for performance-sensitive applications like databases or large-scale transaction systems.

Custom Script Extension vs. PowerShell Desired State Configuration

When it comes to automating configurations and managing Azure virtual machines, both Custom Script Extensions (CSE) and PowerShell Desired State Configuration (DSC) are powerful tools. While CSE focuses on executing scripts to configure VMs during deployment or post-deployment, DSC takes a declarative approach to define and maintain a desired state for a VM’s configuration. DSC uses a declarative syntax to specify how a system should be configured, and it continuously ensures that the system remains in the desired state. On the other hand, CSE is imperative, executing scripts at specific points in time. DSC is particularly useful for ongoing configuration management and drift prevention, while CSE excels at one-time setup tasks and ad-hoc customization. However, CSE can also be used for ongoing management by triggering script execution on a schedule or in response to events. Ultimately, the choice between CSE and DSC depends on the specific requirements, with CSE offering flexibility and simplicity, and DSC providing a robust framework for maintaining consistent configurations over time. While powerful, PowerShell DSC can introduce complexity due to the requirement of packaging configurations, and deploying them through Azure Machine Configuration (Guest Configuration).

Deployment Process

• Script Preparation: Write a PowerShell script tailored to meet the specific deployment needs, such as software installation or system configuration.

• Integration with ARM Templates: Embed the Custom Script Extension in an Azure Resource Manager (ARM) template, specifying the script to be executed during the VM setup.

• Deployment via Azure Portal and Tools: Deploy the VM through the Azure Portal, Azure CLI, or Azure PowerShell. The Custom Script Extension will automatically execute the PowerShell script post-deployment.

• Monitoring and Troubleshooting: Use tools like Azure Portal or Azure CLI to monitor the deployment and troubleshoot any potential issues.

Best Practices and Considerations

• Script Idempotency: Design scripts so they can be safely rerun multiple times, which is essential for handling retries and resuming interrupted deployments.

• Error Handling: Scripts should include comprehensive error handling to manage failures and, if necessary, revert changes.

• Security Measures: Employ Azure Key Vault for managing sensitive data, use Managed Identity for script execution, and ensure scripts are accessible only to authorized users.

• Version Control: Maintain scripts under version control to track modifications and facilitate rollbacks when needed.

• Testing and Validation: Thoroughly test scripts in a non-production environment to confirm their functionality and identify any issues before widespread deployment.

Example Scenario: Automating IIS Deployment with Custom Script Extension

Consider a scenario where we need to automate a website/app deployment on an Azure VM. Using Custom Script Extension with PowerShell, here’s how you might achieve this:

# PowerShell script for automating IIS installation
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

# Define configuration settings
$contentPath = "$Env:systemdrive\inetpub\wwwroot"
$gitHubRepoUri = "https://raw.githubusercontent.com/cloudacademy/static-website-example/master/index.html"

# Install IIS Role and Features
<#PSScriptInfo
.Synopsis
   Powershell script for Azure Bicep VM Extension to configure a Windows Web Server
.INPUTS
   No inputs are required for this script
.OUTPUTS
   No outputs are generated by this script
.NOTES
  Version:        0.1
  Author:         Ben Roberts
  Creation Date:  17/04/2024
  Purpose/Change: Initial script development
.
#>

# Update Script Execution Policy (temporarily allow script execution)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

# Define Configuration Settings (replace with your values)
$contentPath = "$Env:systemdrive\inetpub\wwwroot"
$gitHubRepoUri = "https://raw.githubusercontent.com/cloudacademy/static-website-example/master/index.html"

# Install IIS Role and Features
Try {
  Install-WindowsFeature -Name Web-Server -IncludeManagementTools
  Write-Host "IIS Role and Features installed successfully"
}
Catch {
  Write-Host $Error[0].Exception.Message
}

try {
  # Download static website content
  Invoke-WebRequest -Uri $gitHubRepoUri -OutFile "$contentPath\Default.htm"
  Write-Host "Website content cloned successfully"
}
catch {
  Write-Host $Error[0].Exception.Message
}

try {
  # Disable Unused Services
  $unusedServices = @("tapisrv", "WMPNetworkSvc", "ssh-agent")
  Stop-Service $unusedServices -ErrorAction SilentlyContinue
  Set-Service $unusedServices -StartupType Disabled
}
catch {
  Write-Host $Error[0].Exception.Message
}

try {
  # Configure Windows Firewall
  New-NetFirewallRule -DisplayName "Allow Inbound Port 80" -Direction Inbound -LocalPort 80 -RemotePort 80 -Protocol TCP -Action Allow
  Write-Host "Firewall rule configured successfully"
}
catch {
  Write-Host $Error[0].Exception.Message
}
# Update Script Execution Policy (revert to previous policy)
Set-ExecutionPolicy Bypass -Scope CurrentUser -Force

# Restart IIS service to apply configuration changes
Restart-Service W3SVC

For deployment, this script is integrated into a Bicep template that specifies the Custom Script Extension to execute the script on the Azure VM:

@description('VM Extension Properties.')
param extentionsProperties object = {
  extensionName: 'IIS'
  publisher: 'Microsoft.Compute'
  type: 'CustomScriptExtension'
  typeHandlerVersion: '1.10'
}

@description('Command to execute on the Virtual Machine.')
param commandToExecute string = 'powershell -File ConfigureWebServer_base.ps1'

resource vmExtension 'Microsoft.Compute/virtualMachines/extensions@2023-09-01' = {
  parent: vm
  name: extentionsProperties.extensionName
  location: location
  properties: {
    publisher: extentionsProperties.publisher
    type: extentionsProperties.type
    typeHandlerVersion: extentionsProperties.typeHandlerVersion
    autoUpgradeMinorVersion: true
    settings: {
      fileUris: [
        // Uri derived from the output of the deployment script: See uploadBlob.ps1
        deploymentScript.outputs.result
      ]
      commandToExecute: commandToExecute
    }
  }
}

For brevity I’ve omitted all the supporting configuration including the VM, VNET, Nic, Managed Identity, etc.

If you want the full context you can view the code here: https://github.com/broberts23/azure-automation-dsc

If you’re wondering what the heck deploymentScript.outputs.result is, checkout my blog on Bicep Deployment Scripts where we uploaded the powershell script we’re consuming in the fileUris property:

Deploying the Bicep Template

To deploy the Bicep template with the Custom Script Extension, we’ll be using a GitHib Action workflow. The workflow will, validate the Bicep file, and deploy the template to Azure, then for a little something extra, verify the website is up.

name: Bicep Deployment and Pester Test

on:
  workflow_dispatch:

# OICD Auth
permissions:
  id-token: write
  contents: read

env:
  resource-group: RG1 # name of the Azure resource group
  rollout-name: rollout01 # name of the deployment
  environment: dev

jobs:
  validate:
    name: Validate Bicep template
    runs-on: ubuntu-latest
    environment: dev
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Login via Azure CLI
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Bicep Validate
        id: validate
        uses: azure/CLI@v2
        with:
          azcliversion: latest
          inlineScript: |
            az deployment group validate --resource-group ${{ env.resource-group }} --name  ${{ env.rollout-name }} --template-file vm_dsc.bicep --parameters adminPassword=${{ secrets.ADMINPASSWORD }}


  deploy_and_test:
    name: Deploy and Test
    runs-on: ubuntu-latest
    environment: dev
    needs: [validate]
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Login via Azure CLI
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Deploy Bicep template
        id: deploy
        uses: azure/CLI@v2      
        with:
          azcliversion: latest
          inlineScript: |
            az deployment group create --resource-group ${{ env.resource-group }} --name  ${{ env.rollout-name }} --template-file vm_dsc.bicep --parameters adminPassword=${{ secrets.ADMINPASSWORD }}
            # Get the public IP address of the deployed VM from the bicep output
            publicIP=$(az deployment group show --resource-group ${{ env.resource-group }} --name  ${{ env.rollout-name }} --query 'properties.outputs.publicIP.value' -o tsv)
            echo "publicIP=$publicIP" >> $GITHUB_OUTPUT

      - name: Testing Website Accessibility
        uses: azure/powershell@v2
        with:
          azPSVersion: "latest"
          inlineScript: |
            Import-Module Pester
            $url = "http://${{ steps.deploy.outputs.publicIP }}"
            Describe "Website Accessibility Test" {
                It "Website should be accessible" {
                    $response = Invoke-WebRequest -Uri $url -UseBasicParsing -ErrorAction SilentlyContinue
                    $response.StatusCode | Should -Be 200
                }
            }

Conclusion

The Custom Script Extension, when combined with Bicep, provides a powerful solution for automating and streamlining cloud deployments in Azure. By leveraging this approach, IT administrators and DevOps teams can ensure more consistent, secure, and efficient deployment processes. The example provided here demonstrates just one of the myriad possibilities, encouraging users to explore this tool-set for diverse automation tasks in Azure environments.

I hope you enjoyed this blog post and found it valuable. Stay tuned for more insights and tutorials on cloud computing, automation, and infrastructure management. Happy automating!

What are Bicep Deployment Scripts?

Bicep Deployment Scripts are essentially PowerShell or Azure CLI scripts that streamline, enhance or augment the deployment process of Azure resources using Bicep resources. They offer a cleaner and more concise way to execute command in-stream of the deployment process, making it easier to define and deploy Azure resources. Deployment scripts can be used to automate the provisioning of Azure resources, configure settings, and execute custom actions during deployment that can then be referenced in the Bicep template by other resources and/or modules.

Deployment scripts execute in a Container Instance and Storage Account which are created as part of the deployment process. Note that there are costs associated with the Container Instance and Storage Account, so be mindful of which properties you use to delete or keep the resources after deployment.

Why Bicep?

First off, if you’re not familiar with Bicep, imagine ARM json templates but with a much friendlier syntax. Bicep simplifies the process of defining Azure resources by providing a more readable and maintainable format. If you’ve ever felt overwhelmed by the complexity of ARM templates, Bicep is your ticket to a smoother deployment experience.

Getting Started with Bicep Deployment Scripts

To kick things off, make sure you have the PowerShell and Bicep installed on your machine or developer environment. Once you’re all set up, writing your first Bicep Deployment Script is a breeze. In this example, we’ll create a simple Bicep module that executes a simple PowerShell script that uploads a file we’ll use in an upcoming blog. Below is a snippet of the Bicep module, i’ve omitted the supporting resources (User Assigned Identity, VNET’s, Storage Account, etc.) from the snippet for brevity:

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlinePS'
  location: location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned' // User Assigned Identity for the Deployment Script to access the Storage Account
    userAssignedIdentities: {
      '${umi.id}': {}
    }
  }
  properties: {
    azPowerShellVersion: '11.4'
    retentionInterval: 'PT1H'
    cleanupPreference: 'OnSuccess'
    environmentVariables: [
      {
        name: 'AZURE_STORAGE_ACCOUNT'
        value: storageAccount.name
      }
      {
        name: 'CONTENT' // Imports the content of a file - in this case, another
        // PowerShell script - that will be uploaded to the Storage Account
        // This is stored in an Environment Variable as a string
        value: loadTextContent('ConfigureWebServer_base.ps1')
      }
      {
        name: 'AZURE_RESOURCE_GROUP'
        value: resourceGroup().name
      }
    ]
    // arguments: saName
    scriptContent: loadTextContent('uploadBlob.ps1')
  }
  dependsOn: [
    // This ensures that the Storage Account and role assignment are created before the deployment script
    roleAssignment
  ]
}

output result string = deploymentScript.properties.outputs.text.ICloudBlob.Uri

In this module, we define a deploymentScript resource that executes an Azure PowerShell script (uploadBlob.ps1) via the scriptContent property. The environment variables are used to pass parameters to the script, such as the Storage Account name and the content of the file. The loadTextContent function is used to import the content of both PowerShell scripts (plain text) from local files and store them as an environment variables.

Note the cleanupPreference property is set to ‘OnSuccess’, which means the Container Instance and Storage Account created to execute the script will only be deleted after a successful execution. This is handy for troubleshooting a failing script, you won’t have to wait for the container instance to be created on subsiquent runs. However, this might not be ideal at scale as developers could leave failed deployments undeleted, leading to wasted spend.

Let’s have a quick look at the PowerShell script called by scriptContent:

<#PSScriptInfo
.Synopsis Powershell script to upload a file to a blob storage account
.INPUTS The input to this script are the environment variables set by the DeploymentScript Bicep resource
.OUTPUTS The output of this script is returned as a DeploymentScript output ($DeploymentScriptOutputs) as the 'text' key. This is later interpreted by the DeploymentScript to get the Uri of the uploaded file.
.NOTES
Version: 0.1
Author: Ben Roberts
Creation Date: 17/04/2024
Purpose/Change: Initial script development
#>

# Connect to Azure using Managed Identity defined in the Deployment Script resource
try {
    Connect-AzAccount -Identity
} catch {
    Write-Host "Failed to connect to Azure"
    exit 1
}

# Get the storage account context
$saContext = Get-AzStorageAccount -Name "${env:AZURE_STORAGE_ACCOUNT}" -ResourceGroupName "${env:AZURE_RESOURCE_GROUP}"
$workingContext = $saContext.Context

# Output the script from the environment variable to a file
Write-Output "${env:CONTENT}" > ConfigureWebServer_base.ps1

# Upload the file to the blob storage account
try {
    $output = Set-AzStorageBlobContent -File ConfigureWebServer_base.ps1 -Container dsc -Blob ConfigureWebServer_base.ps1 -Context $workingContext -Force
} catch {
    Write-Host $Error[0].Exception.Message
}

# Output the results to the built-in DeploymentScript variable using the 'text' key
$DeploymentScriptOutputs = @{}
$DeploymentScriptOutputs['text'] = $output # See results.json for an example of $output

This script authenticates to Azure using the Managed Identity defined in the Deployment Script resource, retrieves the Storage Account context, and uploads the content of the second PowerShell script to a container in the Storage Account. The output of the script is stored in the $DeploymentScriptOutputs variable, which is a common variable that can be accessed by the DeploymentScript resource and surfaced by Azure Resource Manager. This can be referenced in the Azure portal, or using the Azure PowerShell cmdlet Get-AzDeploymentScript

Deployment Scripts Outputs

The output is stored in the text key of the $DeploymentScriptOutputs variable, which can be output to a variable in the Bicep template. This allows you to reference the output of the script in other resources or modules.

output result string = deploymentScript.properties.outputs.text.ICloudBlob.Uri

deploymentScript.properties.outputs.text is a JSON object. We can access the ICloudBlob.Uri property to get the URI of the uploaded file. This output can then be used in other resources or modules to reference the uploaded file by using deploymentScript.outputs.resut. We’ll make use of this in an upcoming blog.

Multi-line Scripts

As an alternative to the passing the deployment script as a ps1 file, you can also pass the script as a multi-line string in the Bicep by using three quotes `”’`. This can be useful for small scripts that don’t require a separate file. Here’s an example of how you can define a multi-line script in a Bicep file:

param storageAccountName = 'myStorageAccount'
param rgName = resourceGroup().name

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlinePS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azCliVersion: '11.4'
    arguments: '-name ${storageAccountName} -rgName ${rgName}'
    scriptContent: '''
      param (
        [string] $name,
        [string] $rgName
      )
      $output = az storage account create -n $name -g $rgName --sku Standard_LRS
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
  }
}

output result object = deploymentScript.properties.outputs.text

Idempotent Scripts

Deployment script execution is designed to be idempotent, meaning that if there are no changes to any of the deploymentScripts resource properties, including the inline script, the script will not run upon redeployment of the Bicep file. The deployment script service compares resource names in the Bicep file with existing resources in the same resource group.

To run the same deployment script multiple times, you have two options: either change the name of your deploymentScripts resource, perhaps using the utcNow function as the resource name or as part of it (note that utcNow can only be used in the default value for a parameter), changing the resource name (“inlinePS” in my example) creates a new deploymentScripts resource; or specify a different value in the forceUpdateTag property, such as utcNow.

Writing deployment scripts with idempotence in mind ensures that accidental reruns won’t lead to unintended system alterations. For instance, let’s say you’re deploying an Azure virtual machine using a deployment script. Before creating the VM, the script should check if a VM with the same name already exists. If it does, the script can either skip VM creation or delete the existing VM and recreate it with updated configurations. This approach guarantees that running the script multiple times won’t result in duplicate VMs or unexpected changes to existing ones, maintaining system integrity and minimizing errors in the deployment process.

Conclusion

Bicep Deployment Scripts are a game-changer for Azure resource deployment. By combining the simplicity of Bicep with the power of PowerShell, you can streamline your deployment process and automate complex workflows with ease. Whether you’re a seasoned Azure pro or just getting started, Bicep Deployment Scripts are a must-have tool in your arsenal.

Stay tuned for the next blog post where we’ll explore how to use Custom Script Extension to deploy a custom web server configuration to an Azure VM, using the PowerShell script we just uploaded to the Storage Account. Until then, happy coding!

We will explore AVM and how you can use them to simplify your Azure deployments.

What are Azure Verified Modules?

Azure Verified Modules are pre-built Terraform and Bicep modules that are designed to automate the deployment and configuration of Azure services. These modules are built using best practices and are verified by the Azure team to ensure they are secure, reliable, and efficient.

Azure Verified Modules are available in the Bicep Registry and can be easily imported into your Bicep configuration files. These modules can be used to deploy a wide range of Azure services, including virtual machines, storage accounts, databases, and many more.

What are we building?

I’m working on a series of blogs where I need working web applications. I will be using container hosting services like Azure Container Instances, Azure Container Apps and Azure Kubernetes Service to host these applications. In this blog, I will be using AVM to deploy an Azure Container Registry, Managed Identity an VNET, then use GitHub Actions to deploy the infrasctucture resources and build then push a container image to the Azure Container Registry as a peice of reusable code I can run on-demand.

Building the Azure Container Registry using Verified Modules

To get started, we need to deploy an Azure Container Registry using AVM. The Azure team and community have created excellent documentation on how to use AVM, and I will be following the steps outlined in the Azure Container Registry module documentation.

Here is the Bicep code to deploy the Azure Container Registry and supporting resources using AVM:

param location string
param environment string

var acrName = '${environment}acr${uniqueString(resourceGroup().id)}'
var vnetName = '${environment}-vnet-${uniqueString(resourceGroup().id)}'
var umiName = '${environment}-umi-${uniqueString(resourceGroup().id)}'

module userAssignedIdentity 'br/public:avm/res/managed-identity/user-assigned-identity:0.2.1' = {
  name: 'userAssignedIdentityDeployment'
  params: {
    name: umiName
    location: location
  }
}

module virtualNetwork 'br/public:avm/res/network/virtual-network:0.1.5' = {
  name: 'virtualNetworkDeployment'
  params: {
    addressPrefixes: [
      '10.0.0.0/16'
    ]
    name: vnetName
    location: location
    subnets: [
      {
        addressPrefix: '10.0.0.0/24'
        name: 'az-subnet-001'
        privateEndpointNetworkPolicies: 'Disabled'
        privateLinkServiceNetworkPolicies: 'Enabled'
      }
      {
        addressPrefix: '10.0.1.0/24'
        name: 'az-subnet-002'
      }
      {
        addressPrefix: '10.0.3.0/24'
        name: 'az-subnet-003'
      }
    ]
  }
}

module registry 'br/public:avm/res/container-registry/registry:0.1.1' = {
  name: 'registryDeployment'
  params: {
    managedIdentities: {
      systemAssigned: false
      userAssignedResourceIds: [
        userAssignedIdentity.outputs.resourceId
      ]
    }
    name: acrName
    acrAdminUserEnabled: false
    acrSku: 'Premium'
    publicNetworkAccess: 'Enabled'
    softDeletePolicyStatus: 'disabled'
    exportPolicyStatus: 'enabled'
    location: location
    tags: {
      Environment: environment
      'hidden-title': 'Container Registry'
      Role: 'DeploymentValidation'
    }
  }
}

In this code snippet, we are deploying an Azure Container Registry with a Premium SKU, enabling the export policy, and disabling the soft delete policy. We are also deploying a virtual network with three subnets and a user-assigned managed identity. The managed identity is used to authenticate the Azure Container Registry to future resources.

I’ve reduced the parameters and variables to a minimum to keep the code as readable as possible.

br/public is the namespace for AVM, and the avm/res/container-registry/registry module is used to deploy the Azure Container Registry. The module takes several parameters, including the name of the Azure Container Registry, the location, the SKU, and the network access settings.

A major benefit of using AVM is tab completion and/or Intellisense in your IDE. This makes it easier to discover the available modules versions, and their parameters, as well as the values that can be passed to the parameters.

GitHub Actions for Infra Deployment

Now that we have the Bicep code to deploy the Azure Container Registry, we need to create a GitHub Actions workflow to deploy the infrastructure resources. Here is the GitHub Actions workflow that deploys the Azure Container Registry using AVM:

name: Deploy Azure Infra

on: workflow_dispatch:

permissions:
  id-token: write
  contents: read

env:
  resource-group: RG1 # name of the Azure resource group

jobs:
  bicep-deploy:
    name: "Bicep Deploy"
    runs-on: ubuntu-latest
    environment: dev

    steps:
      # Checkout the repository to the GitHub Actions runner
      - name: Checkout
        uses: actions/checkout@v4

      # Authenticate to Az CLI using OIDC
      - name: "Az CLI login"
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Azure CLI script
        uses: azure/cli@v2
        with:
          azcliversion: 2.59.0
          inlineScript: |
            az deployment group create --resource-group ${{ env.resource-group }} --name rollout01 --template-file main.bicep --parameters main.bicepparam

In this GitHub Actions workflow, we are using the Azure/login and Azure/cli actions to authenticate to the Azure CLI and deploy the Bicep code to the Azure resource group. The workflow is triggered manually using the workflow_dispatch event.

I’ve covered using OIDC to authenticate Github to Azure in depth in previous blogs. You can find more information on how to set up OIDC authentication in parts 4 and 5 of Azure MLOps Challenge Blog

GitHub Actions for Container Deployment

Now that we have deployed the Azure Container Registry using Azure Verified Modules, we need to create a GitHub Actions workflow to build and push a container image to the Azure Container Registry. Here is the GitHub Actions workflow that builds and pushes a container image to the Azure Container Registry:

name: Build and Push Docker image to ACR

on: workflow_dispatch:

permissions:
  id-token: write
  contents: read

env:
  REGISTRY_NAME: devacrulelz55lpsh # Set your registry name here
  IMAGE_NAME: app2003 # Set your image name here

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    environment: dev

    steps:
      - name: Checkout code
        uses: actions/checkout@main

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: "Az CLI login"
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Login to ACR
        run: |
          az acr login --name ${{ env.REGISTRY_NAME }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          file: ./Dockerfile
          push: true
          tags: ${{ env.REGISTRY_NAME }}.azurecr.io/${{ env.IMAGE_NAME }}:${{ github.sha }}

In this GitHub Actions workflow, we are using the Docker/build-push-action to build and push a container image to the Azure Container Registry. We’re also using Azure RBAC authentication to the registry, opposed to the registry access keys of the Admin User login. The workflow is triggered manually using the workflow_dispatch event.

Conclusion

In this blog post, we explored Azure Verified Modules and how you can use them to simplify your Azure deployments. We deployed an Azure Container Registry using Azure Verified Modules and created a GitHub Actions workflows to deploy the infrastructure resources and build and push a container image to an Azure Container Registry.

Azure Verified Modules are a powerful tool that can help you automate the deployment and configuration of Azure services. By using Azure Verified Modules, you can save time and effort and ensure your deployments are secure, reliable, and efficient.

Azure Verified Modules offer significant benefits for businesses, particularly in terms of reducing the need to maintain internal registries, which can be time-consuming and resource-intensive. These modules are pre-built, tested, and verified by Microsoft, which means businesses can leverage them without worrying about their upkeep. By using Azure Verified Modules, businesses can focus more on their core operations and less on the maintenance of infrastructure code. Furthermore, these modules offer best practices and security, providing businesses with the assurance that they are using reliable and secure modules for their Azure deployments. This not only saves time and resources but also enhances the efficiency and reliability of business operations.

I hope you found this blog post helpful. Thank you for reading!

AKS provides a fully managed Kubernetes cluster that makes it easy to deploy, manage, and scale your applications. And with automated deployments, you can streamline your deployment process and reduce the risk of errors.

With automated deployments, you can:

• Reduce the need for Kubernetes expertise: Automated deployments eliminate the need for Kubernetes expertise by automating the build and deployment process.

• Reduce the risk of errors: Automated deployments eliminate the risk of human error by automating the build (CI) process.

• Save time and effort: Automating your deployments saves time and effort by eliminating the need for manual intervention.

• Increase consistency: Automated deployments ensure that your deployments (CD) are consistent and repeatable.

With Automated Deployments you can streamline your integration and deployment process and focus on what really matters: releasing great application on AKS.

Automated Deployments automates the following four tasks:

• Generates a Dockerfile

• Generates a GitHub Actions (yaml) pipeline

• Generates two Kubernetes manifest

• Authenticates with GitHub Actions, ACR and AKS

Prerequisites

To complete this tutorial, you need:

• An Azure subscription.

• A GitHub account.

• An application to deploy. If you don’t have an application to deploy, you can use the sample application in this tutorial.

Create Azure Resources

To create the Azure resources, you’ll need for this tutorial, use the following Azure CLI commands:

az group create --name myAKSDemo --location australiaeast

az aks create --resource-group myAKSDemo `
--name myAKSCluster `
--node-count 1 `
--enable-addons monitoring `
--generate-ssh-keys `
--kubernetes-version 1.28.0

az acr create --resource-group myAKSDemo `
--name automateddeployments `
--sku Basic

Azure Container Registry (ACR) is used to store our containers after they’re built in the Github Actions Workflow. The containers are then deployed into AKS after the Workflow runs the kubectl apply command.

GitHub Repository

For this demo we’ll be using a (very) basic Flask app. Create a folder in the repo called “src” and a file named app.py and requirements.txt inside.

from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello_world():
    return "<h1>Hello World</h1>"

if __name__ == "__main__":
    app.run(debug=True)

Flask==2.3.3

Once you’ve committed those changes to your main branch, we can move on to automated deployments configuration.

Configure Automated Deployments

In the Azure Portal, select your cluster and click on the Automated Deployments tab. Click on Automatically containerize and deploy to start the setup.

After you’ve authenticated with GitHub, select the repository you want to use for the deployment.

The wizard will automatically detect environment runtime. Fill in the port and location for the app.

Don’t forget to select the registry created above at the bottom of the page.

Create a new namespace for the project and proceed to the next step.

and click Deploy.

The automated deployment will now generate the credentials and set up permissions between GitHub Actions, the Container Registry and the AKS cluster.

The automated deployment will also create a pull request containing the new Dockerfile, GitHub Actions workflow and Kubernetes (yaml) manifest.

Clicking on “Approve pull request” will open the pull request in GitHub in a new tab.

Note: The auto-generated entrypoint/cmd won’t work, update the Dockerfile to use the following instead.

CMD [ "python3", "-m" , "flask", "run", "--host=0.0.0.0"]

Approve the merge and delete the branch then head to Action to see the build process.

The pipeline will build the Docker image, push it to ACR and deploy it to AKS.

After a few minutes the deployment will be complete and the job status from the GitHub Actions pipeline will be reflected under the Automated Deployments tab in the Azure Portal.

You can start to see how you might scale this out by adding more apps in different repo and/or branches.

Head up to “Services and ingress” to get the public IP address of the app.

Clicking on the external IP will open a tab with the app.

Success! 🤜🤛

You’ve deployed an application to AKS using without any knowledge of Kubernetes or Docker!

Automated Deployments Demo

Now that we’ve got the basic configuration in place, let’s take a look at how automated deployments work.

This is best explained by modifying the code in the GitHub repo and seeing how the automated deployment process works.

Make a change to app.py and commit the changes to a new branch and create a pull request.

from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello_world():
    return "<h1>Hello World 2.0</h1>"

if __name__ == "__main__":
    app.run(debug=True)

git checkout -b feature/website-update

git commit -am "added things"

git push --set-upstream origin feature/website-update

After completing the merge, observe the GitHub Actions pipeline.

and the Azure Portal.

After the build is complete, refresh the tab with the app to see the changes.

Behind The Certains

The real magic is in the GitHub workflow.

name: pythonapp
"on":
    push:
        branches:
            - main
    workflow_dispatch: {}
env:
    ACR_RESOURCE_GROUP: myAKSDemo
    AZURE_CONTAINER_REGISTRY: automateddeployments
    CLUSTER_NAME: myDemoCluster
    CLUSTER_RESOURCE_GROUP: myAKSDemo
    CONTAINER_NAME: pythonapp
    DEPLOYMENT_MANIFEST_PATH: |
        manifests/deployment.yaml
        manifests/service.yaml
jobs:
    buildImage:
        permissions:
            contents: read
            id-token: write
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v3
            - uses: azure/login@<ID>
              name: Azure login
              with:
                client-id: ${{ secrets.AZURE_CLIENT_ID }}
                subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
                tenant-id: ${{ secrets.AZURE_TENANT_ID }}
            - name: Build and push image to ACR
              run: az acr build --image ${{ env.CONTAINER_NAME }}:${{ github.sha }} --registry ${{ env.AZURE_CONTAINER_REGISTRY }} -g ${{ env.ACR_RESOURCE_GROUP }} -f Dockerfile ./src
    deploy:
        permissions:
            actions: read
            contents: read
            id-token: write
        runs-on: ubuntu-latest
        needs:
            - buildImage
        steps:
            - uses: actions/checkout@v3
            - uses: azure/login@<ID>
              name: Azure login
              with:
                client-id: ${{ secrets.AZURE_CLIENT_ID }}
                subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
                tenant-id: ${{ secrets.AZURE_TENANT_ID }}
            - uses: azure/use-kubelogin@v1
              name: Set up kubelogin for non-interactive login
              with:
                kubelogin-version: v0.0.25
            - uses: azure/aks-set-context@v3
              name: Get K8s context
              with:
                admin: "false"
                cluster-name: ${{ env.CLUSTER_NAME }}
                resource-group: ${{ env.CLUSTER_RESOURCE_GROUP }}
                use-kubelogin: "true"
            - uses: Azure/k8s-deploy@v4
              name: Deploys application
              with:
                action: deploy
                images: ${{ env.AZURE_CONTAINER_REGISTRY }}.azurecr.io/${{ env.CONTAINER_NAME }}:${{ github.sha }}
                manifests: ${{ env.DEPLOYMENT_MANIFEST_PATH }}
                namespace: flask

Here’s a brief description of what’s happening:

• az acr build containerizes the latest version of the code from the Dockerfile and pushes it to the ACR.

• azure/use-kubelogin@v1 and azure/aks-set-context@v3 logs into the AKS cluster.

• Azure/k8s-deploy@v4 deploys the new container image to AKS using deployment.yaml

Not Without Its Flaws

During the process of writing this blog I tried three times to get the Automated Deployment to work:

• The first attempt I used a Python app that I hadn’t tested as a container,

• The second attempt I used a Node app that I had used on AKS before and,

• The third attempt I used a Go app that I had used with Docker locally.

Each time I ran into the same issue: the automated deployment process failed to generate a usable Dockerfile. So, I had to troubleshoot the issue with Docker locally before I could move on.

Conclusion

Automated Deployments is a fantastic solution for abstracting away the complexities of containers builds and Kubernetes deployments. All you need is a basic understanding of Docker and you’ll have apps running on AKS in no time. I think it’s a great idea and the automation to generate the various files and pull request integration works really well, but the overall solution feels a bit… incomplete. I’d love to see the wizard get integration with an ingress controller to make it more than just a pod running on a cluster for a start, to bootstrap the blue/green or canary deployments. Similar to Azure Web App Slots.

As always, thanks for reading and happy coding!

If you’d like more information Automated Deployments, you can find it here.

Cleanup

When you’re ready to delete your resources, you can use the following command to remove the resource group, AKS cluster, and all related resources.

az group delete --name myAKSDemo --yes --no-wait