Extend Automation of Microsoft Online Services

Overview

Atria provides the capability to manage Microsoft 365 and user-based subscriptions efficiently. As a CSP provider operating at scale, you may have additional configuration changes to make via the available APIs, but the complexity of the Secure Application Model can make this challenging.

To address this, Atria includes PowerShell actions that enable you to extend default provisioning processes to meet your needs. You can also build custom services using Atria custom services. These actions set up your PowerShell connection with the correct security context required to perform actions for the tenant or user.

This allows you to seamlessly use the PartnerCenter connection configured in Atria using the Secure Application Model.

Ensure you have read and understood the Provisioning Manager guide before continuing with this guide.

Prerequisite: The Azure AD service must be provisioned to the customer to use these actions.

Key Benefits

Execute custom PowerShell scripts when provisioning tenants or users.
Seamless connection to PowerShell providers through Atria’s secure application model.
Rapidly build custom services to deliver Microsoft 365-based services.

How It Works

Atria provides two actions:

MSOL Run Customer Script (for Customer/Tenant context)
MSOL Run User Script (for User context, adding user-specific parameters)

Currently, we support the following API connections:

Connection Provider	Use for
Exchange	Exchange Online PowerShell - Exchange configuration (uses Exchange Online v1 PowerShell)
Graph	Microsoft Graph - Provides a graph token variable with an access token to send HTTPS requests to Microsoft Graph
MSOnline	MS Online V1 PowerShell module - Older PowerShell library for managing Azure AD and Office 365
PartnerCenter	Microsoft PartnerCenter PowerShell - For managing subscriptions, billing, and customer details

Action Parameters

CustomerID Parameter

The CustomerID is available on all provisioning requests and refers to the Atria numeric identifier for the customer.

Use {CustomerId} to reference it in the request.

UserID Parameter

The UserID is available on all user-related provisioning requests and refers to the Atria numeric identifier for the user.

Use {UserID} to reference it in the request.

Note: This parameter is only available for MSOL Run User Script.

Connect Parameter

Available options: Exchange, Graph, MSOnline, PartnerCenter

Provide one or more as a comma-separated list. Atria will set up the connection accordingly.

ScriptFile Parameter

This is the location of your PowerShell script. The script must be accessible from the machine where the Atria MSOL Web Service runs.

webServiceConnection

This specifies the details needed to connect the MSOL web service. This is contained as a parameter in the provisioning request for the Microsoft Online or AzureAD services. If you are creating your own service, the webServiceConnection will not be available in the context of your request. You can use the MSOL Add WebService Connection action to retrieve the correct connection details and add them to your provisioning request. This action will only work in the primary location as it queries the Atria database to extract the connection data. Add rules that use this action and communicate with the Microsoft Online service into the pre-request section of your provisioning rules.

note

You must have the Azure AD service successfully provisioned in order for Atria to be able to make any calls to Microsoft Online services on your behalf.

resultProperty

This specifies the property for any data you wish to return to the provisioning request from the script.

timeout

Specifies the timeout in seconds to use when performing operations against APIs.

Optional Parameters

Use optional parameters to pass information from the provisioning request into your script. To add parameters, increase the Optional Parameters property.

Note the Syntax, this is configuring the PowerShell variables in your script. Each of the $variables defined can be used in your script. These parameters are passed by value, any changes made, will not be reflected in the request variables after the action has executed.

Additional Variables Available in Your Script

The following variables are available for use within your script by default – you do not need to pass them in as optional parameters.

Variable Name	Availability	Description
`$CustomerID`	Always	Atria CustomerID (Primary Key of Customers Table)
`$TenantId`	When tenant exists in Azure AD	Microsoft AzureAD globally unique TenantID (GUID)
`$UserId`	When user exists	Atria numeric UserID (Primary Key of Users Table)
`$UserAzureID`	When user exists in Azure AD	GUID of the user in Azure AD
`$Session`	When `Exchange` is used	Connection to Exchange Remote PowerShell session
`$GraphToken`	When `Graph` is used	Access token for Microsoft Graph

Writing Your Script

Important: All environments log into the tenant, except MSOnline, which runs in the partner context. You must pass –TenantId $TenantId to the cmdlets for customer-specific actions.

Note that when you attach to provisioning events, their system does not differentiate between a create (the first execution) and an update (any subsequent execution), as such you need to ensure that your script can be re- executed and caters for any objects which may have already been created by a previous execution of the script.

Where to Locate your Rules

As the Microsoft Online Service is always interacting with Microsoft services, this is always deployed in the primary Atria location. Any provisioning rules are best placed in the “Post” provisioning sections.

For your own custom services – place your rules in the “Main” section.

If you are adding processes to an existing service, place your rules in the “Before” or “After" section.

Remember that all the variables within the request are available for you to feed in to your Powershell scripts.

Usage Notes and Examples

important

Make sure to tick the Rule enabled box on the general tab of your Rules, for them to function.

Getting the Connection to the Web Service

In order to execute any PowerShell commands we have to get a connection to the MSOL Web Service. Add a rule to run the “MSOL Add WebService Connection” action – this will locate the correct connection details and add it for subsequent use.

The rule below will store the connection details in the msolws variable.

This step is required for all of the examples in this document.

Exchange Online (Exchange)

Example 1

This example takes the Custom Attribute properties for a user and adds them to their Exchange mailbox. The script is triggered on the provision of the Microsoft Online service, and only updates the values if they are currently blank, stopping overwriting.

 # Retrieve the user from Exchange Online
$Mailbox = Get-Mailbox -Identity $UserPrincipalName

if ($Mailbox) {
    # Update CustomAttribute1 only if it is not already set
    if (-not $Mailbox.CustomAttribute1) {
        Set-Mailbox -Identity $UserPrincipalName -CustomAttribute1 $Custom1
    }

    # Update CustomAttribute2 only if it is not already set
    if (-not $Mailbox.CustomAttribute2) {
        Set-Mailbox -Identity $UserPrincipalName -CustomAttribute2 $Custom2
    }
}

# Disconnect from Exchange Online
Disconnect-ExchangeOnline -Confirm:$false 

The rule needs to be created in the following location. This can be changed depending on when you want the script to be triggered:

The contents of the rule takes various properties from Atria to be used within the script:

Example 2

This example creates an Exchange Transport Rule to prepend all external emails with a highlighted block of text “[Warning - this email was received from an External sender!]” Note the Invoke-command used with the $Session variable to execute the contained script within the context of the session which Atria has automatically set up within the correct context for the tenant specified in the action parameter.

SetExternalEmailTransportRules.ps1 (stored on the same server as the MSOL Web Service)

This example creates an Exchange Transport Rule to prepend external emails with a warning message:

Invoke-Command -Session $Session -ScriptBlock {
    $Disclaimer = "<p><div style='border:solid #9C6500 1.0pt;padding:2.0pt 2.0pt 2.0pt 2.0pt'><p class=MsoNormal style='line-height:12.0pt;background:#FFEB9C'> <b><span style='font-size:10.0pt;color:#9C6500'></span></b><span style='font-size:10.0pt;color:black'> [Warning - this email was received from an External sender!]<o:p></o:p></span></p>"
    New-TransportRule "(Atria) External Email Warning" `
    -FromScope NotInOrganization `
    -SentToScope InOrganization -Priority 0 `
    -ApplyHtmlDisclaimerText $Disclaimer `
    -ApplyHtmlDisclaimerLocation Prepend `
    -ApplyHtmlDisclaimerFallbackAction Wrap
}

The rules to be added are as follows:

The second rule executes the script – we specify the {customerid} which is available in the request and use the msolws variable we added to the request in the prior step. We need to connect to Exchange Online Powershell so we specify “Exchange” for the connect parameter. The scriptFile refers to the script, the path must be resolvable in the context of the Microsoft online web service.

Microsoft Graph (Graph)

Microsoft Graph is becoming the foundation for easy integration with Microsoft services, Graph has a restful API which can be easily invoked from within Powershell to both extract data and perform changes. Microsoft Graph has an advanced permissions system, the Atria application must be granted the correct permissions in order to execute the Graph query/command. You may need to add additional permissions in order to execute your scripts.

Example script – the Graph URI is passed as the $ResourceURI parameter

$HeaderParams = @{
    'Content-Type' = "application/json"
    'Authorization' = "Bearer $GraphToken"
}

$Results = Invoke-RestMethod `
    -Headers $HeaderParams `
    -Uri $ResourceURI `
    -UseBasicParsing `
    -Method "GET" -ContentType "application/json"

Return $Results

Microsoft Online PowerShell (MSOnline)

note

This runs in the context of the partner – you will need to ensure that you add the –TenantID $TenantID parameter to all commandlets in your script to ensure they act on behalf of the correct customer.

In this example, we have written a simple script that will create an Azure AD security group using the MSOL Powershell library.

$group = Get-MsolGroup -SearchString $groupName

if ($group -eq $null)
{
    # Create a new security group called Senior Management for the tenant
    New-MsolGroup -DisplayName $groupName -TenantId $TenantID
}

The rule we have added is also dependent on the msolws

With this group being created, You could pass this into another that retrieves the members of this group, using the Msol User Run Script, and example of this is below.

Script:

$group = get-msolgroup -searchstring $groupName -TenantId $TenantID

if ($group){
    # Group Exists, continue
}
Else{
    throw 'Specified Group does not exist'
}

# Get Group from AzureAD
$user = Get-MsolGroupMember -GroupObjectId $group.objectID -TenantId $tenantId

if ($Users -eq $null)
{
    Return 'Group has no members'
}

# If user isn't in group, add them to MFA Enable Group
else{
    Return $Users
}

Connecting to Multiple Services

You can connect to multiple services if needed. So if you have one large script that talks to multiple Powershell interfaces, you can comma separate the providers you need on the connect parameter of the rule.

If you experience any issues or require any assistance with this process, please contact us at support@getatria.com.

Overview​

Key Benefits​

How It Works​

Action Parameters​

CustomerID Parameter​

UserID Parameter​

Connect Parameter​

ScriptFile Parameter​

webServiceConnection​

resultProperty​

timeout​

Optional Parameters​

Additional Variables Available in Your Script​

Writing Your Script​

Where to Locate your Rules​

Usage Notes and Examples​

Getting the Connection to the Web Service​

Exchange Online (Exchange)​

Example 1​

Example 2​

Microsoft Graph (Graph)​

Microsoft Online PowerShell (MSOnline)​

Connecting to Multiple Services​