Benoit HAMET

UPDATE: script update to enable Azure MFA and correct a bug in the Office 365 role update function

Office 365 Role membership management is one of the few workload you can not manage using groups.

To automate the membership of these roles I have created a script.

The script is comparing Active Directory group membership with the corresponding Office 365 Role, excluding online account added to the Office 365 role. If there is any difference, the script will automatically grant or revoke role membership based on the AD group.

 

Prerequisites

To take advantage of this script you need the following requirements:

NOTE the script will only work with existing AD group matching the Office 365 role

  • Active Directory user accounts used to manage the role permission are synchronized
  • All accounts have a routable UPN – i.e. not using @domain.local. If not you will got the error “Access Denied. You do not have permissions to call this cmdlet.” when updating Office 365 role
  • Use an account with Office 365 Global Administrator; it will be needed to update Office 365 role membership.If you plan to use the script with a scheduled task you need to use a service account with the password set to never expire
  • A service mailbox you can authenticate with to send email notifications after completion

Script Usage

The script can be executed manually or used with a scheduled task; if you use it with a schedule task, you have to manually run it once to generate all the required credentials to connect to Office 365.

Script Variables

There are few variables you have to update to match your environment

  • $ScriptFolder defines the folder location where the script is saved; set by default to C:\Scripts. It is optional to update. All encrypted credentials files and log files will be saved in this directory
  • $GroupOU defines the organizational unit where the AD groups used for Office 365 Role management are located; this OU does not need to be synchronized with Office 365. For example, $GroupOU = "Office 365 Roles Management"
  • $MFAEnabled defines if you want to enable Azure MFA; the script will ask if you want to enable or not Azure MFA – if you do not answer within 20 seconds it will apply the default (MFA enabled); this helps the script to detect if it is running interactively or with a scheduled task
  • $SMTPServer to define the SMTP server to use for sending email notification. For example, $SMTPServer = "smtp.domain.com"
  • $SMTPPort to define the communication port to use to connect to the SMTP server – usually 25 or 587
  • $From defines the FROM field of the email notification; it does not need to be an existing email address
  • $To defines the recipient for the notification. If you want to define multiple recipients, separate each recipient with a coma. For example, $To = "recipient1@domain.com","recipient2@domain.com"

 

Manual Execution

After updating the above variables, just run the script.

You will be prompted if you want to save the credentials to connect to Office 365 and the SMTP server.

Whatever your decision you will be prompted for your credentials but if you choose to save them, 3 or 6 encrypted files will be generated to save the account, the password and the encryption/decryption key. 3 files are used for each credentials.

 

Use with a scheduled task

If you plan to use the script with a schedule task you need to manually run the script once and choose to the save the credentials.

NOTE if at any time you hit the cancel button during the authentication requests, the script will stop

 

Saved credentials

If you choose to save the credentials, 3 files are generated for this credential.

  • <credential>_account.txt is the encrypted file containing the user account
  • <credential>_password.txt is the encrypted file containing the password
  • <credential>_key.key is the encryption/decryption key

Where <credential> is the service you are going to authenticate against; like office365 for Office 365 or smtp for the SMTP server.

You will not be prompted if the 3 required files for the credential already exist; if you want to ‘overwrite’, just delete one of the file

 

User Interface

The following screenshots show the different UI you have

Prompt to save credential Credentials not being saved Credential being save  
    User account prompt Password prompt
image image image image
image image image image
Prompt to enable Azure MFA      
image This pop up is “time bombed”; if you do not answer within 20 seconds the default settings (MFA enabled) is applied.
This allows the script to detect if it is running interactively or with a scheduled task		    

 

Log file and notification

All actions executed by the script are logged.

If any error occurs during the execution, the error’s details are captured and saved in the log file. The notification email will show there has been an error during the execution of one step

Below a sample of the notification email and an extract of a sample log file (attached to the notification email)

imageimage

 

Getting the script

You can download the script from the TechNet Script Gallery here https://gallery.technet.microsoft.com/Automatic-Office-365-Role-433d5120

Please provide any feedback or question there, thanks.