How to Extend Automation of Microsoft Online Services

How to Extend Automation of Microsoft Online Services

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

When creating provisioning rules, select one of the new MSOL Run actions.



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.

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 within 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

Available

Description

$CustomerID

Always

A reference to the Atria CustomerID (primary key of customers table)

$TenantId

When tenant exists in Azure AD

The Microsoft AzureAD globally unique tenantID  (GUID)

$UserId

When

The Atria numeric UserID (primary key of users table)

$UserAzureID

When user exists in Azure AD

The GUID of the user in Azure AD

$Session

When Exchange has been specified as a connect option

Holds the connection to the Exchange Remote Powershell session.

$GraphToken

When Graph has been specified as a connect option

Holds an access token for Microsoft Graph.

$SecurityCenterSession

When SecurityCenter has been specified as a connect option

Holds the PowerShell Session connection to the Security and Compliance Endpoint.


Writing your script

All environments are logged in to the tenant, except MSOnline, this runs in the partner context and you will need to pass –TenantId $TenantId to the commandlets to have them run in the context of the customer.
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

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.

Azure Active Directory (AzureAD)

In this example, we are creating an Azure AD Security group.  

Script : CreateAADSecurityGroup2.ps1

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

Adding the rule to call the script – the groupName is passed in and the AzureAD connection type is specified.  The script is parameterised but in this case we are hard coding the group name to “Senior Management”.  If you wanted to pass in a variable from the request, you would set the variables field to $groupName = {RequestParameter} 


Exchange Online (Exchange)

This example creates an Exchange Transport Rule to prepend all external email 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)

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


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

  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!

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

Script : CreateAADSecurityGroup.ps1

  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


Microsoft Partner Center API (PartnerCenter)

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.


    • Related Articles

    • How to Migrate from Hosted Exchange to Exchange Online

      Overview This article provides an example of how to migrate from the Atria Hosted Exchange Service to the Microsoft Online Service.  It will cover the change in service as well as data migration.  The process will use the following free Microsoft ...
    • Atria and CPSM impacted by Microsoft Exchange April Update

      Overview This issue impacts any version of CPSM or Atria used to manage Exchange 2013, 2016 or 2019 which have received the April Microsoft security update. Last week Microsoft released a set of critical security fixes to Exchange ...
    • How to configure Azure AD Custom Tenant Configuration Scripts

      Overview As part of the Atria Azure AD Service Sync Policies, you can assign custom configuration scripts that will be run each time the service is provisioned.  This is useful to ensure your customer's tenants are always configured with your ...
    • Atria v12.11+ System Requirements

      Overview  The following article provides the prerequisites necessary for the deployment of Atria v12.11+ into your environment.  System Requirements   Environment  Core servers for the platform should be domain joined. Before you can deploy Atria ...
    • Atria v12.11+ Deployment Guide

      Overview  This article outlines the deployment procedure of Atria v12.11+.  This article will also refer to other articles that may assist with your installation or upgrade. Alert:  In-place migration from any version of CloudPortal Services Manager ...