Atom Skills: Add to distribution list (Azure AD)

Enable employee self-service through Atom skills. Your employees can add themselves to distribution lists automatically or after approval, without waiting for an administrator to intervene.

The playbook

1. An end-user asks Atom to add them to a distribution list

2. Atom asks them to choose the distribution list and state the reason for the inclusion. If there's an approval policy associated with the DL, an approval notification is sent to the approvers.

3. Once it's been approved, the end-user is notified.

This skill requires an Azure Automation and a Powershell runbook script. Once you've set it up, you need to copy the webhook into Atomicwork's settings. If you've already done these parts and just want to skip ahead to setting up the skill, scroll to the end.

Connect Azure Automation and the Powershell runbook script

Step 1: Configure a Powershell (7.2 version) based runbook that has ExchangeOnlineManagement & ExchangePowerShell modules

Use this code:

param( [object]$WebhookData )
try { "Logging in to Exchange..." Connect-ExchangeOnline -ManagedIdentity -Organization atomicwork.onmicrosoft.com "Adding user..." $webhookBodyObject = (ConvertFrom-Json -InputObject $WebhookData.RequestBody) Write-Output "Hello $webhookBodyObject" Write-Output $webhookBodyObject.email Write-Output $webhookBodyObject.distribution_list_id Add-DistributionGroupMember -Identity $webhookBodyObject.distribution_list_id -Member $webhookBodyObject.email "User Added" }
catch { Write-Error -Message $_

Step 2: Install ExchangePowerShell & ExchangeOnlineManagement modules

Go to Automation account > Modules > Add module > Browse from gallery > Search for "ExchangePowerShell" and click on Select. Repeat for ExchangeOnlineManagement

Step 3: Assign a role to the automation account

Go to Microsoft Entra Id > Roles and Administrators > search for Exchange administrator. Click on Add assignments > Search for the automation account you created and assign it.

Step 4: Assign all requisite permissions through Powershell

Managed identity id: Go to Enterprise apps > uncheck Application type = Enterprise Applications > search for your automation account and get its object ID. Copy this into notes.

Similarly, search for Office 365 Exchange Online and copy the object ID for serverServicePrincipalObjectId into your notes as well.

Get the App role ID for the Exchange.ManageAsApp permission. You can do this either through APIs or Powershell.

https://graph.microsoft.com/v1.0/servicePrincipals/{{theObjectId you got in prev step for office 365}}

Grab the id Exchange.ManageAsApp

Now, run this script in Powershell (Powershell is inevitable). Your end result should look something like this:

Install-Module -Name Microsoft.Graph.Authentication -Repository PSGallery -Force
Install-Module -Name Az.Accounts -Repository PSGallery -Force
Install-Module -Name Microsoft.Graph.Applications -Repository PSGallery -Force
 
Connect-MgGraph -Scopes Application.Read.All, Application.ReadWrite.All,AppRoleAssignment.ReadWrite.All,Directory.ReadWrite.All
 
New-MgServicePrincipalAppRoleAssignment `
-ServicePrincipalId $managedIdentityObjectId `
-PrincipalId $managedIdentityObjectId `

Step 5: The Webhook

Go to your runbook > Add webhook > Give the webhook a nice name and leave the parameters empty. The tough part is over!

Let's test it out. Go to your favorite API testing tool and try this out:

curl --location 'yourwebhookurl' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "youruserPrincipal",
"distribution_list_id": "your dl id"
}'

You should have been added to the distribution list ID :)

Setting up the skill

1. Go to Settings > Workspace > Skills > Click on Add to distribution list

2. Paste in the webhook URL

3. Select the distribution lists you'd like to give access to. Click on Enable.

4. Choose the approval policy - you can set one up or waive it for certain distribution lists.

And we're done!