Public/Get-AADGroupByDisplayName.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
<#
    .NOTES
    ===========================================================================
     Created with: SAPIEN Technologies, Inc., PowerShell Studio 2017 v5.4.135
     Created on: 2/14/2017 5:53 AM
     Created by: Mark Kraus
     Organization: Mitel
     Filename: Get-AADGroupByDisplayName.ps1
    ===========================================================================
    .DESCRIPTION
        Get-AADGroupByDisplayName Function
#>


<#
    .SYNOPSIS
        Retrieves an Azure AD Group by the Display name
    
    .DESCRIPTION
        Retrieves an Azure AD Group by the Display Name
    
    .PARAMETER AccessToken
        MSGraphAPI.Oauth.AccessToken object obtained from Get-GraphOauthAccessToken.
    
    .PARAMETER DisplayName
        The Group's Display Name. This must be an exact match and does not support wildcards

    .PARAMETER BaseURL
        The Azure AD Graph Base URL. This is not required. Deafult
            https://graph.windows.net

    .PARAMETER APIVersion
        version og the API to use. Default is 1.6
    
    .EXAMPLE
        PS C:\> $AADGroup = Get-AADGroupByDisplayName -AccessToken $GraphAccessToken -DisplayName 'Adataum Finance'
    
    .OUTPUTS
        MSGraphAPI.DirectoryObject.ServicePrincipal
#>

function Get-AADGroupByDisplayName {
    [CmdletBinding(SupportsShouldProcess = $true)]
    [OutputType('MSGraphAPI.DirectoryObject.Group')]
    param
    (
        [Parameter(Mandatory = $true,
                   ValueFromPipelineByPropertyName = $true)]
        [ValidateNotNullOrEmpty()]
        [PSTypeName('MSGraphAPI.Oauth.AccessToken')]
        $AccessToken,
        
        [Parameter(Mandatory = $true,
                   ValueFromPipeline = $true,
                   ValueFromPipelineByPropertyName = $true,
                   ValueFromRemainingArguments = $true)]
        [ValidateNotNullOrEmpty()]
        [string[]]$DisplayName,
        
        [Parameter(Mandatory = $false,
                   ValueFromPipelineByPropertyName = $true)]
        [ValidateNotNullOrEmpty()]
        [string]$BaseUrl = 'https://graph.windows.net',
        
        [Parameter(Mandatory = $false,
                   ValueFromPipelineByPropertyName = $true)]
        [ValidateNotNullOrEmpty()]
        [string]$APIversion = '1.6'
        
    )
    
    process {
        foreach ($GroupName in $DisplayName) {
            if (-not $pscmdlet.ShouldProcess($ServiceId)) {
                return
            }
            $Application = $AccessToken.Application
            $Tenant = $Application.Tenant
            $Url = '{0}/{1}/{2}?api-version={3}&$filter=displayName+eq+%27{4}%27' -f @(
                $BaseUrl
                $Tenant
                'groups'
                $APIversion
                [System.Web.HttpUtility]::UrlEncode($GroupName)
            )
            $Params = @{
                Uri = $Url
                Method = 'GET'
                AccessToken = $AccessToken
                ErrorAction = 'Stop'
            }
            try {
                $Result = Invoke-GraphRequest @Params
            }
            catch {
                $ErrorMessage = "Unable to query User '{0}': {1}" -f $UserId, $_.Exception.Message
                Write-Error $ErrorMessage
                return
            }
            foreach ($ServiceObject in $Result.ContentObject.value) {
                $OutputObject = $ServiceObject.psobject.copy()
                $OutputObject.psobject.TypeNames.Insert(0, 'MSGraphAPI.DirectoryObject.Group')
                $OutputObject | Add-Member -MemberType NoteProperty -Name _AccessToken -Value $AccessToken
                $OutputObject
            }
        }
    }
}