[Request]: New Remove-AdoMembership Cmdlet

[msc365admin]

Is there an existing issue for this?

• I have searched the existing issues

Azure.DevOps.PSModule version

0.2.2

Related function

Get-AdoMembership, Add-AdoGroupMember

Use case

As a DevOps Engineer managing Azure DevOps organization security and access control

I want a Remove-AdoMembership cmdlet to programmatically remove membership relationships between subjects and containers

So that I can automate the cleanup of group memberships, implement least-privilege access patterns, and efficiently manage team member departures or role changes without manual portal operations

Notes

• Currently, the module provides Get-AdoMembership to retrieve membership relationships and Add-AdoGroupMember to add members to groups
• There is no corresponding cmdlet to remove membership relationships, creating an asymmetric API surface
• Manual membership removal via the Azure DevOps portal is time-consuming and error-prone for bulk operations
• Automated membership lifecycle management (onboarding/offboarding) requires both add and remove capabilities
• Common scenarios include:
  • Implementing temporary access grants with automated revocation
  • Cleaning up stale memberships during security audits
  • Automating role-based access control (RBAC) transitions

Proposed solution

Create a Remove-AdoMembership cmdlet that:

Cmdlet Signature

function Remove-AdoMembership {
    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')]
    param (
        [Parameter(ValueFromPipelineByPropertyName)]
        [ValidateScript({ Confirm-CollectionUri -Uri $_ })]
        [string]$CollectionUri = ($env:DefaultAdoCollectionUri -replace 'https://', 'https://vssps.'),

        [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)]
        [string[]]$SubjectDescriptor,

        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [string]$ContainerDescriptor,

        [Parameter()]
        [Alias('ApiVersion')]
        [ValidateSet('7.1-preview.1', '7.2-preview.1')]
        [string]$Version = '7.1-preview.1'
    )
}

Key Features

1. DELETE HTTP Method: Calls the Azure DevOps Graph API using DELETE method
2. Pipeline Support: Accept SubjectDescriptor from pipeline for bulk operations
3. Confirmation Prompts: Include -WhatIf and -Confirm support due to destructive nature
4. Descriptor Validation: Validate descriptor format before API calls
5. Error Handling: Provide clear error messages for non-existent memberships or permission issues
6. Consistency: Follow same parameter patterns as Get-AdoMembership for intuitive usage

API Endpoint

DELETE https://vssps.dev.azure.com/{organization}/_apis/graph/memberships/{subjectDescriptor}/{containerDescriptor}?api-version=7.1-preview.1

Example Usage

# Remove a single membership
$params = @{
    CollectionUri       = 'https://vssps.dev.azure.com/my-org'
    SubjectDescriptor   = 'aadgp.00000000-0000-0000-0000-000000000000'
    ContainerDescriptor = 'vssgp.00000000-0000-0000-0000-000000000001'
}
Remove-AdoMembership @params

# Remove multiple memberships via pipeline
$usersToRemove = @(
    'aadgp.00000000-0000-0000-0000-000000000002',
    'aadgp.00000000-0000-0000-0000-000000000003'
)
$usersToRemove | Remove-AdoMembership @params

# Preview changes without executing
Remove-AdoMembership @params -WhatIf

# Remove without confirmation prompt (automation scenarios)
Remove-AdoMembership @params -Confirm:$false

Implementation Checklist

• Create Remove-AdoMembership.ps1 in src/Azure.DevOps.PSModule/Public/Graph/Memberships/
• Implement comprehensive Pester tests in src/Azure.DevOps.PSModule/Tests/Graph/Memberships/Remove-AdoMembership.Tests.ps1
• Generate PlatyPS documentation in docs/Remove-AdoMembership.md
• Update module manifest to export the new cmdlet
• Add usage examples to README
• Update CHANGELOG with new feature

Benefits

• Automation: Enable fully automated membership lifecycle management
• Consistency: Complete the CRUD operations for membership management
• Efficiency: Reduce manual effort and human error in membership cleanup
• Security: Facilitate timely removal of access rights as part of security best practices
• Compliance: Support audit requirements for access control management

Testing Scenarios

1. Successfully remove a valid membership relationship
2. Handle non-existent membership gracefully
3. Validate proper error handling for invalid descriptors
4. Confirm pipeline input processing for bulk operations
5. Verify -WhatIf and -Confirm behavior
6. Test with both AAD and VSSGP descriptor types
7. Validate API version parameter functionality