APIs for managing Microsoft Team team tags and tag members are currently available in Microsoft Graph beta endpoint. Support for tags is also available in Microsoft Graph PowerShell SDK. In this blog post, I will cover how to manage team tags with the Graph PowerShell SDK.
(Article originally published on Jan 23rd, 2022)
What are team tags?
Tags help reach out to a group of people based on their attributes, like roles, projects, skills, location, and so on, for example, “Project Manager” or “Kuopio”. A tag can be used as a mention, and everyone assigned to that specific tag will receive a notification. A tag can be also used to invite a group of people to a chat. A user can belong to multiple tags and each tag can have maximum of 100 members. Guest user can be also added as tag members.
More information about tags: https://support.microsoft.com/en-us/office/using-tags-in-teams-667bd56f-32b8-4118-9a0b-56807c96d91e
Preparations and Connecting to Graph
Since the teamworkTag endpoint only supports application authentication, the first thing is to register a new Azure AD application for your tenant (Quick Start Guide: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). Note that Graph PowerShell SDK supports only certificate authentication, so a certificate is required for authentication. A self-signed certificate can be created with PowerShell (use only for development and testing).
$cert = New-SelfSignedCertificate -Subject "CN=demo.mattipaukkonen.com" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
Export-Certificate -Cert $cert -FilePath "C:\Temp\demo.cer"
Upload the certificate to the newly registered Azure AD app.
The app requires TeamworkTag.ReadWrite.All Graph API permission for creating and managing tags.
For connecting Graph with application permissions, ClientID, Tenant ID, and Certificate Thumbprint are required. Client ID and Tenant ID can be found on the Overview page of the registered Azure AD application. Certificate thumbprint is visible on the Certificates & secrets page or, if the same PowerShell session is used thumbprint can be fetched from the $cert variable.
Connect-MgGraph -ClientId <your-client-id> -TenantId <your-tenant-id> -CertificateThumbprint <certificate-thumbprint>
Since tag management is only available in Graph API beta, beta profile needs to be selected on Graph SDK.
Select-MgProfile -Name "beta"
Create a New Tag
New tag is created with New-MgTeamTag cmdlet. One members is required when new tag is created, cmdlet requires an Azure AD Object Id of the user.
New-MgTeamTag -TeamId <team-id> -DisplayName "Project Manager" -Description "All project managers" -Members @{"userID"=<User's Azure AD Object Id>}
Listing and managing tags
All tags of the specified team can be listed with Get-MgTeamTag cmdlet.
Get-MgTeamTag -TeamId <team id>
Same cmdlet is also used to retrieve a specific team tag by using an tag id.
Get-MgTeamTag -TeamId <team id> -TeamworTagId <teamwork tag id>
Updating tag’s display name and description can be done with Update-MgTeamTag cmdlet.
Update-MgTeamTag -TeamId <team id> -TeamworkTagId <tag id> -DisplayName "New name" -Description "New description"
A tag is removed with Remove-MgTeamTag cmdlet.
Managing tag members
Listing members of a specified tag.
Get-MgTeamTagMember -TeamId <team id> -TeamworkTagId <tag id>
Adding new members to the tag is done with New-MgTeamTagMember cmdlet. User is referenced with Azure AD Object Id.
New-MgTeamTagMember -TeamId <team id> -TeamworkTagId <tag id> -UserId <AAD Object Id>
And a user is removed from a tag with Remove-MgTeamTagMember cmdlet where the user is referenced with tag member id.
Getting user’s AAD Object Id with Graph SDK
Since the user’s AAD Object Id is required, when the user is added as a member to a tag, here is how to get the object id using the user’s email address. For this, User.Read.All permission needs to be added to the Azure AD Registered application.
Get-MgUser -Filter "Mail eq 'matti@demo.com'" | select Id
Afterword
Using Microsoft Graph PowerShell SDK in a real-world scenario, where some guest users needed to be invited and added to team tags, worked well. Using Graph API enables to use of just one PowerShell module, rather than using several for different functions. When working with this module it is required also to read Microsoft Graph API documentation for specific permission of different functions. Also, read carefully the documentation about Graph PowerShell SDK, since tag management is in beta, there might be changes when moving to v1.0.
Matti Paukkonen 