Skip to content

Commit a8bda12

Browse files
givinalisGivinalis Omachar
givinalis
and
Givinalis Omachar
authored
Introducing new filter parameters to Get-EntraServicePrincipal and Get-EntraBetaServicePrincipal (#1567)
* added new params * added new parameters to cmdlets * added unit tests for cmdlets * Updated documentation with new parameters and examples --------- Co-authored-by: Givinalis Omachar <[email protected]>
1 parent f1831bf commit a8bda12

File tree

6 files changed

+446
-2
lines changed

6 files changed

+446
-2
lines changed

‎module/Entra/Microsoft.Entra/Applications/Get-EntraServicePrincipal.ps1‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,16 @@ function Get-EntraServicePrincipal {
2525

2626
[Parameter(Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Properties to include in the results.")]
2727
[Alias("Select")]
28-
[System.String[]] $Property
28+
[System.String[]] $Property,
29+
30+
[Parameter(ParameterSetName = "GetQuery", Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter by whether user assignment is required to access the application.")]
31+
[Parameter(ParameterSetName = "GetVague", Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter by whether user assignment is required to access the application.")]
32+
[System.Nullable`1[System.Boolean]] $AssignmentRequired,
33+
34+
[Parameter(ParameterSetName = "GetQuery", Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter by application type: AppProxyApps, EnterpriseApps, ManagedIdentity, or MicrosoftApps.")]
35+
[Parameter(ParameterSetName = "GetVague", Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter by application type: AppProxyApps, EnterpriseApps, ManagedIdentity, or MicrosoftApps.")]
36+
[ValidateSet("AppProxyApps", "EnterpriseApps", "ManagedIdentity", "MicrosoftApps")]
37+
[System.String] $ApplicationType
2938
)
3039

3140
begin {
@@ -105,6 +114,30 @@ function Get-EntraServicePrincipal {
105114
$params["Property"] = $PSBoundParameters["Property"]
106115
}
107116

117+
if ($null -ne $PSBoundParameters["AssignmentRequired"]) {
118+
$assignmentRequiredState = $PSBoundParameters["AssignmentRequired"]
119+
if ($params.ContainsKey("Filter")) {
120+
$params["Filter"] += " and appRoleAssignmentRequired eq $assignmentRequiredState"
121+
} else {
122+
$params["Filter"] = "appRoleAssignmentRequired eq $assignmentRequiredState"
123+
}
124+
}
125+
126+
if ($null -ne $PSBoundParameters["ApplicationType"]) {
127+
$appType = $PSBoundParameters["ApplicationType"]
128+
$appTypeFilter = switch ($appType) {
129+
"AppProxyApps" { "tags/any(t:t eq 'WindowsAzureActiveDirectoryOnPremApp')" }
130+
"EnterpriseApps" { "tags/any(t:t eq 'WindowsAzureActiveDirectoryIntegratedApp')" }
131+
"ManagedIdentity" { "servicePrincipalType eq 'ManagedIdentity'" }
132+
"MicrosoftApps" { "appOwnerOrganizationId eq f8cdef31-a31e-4b4a-93e4-5f571e91255a" }
133+
}
134+
if ($params.ContainsKey("Filter")) {
135+
$params["Filter"] += " and $appTypeFilter"
136+
} else {
137+
$params["Filter"] = $appTypeFilter
138+
}
139+
}
140+
108141
Write-Debug("============================ TRANSFORMATIONS ============================")
109142
$params.Keys | ForEach-Object { "$_ : $($params[$_])" } | Write-Debug
110143
Write-Debug("=========================================================================`n")

‎module/EntraBeta/Microsoft.Entra.Beta/Applications/Get-EntraBetaServicePrincipal.ps1‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,16 @@ function Get-EntraBetaServicePrincipal {
2525

2626
[Parameter(Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Properties to include in the results.")]
2727
[Alias("Select")]
28-
[System.String[]] $Property
28+
[System.String[]] $Property,
29+
30+
[Parameter(ParameterSetName = "GetQuery", Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter by whether user assignment is required to access the application.")]
31+
[Parameter(ParameterSetName = "GetVague", Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter by whether user assignment is required to access the application.")]
32+
[System.Nullable`1[System.Boolean]] $AssignmentRequired,
33+
34+
[Parameter(ParameterSetName = "GetQuery", Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter by application type: AppProxyApps, EnterpriseApps, ManagedIdentity, or MicrosoftApps.")]
35+
[Parameter(ParameterSetName = "GetVague", Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter by application type: AppProxyApps, EnterpriseApps, ManagedIdentity, or MicrosoftApps.")]
36+
[ValidateSet("AppProxyApps", "EnterpriseApps", "ManagedIdentity", "MicrosoftApps")]
37+
[System.String] $ApplicationType
2938
)
3039

3140
begin {
@@ -105,6 +114,30 @@ function Get-EntraBetaServicePrincipal {
105114
$params["Property"] = $PSBoundParameters["Property"]
106115
}
107116

117+
if ($null -ne $PSBoundParameters["AssignmentRequired"]) {
118+
$assignmentRequiredState = $PSBoundParameters["AssignmentRequired"]
119+
if ($params.ContainsKey("Filter")) {
120+
$params["Filter"] += " and appRoleAssignmentRequired eq $assignmentRequiredState"
121+
} else {
122+
$params["Filter"] = "appRoleAssignmentRequired eq $assignmentRequiredState"
123+
}
124+
}
125+
126+
if ($null -ne $PSBoundParameters["ApplicationType"]) {
127+
$appType = $PSBoundParameters["ApplicationType"]
128+
$appTypeFilter = switch ($appType) {
129+
"AppProxyApps" { "tags/any(t:t eq 'WindowsAzureActiveDirectoryOnPremApp')" }
130+
"EnterpriseApps" { "tags/any(t:t eq 'WindowsAzureActiveDirectoryIntegratedApp')" }
131+
"ManagedIdentity" { "servicePrincipalType eq 'ManagedIdentity'" }
132+
"MicrosoftApps" { "appOwnerOrganizationId eq f8cdef31-a31e-4b4a-93e4-5f571e91255a" }
133+
}
134+
if ($params.ContainsKey("Filter")) {
135+
$params["Filter"] += " and $appTypeFilter"
136+
} else {
137+
$params["Filter"] = $appTypeFilter
138+
}
139+
}
140+
108141
Write-Debug("============================ TRANSFORMATIONS ============================")
109142
$params.Keys | ForEach-Object { "$_ : $($params[$_])" } | Write-Debug
110143
Write-Debug("=========================================================================`n")

‎module/docs/entra-powershell-beta/Applications/Get-EntraBetaServicePrincipal.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ Get-EntraBetaServicePrincipal
2929
[-All]
3030
[-Filter <String>]
3131
[-Property <String[]>]
32+
[-AssignmentRequired <Boolean>]
33+
[-ApplicationType <String>]
3234
[<CommonParameters>]
3335
```
3436

@@ -39,6 +41,8 @@ Get-EntraBetaServicePrincipal
3941
[-SearchString <String>]
4042
[-All]
4143
[-Property <String[]>]
44+
[-AssignmentRequired <Boolean>]
45+
[-ApplicationType <String>]
4246
[<CommonParameters>]
4347
```
4448

@@ -287,6 +291,67 @@ PowerApps-Advisor cccccccc-2222-3333-4444-
287291

288292
This example shows how you can retrieve applications (service principals) outside my tenant.
289293

294+
### Example 15: Retrieve service principals with user assignment required
295+
296+
```powershell
297+
Connect-Entra -Scopes 'Application.Read.All'
298+
Get-EntraBetaServicePrincipal -AssignmentRequired $true
299+
```
300+
301+
```Output
302+
DisplayName Id AppId SignInAudience ServicePrincipalType
303+
----------- -- ----- -------------- --------------------
304+
Restricted App aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb 00001111-aaaa-2222-bbbb-3333cccc4444 AzureADMyOrg Application
305+
```
306+
307+
This example retrieves all service principals where user assignment is required to access the application.
308+
309+
### Example 16: Retrieve Enterprise Apps using ApplicationType parameter
310+
311+
```powershell
312+
Connect-Entra -Scopes 'Application.Read.All'
313+
Get-EntraBetaServicePrincipal -ApplicationType EnterpriseApps
314+
```
315+
316+
```Output
317+
DisplayName Id AppId SignInAudience ServicePrincipalType
318+
----------- -- ----- -------------- --------------------
319+
Enterprise App1 00001111-aaaa-2222-bbbb-3333cccc4444 33334444-dddd-5555-eeee-6666ffff7777 Application
320+
Enterprise App2 11112222-bbbb-3333-cccc-4444dddd5555 22223333-cccc-4444-dddd-5555eeee6666 AzureADMultipleOrgs Application
321+
```
322+
323+
This example demonstrates how to retrieve all enterprise apps using the ApplicationType parameter. Valid values are: AppProxyApps, EnterpriseApps, ManagedIdentity, MicrosoftApps.
324+
325+
### Example 17: Retrieve Managed Identities
326+
327+
```powershell
328+
Connect-Entra -Scopes 'Application.Read.All'
329+
Get-EntraBetaServicePrincipal -ApplicationType ManagedIdentity
330+
```
331+
332+
```Output
333+
DisplayName Id AppId SignInAudience ServicePrincipalType
334+
----------- -- ----- -------------- --------------------
335+
MyVM-Identity 00001111-aaaa-2222-bbbb-3333cccc4444 33334444-dddd-5555-eeee-6666ffff7777 ManagedIdentity
336+
```
337+
338+
This example retrieves all managed identities.
339+
340+
### Example 18: Combine AssignmentRequired and ApplicationType filters
341+
342+
```powershell
343+
Connect-Entra -Scopes 'Application.Read.All'
344+
Get-EntraBetaServicePrincipal -AssignmentRequired $true -ApplicationType EnterpriseApps
345+
```
346+
347+
```Output
348+
DisplayName Id AppId SignInAudience ServicePrincipalType
349+
----------- -- ----- -------------- --------------------
350+
Secured Enterprise App aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb 00001111-aaaa-2222-bbbb-3333cccc4444 AzureADMyOrg Application
351+
```
352+
353+
This example demonstrates how to combine both AssignmentRequired and ApplicationType parameters to filter enterprise apps that require user assignment.
354+
290355
## PARAMETERS
291356

292357
### -All
@@ -386,6 +451,42 @@ Accept pipeline input: False
386451
Accept wildcard characters: False
387452
```
388453
454+
### -AssignmentRequired
455+
456+
Filter by whether user assignment is required to access the application. When set to `$true`, returns only service principals where user assignment is required. When set to `$false`, returns only service principals where user assignment is not required.
457+
458+
```yaml
459+
Type: System.Boolean
460+
Parameter Sets: GetQuery, GetVague
461+
Aliases:
462+
463+
Required: False
464+
Position: Named
465+
Default value: None
466+
Accept pipeline input: True (ByPropertyName, ByValue)
467+
Accept wildcard characters: False
468+
```
469+
470+
### -ApplicationType
471+
472+
Filter by application type. Valid values are:
473+
- `AppProxyApps`: Application proxy applications
474+
- `EnterpriseApps`: Enterprise applications
475+
- `ManagedIdentity`: Managed identity service principals
476+
- `MicrosoftApps`: Microsoft first-party applications
477+
478+
```yaml
479+
Type: System.String
480+
Parameter Sets: GetQuery, GetVague
481+
Aliases:
482+
483+
Required: False
484+
Position: Named
485+
Default value: None
486+
Accept pipeline input: True (ByPropertyName, ByValue)
487+
Accept wildcard characters: False
488+
```
489+
389490
### CommonParameters
390491

391492
This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).

‎module/docs/entra-powershell-v1.0/Applications/Get-EntraServicePrincipal.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ Get-EntraServicePrincipal
2929
[-All]
3030
[-Filter <String>]
3131
[-Property <String[]>]
32+
[-AssignmentRequired <Boolean>]
33+
[-ApplicationType <String>]
3234
[<CommonParameters>]
3335
```
3436

@@ -39,6 +41,8 @@ Get-EntraServicePrincipal
3941
[-SearchString <String>]
4042
[-All]
4143
[-Property <String[]>]
44+
[-AssignmentRequired <Boolean>]
45+
[-ApplicationType <String>]
4246
[<CommonParameters>]
4347
```
4448

@@ -287,6 +291,67 @@ PowerApps-Advisor cccccccc-2222-3333-4444-
287291

288292
This example shows how you can retrieve applications (service principals) outside my tenant.
289293

294+
### Example 15: Retrieve service principals with user assignment required
295+
296+
```powershell
297+
Connect-Entra -Scopes 'Application.Read.All'
298+
Get-EntraServicePrincipal -AssignmentRequired $true
299+
```
300+
301+
```Output
302+
DisplayName Id AppId SignInAudience ServicePrincipalType
303+
----------- -- ----- -------------- --------------------
304+
Restricted App aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb 00001111-aaaa-2222-bbbb-3333cccc4444 AzureADMyOrg Application
305+
```
306+
307+
This example retrieves all service principals where user assignment is required to access the application.
308+
309+
### Example 16: Retrieve Enterprise Apps using ApplicationType parameter
310+
311+
```powershell
312+
Connect-Entra -Scopes 'Application.Read.All'
313+
Get-EntraServicePrincipal -ApplicationType EnterpriseApps
314+
```
315+
316+
```Output
317+
DisplayName Id AppId SignInAudience ServicePrincipalType
318+
----------- -- ----- -------------- --------------------
319+
Enterprise App1 00001111-aaaa-2222-bbbb-3333cccc4444 33334444-dddd-5555-eeee-6666ffff7777 Application
320+
Enterprise App2 11112222-bbbb-3333-cccc-4444dddd5555 22223333-cccc-4444-dddd-5555eeee6666 AzureADMultipleOrgs Application
321+
```
322+
323+
This example demonstrates how to retrieve all enterprise apps using the ApplicationType parameter. Valid values are: AppProxyApps, EnterpriseApps, ManagedIdentity, MicrosoftApps.
324+
325+
### Example 17: Retrieve Managed Identities
326+
327+
```powershell
328+
Connect-Entra -Scopes 'Application.Read.All'
329+
Get-EntraServicePrincipal -ApplicationType ManagedIdentity
330+
```
331+
332+
```Output
333+
DisplayName Id AppId SignInAudience ServicePrincipalType
334+
----------- -- ----- -------------- --------------------
335+
MyVM-Identity 00001111-aaaa-2222-bbbb-3333cccc4444 33334444-dddd-5555-eeee-6666ffff7777 ManagedIdentity
336+
```
337+
338+
This example retrieves all managed identities.
339+
340+
### Example 18: Combine AssignmentRequired and ApplicationType filters
341+
342+
```powershell
343+
Connect-Entra -Scopes 'Application.Read.All'
344+
Get-EntraServicePrincipal -AssignmentRequired $true -ApplicationType EnterpriseApps
345+
```
346+
347+
```Output
348+
DisplayName Id AppId SignInAudience ServicePrincipalType
349+
----------- -- ----- -------------- --------------------
350+
Secured Enterprise App aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb 00001111-aaaa-2222-bbbb-3333cccc4444 AzureADMyOrg Application
351+
```
352+
353+
This example demonstrates how to combine both AssignmentRequired and ApplicationType parameters to filter enterprise apps that require user assignment.
354+
290355
## PARAMETERS
291356

292357
### -All
@@ -386,6 +451,42 @@ Accept pipeline input: False
386451
Accept wildcard characters: False
387452
```
388453
454+
### -AssignmentRequired
455+
456+
Filter by whether user assignment is required to access the application. When set to `$true`, returns only service principals where user assignment is required. When set to `$false`, returns only service principals where user assignment is not required.
457+
458+
```yaml
459+
Type: System.Boolean
460+
Parameter Sets: GetQuery, GetVague
461+
Aliases:
462+
463+
Required: False
464+
Position: Named
465+
Default value: None
466+
Accept pipeline input: True (ByPropertyName, ByValue)
467+
Accept wildcard characters: False
468+
```
469+
470+
### -ApplicationType
471+
472+
Filter by application type. Valid values are:
473+
- `AppProxyApps`: Application proxy applications
474+
- `EnterpriseApps`: Enterprise applications
475+
- `ManagedIdentity`: Managed identity service principals
476+
- `MicrosoftApps`: Microsoft first-party applications
477+
478+
```yaml
479+
Type: System.String
480+
Parameter Sets: GetQuery, GetVague
481+
Aliases:
482+
483+
Required: False
484+
Position: Named
485+
Default value: None
486+
Accept pipeline input: True (ByPropertyName, ByValue)
487+
Accept wildcard characters: False
488+
```
489+
389490
### CommonParameters
390491

391492
This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).

0 commit comments

Comments
 (0)