Skip to content

AzDoServiceConnectionPermission

Jump to bottom
Michael Zanatta edited this page Aug 13, 2026 · 2 revisions

AzDoServiceConnectionPermission Resource

Description

The AzDoServiceConnectionPermission DSC resource is used to manage role-based permissions for service connections (service endpoints) in Azure DevOps. It allows you to control which groups and users can use, edit, or manage service connections for authentication with external services and platforms.

Syntax

AzDoServiceConnectionPermission [string] #ResourceName
{
    ProjectName = [String] $ProjectName
    ConnectionName = [String] $ConnectionName
    GroupName = [String] $GroupName
    [ isInherited = [Boolean] $isInherited ]
    [ Permissions = [HashTable[]] $Permissions ]
    [ Ensure = [String] {'Present', 'Absent'} ]
    [ DependsOn = [String[]] ]
    [ PsDscRunAsCredential = [PSCredential] ]
}

Properties

Key Properties (Required)

  • ProjectName [String] - The name of the Azure DevOps project.

  • ConnectionName [String] - The name of the service connection.

  • GroupName [String] - The name of the group whose permissions are being managed.

Optional Properties

  • isInherited [Boolean] - Whether permissions are inherited from the project level. Default is $true.

  • Permissions [HashTable[]] - An array of permission hashtables, each containing:

    • Permission - The permission name (e.g., 'Use', 'Edit', 'Delete', 'Manage')
    • Allow - Boolean indicating if permission is allowed
    • Deny - Boolean indicating if permission is denied

  • Ensure [String] - Desired state of the resource:

    • 'Present' - (default) Permissions should be configured
    • 'Absent' - Permissions should be removed

Common Properties

  • DependsOn [String[]] - Dependencies on other resources. Use this to control the order of resource execution.

  • PsDscRunAsCredential [PSCredential] - Credentials to run this resource under.

Return Values

The resource returns the following properties:

  • ProjectName - The name of the project
  • ConnectionName - The name of the service connection
  • GroupName - The name of the group
  • isInherited - Whether permissions are inherited
  • Permissions - The configured permissions
  • Ensure - Current state ('Present' or 'Absent')

Examples

Example 1: Grant Service Connection Access

Configuration GrantServiceConnectionAccess {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoServiceConnectionPermission 'AzureDevAccess' {
            ProjectName     = 'MyProject'
            ConnectionName  = 'Azure Dev Subscription'
            GroupName       = 'Development Team'
            isInherited     = $false
            Permissions     = @(
                @{
                    Permission = 'Use'
                    Allow      = $true
                },
                @{
                    Permission = 'Edit'
                    Allow      = $false
                }
            )
            Ensure          = 'Present'
        }
    }
}

GrantServiceConnectionAccess
Start-DscConfiguration -Path ./GrantServiceConnectionAccess -Wait -Verbose

Example 2: Restrict Production Service Connection

Configuration RestrictProductionConnection {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoServiceConnectionPermission 'ProdAccess' {
            ProjectName     = 'MyProject'
            ConnectionName  = 'Azure Production Subscription'
            GroupName       = 'DevOps Team'
            isInherited     = $false
            Permissions     = @(
                @{ Permission = 'Use'; Allow = $true },
                @{ Permission = 'Edit'; Allow = $true }
            )
            Ensure          = 'Present'
        }
        
        AzDoServiceConnectionPermission 'DeveloperRestriction' {
            ProjectName     = 'MyProject'
            ConnectionName  = 'Azure Production Subscription'
            GroupName       = 'Developers'
            isInherited     = $false
            Permissions     = @(
                @{ Permission = 'Use'; Allow = $false; Deny = $true }
            )
            Ensure          = 'Present'
        }
    }
}

RestrictProductionConnection
Start-DscConfiguration -Path ./RestrictProductionConnection -Wait -Verbose

Example 3: Configure Multiple Service Connection Permissions

Configuration MultiServiceConnections {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoServiceConnectionPermission 'DevAzure' {
            ProjectName     = 'MyProject'
            ConnectionName  = 'Azure Dev'
            GroupName       = 'Developers'
            isInherited     = $false
            Permissions     = @(
                @{ Permission = 'Use'; Allow = $true },
                @{ Permission = 'Edit'; Allow = $true }
            )
            Ensure          = 'Present'
        }
        
        AzDoServiceConnectionPermission 'AWS' {
            ProjectName     = 'MyProject'
            ConnectionName  = 'AWS Deployment'
            GroupName       = 'DevOps Team'
            isInherited     = $false
            Permissions     = @(
                @{ Permission = 'Use'; Allow = $true },
                @{ Permission = 'Edit'; Allow = $true }
            )
            Ensure          = 'Present'
        }
        
        AzDoServiceConnectionPermission 'DockerHub' {
            ProjectName     = 'MyProject'
            ConnectionName  = 'Docker Hub Registry'
            GroupName       = 'Developers'
            isInherited     = $false
            Permissions     = @(
                @{ Permission = 'Use'; Allow = $true }
            )
            Ensure          = 'Present'
        }
    }
}

MultiServiceConnections
Start-DscConfiguration -Path ./MultiServiceConnections -Wait -Verbose

Example 4: Query Service Connection Permissions

# Get the current state of service connection permissions
$properties = @{
    ProjectName    = 'MyProject'
    ConnectionName = 'Azure Dev Subscription'
    GroupName      = 'Development Team'
}

$result = Invoke-DscResource -Name 'AzDoServiceConnectionPermission' `
    -Method Get `
    -Property $properties `
    -ModuleName 'AzureDevOpsDscNative'

$result | Select-Object ProjectName, ConnectionName, GroupName, isInherited, Permissions

Example 5: Allow Pipeline Access to Service Connection

Configuration AllowPipelineServiceAccess {
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
    
    Node localhost {
        AzDoServiceConnectionPermission 'PipelineAzureAccess' {
            ProjectName     = 'MyProject'
            ConnectionName  = 'Azure Dev Subscription'
            GroupName       = 'Pipeline Service'
            isInherited     = $false
            Permissions     = @(
                @{ Permission = 'Use'; Allow = $true }
            )
            Ensure          = 'Present'
        }
    }
}

AllowPipelineServiceAccess
Start-DscConfiguration -Path ./AllowPipelineServiceAccess -Wait -Verbose

Important Notes

Permission Types

  • Use - Ability to use the service connection in pipelines
  • Edit - Ability to modify the service connection credentials/configuration
  • Delete - Ability to delete the service connection
  • Manage - Ability to manage service connection permissions

Service Connection Types

  • Azure subscriptions, AWS, Docker registries, GitHub, npm feeds, etc.
  • Different connection types may have different permission models
  • Security should be a priority for cloud connection permissions

Best Practices

  • Use the principle of least privilege for permissions
  • Restrict edit permissions to connection owners only
  • Create separate connections for dev, staging, and production
  • Regularly audit who has access to critical connections
  • Document which pipelines use each connection

Inheritance

  • When isInherited is $true, permissions flow from project settings
  • Setting isInherited to $false allows custom permissions
  • Important for restricting production connections

Troubleshooting

Issue: "Service Connection Not Found"

Cause: The service connection does not exist

Solution:

# Create the service connection first using AzDoServiceConnection resource
# Verify connection name matches exactly (case-sensitive)

Issue: "Cannot Set Permissions"

Cause: Group does not exist or insufficient permissions

Solution:

  • Verify the group exists in the project
  • Ensure user has service connection admin permissions
  • Check personal access token has correct scope

Issue: "Pipelines Cannot Use Connection"

Cause: Pipelines lack "Use" permission

Solution:

  • Grant "Use" permission to pipeline service accounts
  • Verify pipelines have access to the connection
  • Check project pipeline service connection permissions

Related Resources

See Also

Clone this wiki locally