Overview

Since version 12.0, Atria has provided the capability to allow easy management of Azure AD and User-based subscriptions (such as Microsoft 365 and Office 365).  As a CSP provider operating at scale, you may have additional configuration changes you want to make via the many APIs available but the complexity of the Secure Application Model has made this difficult to implement. 

With Atria 12.6.7 we have introduced new Powershell actions which give you the ability to extend our default provisioning processes to meet your own needs, as well as giving you the ability to build your own services using Atria custom services.  The key benefit is that these actions set your Powershell connection up with the right security context needed to perform actions for the tenant or user.  

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

In order to use any of these actions in any provisioning rules, you must have the Azure AD service provisioned to the customer.

Key benefits

1. Enables execution of custom PowerShell scripts when provisioning tenants or users
2. Connection to Powershell providers handled seamlessly by Atria using the secure application model.
3. Rapidly build custom services to systematically deliver your own Microsoft 365 based services
   

How it works

There are two actions provided for your use – one for Customer/Tenant context (MSOL Run Customer Script) and one for user context (MSOL Run User Script)

Both are similar – the latter, just adds the user-specific parameters.

Currently, we can provide the correct context for executing the following API Connections:

Connection	Provider	Use for
AzureAD	Azure Active Directory Powershell 2.0	Azure AD management
Exchange	Exchange Online Powershell	Exchange configuration (uses Exchange online v1 Powershell)
Graph	Microsoft Graph	Provides graph token variable with an access token to allow you to send https requests to Microsoft Graph.
MSOnline	MS Online V1 Powershell module for Azure Active Directory	Older Powershell library for managing AzureAD and Office 365
PartnerCenter	Microsoft PartnerCenter Powershell	For managing subscriptions, billing, customer details within PartnerCenter
SecurityCenter	Office 365 Security and Compliance	Security and Compliance Configuration.

Action Parameters

CustomerID Parameter

The CustomerID is available on all provisioning requests and refers to the Atria numeric identified for the customer.  Use the {CustomerId} variable to refer to the CustomerID in the current request.

UserID Parameter

The UserID is available on all user-related provisioning requests and refers to the Atria numeric identified for the User.  Use the {UserID } variable to refer to the UserID in the current request.

Note: that this parameter is only available on the MSOL Run User Script action.

Connect Parameter

Options are AzureAD, Exchange, Graph, MSOnline, PartnerCenter, SecurityCenter (see above list for details) 

Provide one or more of the above as a comma-separated list to the connect Action parameter.  Atria will set up the connection and your script should just assume this is in place.

There are a few variables available to you without needing to pass them in:

ScriptFile Parameter

This is the location of your AD script.  The script is executed from the Atria MSOL Web Service, so the path to this script has to be accessible and available from the machine where this service is running.

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 THAT 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.

Writing your script

Where to locate your rules

1. $group = Get-AzureADGroup -SearchString $groupName
2.  
   
3. if ($group -eq $null) {
4.     #Create a new security group for the tenant
5.     New-AzureADGroup -DisplayName $groupName -MailEnabled $false -SecurityEnabled $true -MailNickName "NotSet"
6. }

1. #Create mail flow rule for adding External warning message for external mails
2.  
   
3. Invoke-Command -Session $Session -ScriptBlock {
4.  
5. $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>"
6.  
   
7. $RuleExists = false
8.     try { $tr = Get-TransportRule "External Email Warning"
9.           $RuleExists = true }
10.     catch
11.         { $RuleExists = false }
12.  
    
13.     # If the rule exists, then update it, else create the rule
14.     if ($RuleExists)
15. {
16.          #update transport rule
17.          Set-TransportRule "(Atria) External Email Warning" `
18. -FromScope NotInOrganization `
19.                     -SentToScope InOrganization -Priority 0 `
20. -ApplyHtmlDisclaimerText $Disclaimer `
21.                     -ApplyHtmlDisclaimerLocation Prepend `
22. -ApplyHtmlDisclaimerFallbackAction Wrap
23.                        
24.         }
25.     else {
26.          #create new transport rule
27.          New-TransportRule "(Atria) External Email Warning" `
28. -FromScope NotInOrganization `
29.                     -SentToScope InOrganization -Priority 0 `
30. -ApplyHtmlDisclaimerText $Disclaimer `
31.                     -ApplyHtmlDisclaimerLocation Prepend `
32. -ApplyHtmlDisclaimerFallbackAction Wrap
33.         }

1. $HeaderParams = @{
2.             'Content-Type'  = "application\json"
3.             'Authorization' = "Bearer $GraphToken"
4.             }
5. $Results = Invoke-RestMethod `
6. -Headers $HeaderParams `
7. -Uri
   
   $ResourceURI `
   
8. -UseBasicParsing `
9. -Method "GET" -ContentType "application/json"
10. Return
    
    $Results
    

Microsoft Online PowerShell (MSOnline)

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!

1. $group = Get-MsolGroup -SearchString $groupName
2.  
3. if ($group -eq $null)
4. {
5.     #Create a new security group called Senior Management for the tenant
6.     New-MsolGroup -DisplayName $groupName -TenantId $TenantID
7. }

The rule we have added is also dependent on the msolws