In the current article, we will learn how to create a PowerShell script, which will help us to connect automatically to Office 365 (Windows Azure Active Directory) and Exchange Online, without the need of typing complicated PowerShell commands!
The added bonus that I would like to add to this “automation” is – a method that will enable us to avoid the need to provide our global administrator credentials, each time we run the PowerShell script.
Q1: Why should I need to use a “PowerShell script” for connecting Office 365?
A1: Office 365 infrastructure, include many different “infrastructures” such as – Windows Azure Active Directory, Exchange Online, SharePoint online, etc.
When we need to use a remote PowerShell session, we will need to use different procedures for connecting each of this infrastructure, and provide our credentials separately for each of the different Office 365 infrastructures.
The solution to this “a headache” could be a PowerShell script, that “contain” all the required PowerShell commands that we need to use for connecting each of the different Office 365 infrastructures.
Q2: What about the need for providing the user credentials and using PowerShell script?
A2: By default, when using a PowerShell script in an Office 365 environment, that need to provide user credentials, we use a PowerShell such as – Get-Credential.
The Get-Credential displays a pop out credential’s windows in which the user needs to fill in his credentials. The information about the user credentials can saved in a variable, and we can use these provided credentials for connecting each of the different Office 365 infrastructures.
When using this option, we will need to provide the required user credentials, each time we run the PowerShell script.
Q3: Is there a way that we can use that will enable us to avoid the need of providing our credentials, each time we run the PowerShell script?
A3: Yes, there is!
Technically speaking, we can add the Office 365 global administrator credentials to the PowerShell script, meaning, the global administrator username + password.
Although this option can implement; this is a dreadful solution from the security perspective because the PowerShell script is a simple text file that can easily be read by any user.
Q4: Is there a more secure solution for the issue of “credentials” when using PowerShell script
A4: Yes, there is!
The good news is that the PowerShell includes a built-in mechanism, which enables us to save user credentials in a text file in a secure manner.
The information in the text file will be encrypted so, although the information stored in a simple text file, the information is useless for non-authorized users.
Only the PowerShell will be able to access the encrypted file and fetch from the file the required information.
PowerShell script and user credentials
In a scenario in which we need to use a PowerShell script that needs to provide user credentials, we can choose one of three options:
1. Write the password as part of the PowerShell script
Add the password to the PowerShell script file – this is the simplest option but, from the security perspective, this is the worst option because the password kept in a text file in a non-encrypted format. (we will not review this option).
2. Provide user credentials when running the PowerShell script
In this scenario, the PowerShell script includes an “empty variable” that will contain the required user credentials.
When we run the PowerShell script, pop out window will appear.
The person the execute the PowerShell script will need to provide the required credentials.
The information about the user credentials will be saved in encrypted format in the desktop RAM and will be “removed” when we close the PowerShell session.
From the security perspective, this is a better option because the credentials are encrypted.
The main disadvantage of this method is, that in case that we need to run the PowerShell automatically without the need to provide our credentials each time or when using an option
such as – Windows task scheduler, we can not use this option.
In this scenario, we need a “human element” that will need to provide the required credentials.
3. Saving the credentials in an encrypted file
In this method, we provide in advance the required user credentials, by saving the credentials in an encrypted file. The file stored on the desktop, from which we run the PowerShell script.
In this scenario, we implemented a two-phase procedure:
Phase 1 – saving the password using encrypted format
In this step, we use a PowerShell command that will encrypt the user credentials.
If we want to be more accurate, we will encrypt only the part of the “password,” and not the username.
We will need to provide PowerShell the “user password,” and the PowerShell command will take this password, encrypt the password and save it in a text file.
In other words, the information is not readable by a human.
Phase 2 – Creating to PowerShell script that will read the credentials
In this second phase, we write a PowerShell script, which will read the encrypted user credentials and use these credentials for the remote PowerShell session to the Windows Azure Active Directory, Exchange Online, etc.
To be able to demonstrate the required setting, we will use the following scenario:
Our business requirements are:
- Create a PowerShell script, that will enable us to connect to Windows Azure Active Directory infrastructure + Exchange Online infrastructure at the same time.
- Configure the “Office 365 remote PowerShell script” to read a local encrypted user credential, so we will be able to run the PowerShell script and connect automatically to Office 365.
Running a PowerShell script first time configuration
To be able to run a PowerShell script that will connect us to Office 365 infrastructure, we will need to connect to Exchange Online PowerShell.
Note – If you want to get more detailed instructions read the article – Connect to Office 365 and Exchange Online using a Script
Set the PowerShell execution policy to enable us to run a script
We enable our PowerShell console to run the script by running the PowerShell console as administrator and use the following PowerShell command:
Set-ExecutionPolicy Unrestricted -force
Writing a PowerShell script that will connect us to Office 365 | Using saved encrypted user credentials
Our scenario includes three phases:
- Phase 1#3 – save the password to a file and encrypt the password using PowerShell command.
- Phase 2#3 – write a PowerShell script, that will use the encrypted password + create a remote PowerShell session to Windows Azure Active Directory + Exchange Online.
- Phase 3#3 – running the remote PowerShell script – verifying that the script Operating properly
Task 1#3 – save the password to a file and encrypt the password using PowerShell command.
In this scenario, we want to implement a solution, in which the PowerShell script will be able to access a predefined credential stored in a file.
The user credentials will be saved using an encrypted text file.
To be able to encrypt the user credentials, we will use a combination of two PowerShell command
- Get the user password
We will use the PowerShell command:
Read-Host -Prompt “<text>” -AsSecureString
- The second PowerShell command will take the input from the former command, and implement the following tasks:
- Create a new text file.
- Save the password to the text file.
- Encrypt the password.
We will use the PowerShell command –
ConvertFrom-SecureString | Out-File “Path”
An example of the complete PowerShell command syntax is:
Read-Host -Prompt "<text>" -AsSecureString | ConvertFrom-SecureString | Out-File "Path"
In our scenario, we will use the PowerShell command with the following parameters:
- The text file will be named – cred.txt
- The cred.txt will be created and saved in the following path – C:\users\administrator
Read-Host -Prompt "Enter your tenant password" -AsSecureString | ConvertFrom-SecureString | Out-File "C:\users\administartor\cred.txt"
In the following screenshot, we can see an example of using the command in the PowerShell console:
As a result, a prompt appears, asking as to type the password
In the following screenshot, we can see that the password saved to a file named cred.txt.
In the following screenshot, we can see the content of the encrypted text file that created.
Task 2#3 – Creating the remote PowerShell connection script to Office 365
The PowerShell script that we are going to create includes two parts:
Part A – this is the part which deals with the saved encrypted user credentials.
Part B – this is the part that includes the PowerShell commands that create the remote PowerShell connection to the Windows Azure Active Directory and Exchange Online.
Part A – user credentials
In this part, we define three variables:
- $AdminName – the Office 365 UPN name of the user whom we use for creating the remote PowerShell connection with the Windows Azure Active Directory and Exchange Online
- $Pass – a variable that contains the PowerShell command, that access the encrypted password file and “fetch” the password.
- $Cred – a variable that will store the credentials that include the user name + password
Note – the variable names are just an arbitrary name, whom I use. You can define other variable names that will suit your needs.
$AdminName = "UPN Name"$Pass = Get-Content "<Path>" | ConvertTo-SecureString$Cred = new-object -typename System.Management.Automation.PSCredential -argumentlist $AdminName, $Pass
In our scenario, we will use the PowerShell command with the following parameters:
$AdminName = "email@example.com"$Pass = Get-Content "C:\users\administrator\cred.txt" | ConvertTo-SecureString$cred = new-object -typename System.Management.Automation.PSCredential -argumentlist $AdminName, $Pass
In the following screenshot, we can see an example of the required PowerShell syntax that we use in our specific scenario:
Part B – Remote PowerShell commands
This section contains the PowerShell command that will we use for creating the remote PowerShell connection
Import-Module MSOnlineConnect-MsolService -Credential $cred$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $cred -Authentication Basic -AllowRedirectionImport-PSSession $Session
In the following screenshot, we can see an example of the PowerShell syntax in the script.
- Part 1 – include the remote PowerShell command for connecting Windows Azure Active Directory.
- Part 2 – include the remote PowerShell command for connecting Exchange Online.
Saving the PowerShell script file
Assuming that we add all the required PowerShell commands to the editor, the next step is – saving the text file as a PowerShell script.
- In the section – Save as type” select the option – All Files (*.*).
- The additional recommended option is, to save the PowerShell script using UTF-8 This is not a mandatory requirement, but, from my experience, when saving the PowerShell script using standard formats such as ANSI, we can experience a problem when we try to run the PowerShell script from the PowerShell console.
In our scenario we save the PowerShell script using the name – connect365encrypted.ps1 in the path C:\script
Task 3#3 – Running the PowerShell script
We will run the remote PowerShell connection script from the PowerShell console, by using the following steps:
1. “Navigate” the PowerShell script location PowerShell script
To be able to execute the PowerShell script, we need to navigate to the path in which the PowerShell script located.
In our scenario, the PowerShell script is located in the c:\script folder.
Type the following command: cd c:\script and ENTER
2. Provides the PowerShell script name
To execute a PowerShell script, we need to start the command with the following characters – “.\” and then, type the name of the PowerShell script.
For example: .\connect365encrypted.ps1
Another useful option that we can use is the PowerShell autocomplete feature.
Instead of writing the “full name” of the PowerShell script, we can type the first letters of the PowerShell script name and let PowerShell complete the rest of the script name.
For example, to call a PowerShell script, we need to write the following characters – .\ and then, type the first letter\s of the PowerShell script such as co.
To start the l autocomplete feature, we hit the TAB key.
After “hitting” the TAB Key, The PowerShell console will automatically complete the rest of the PowerShell script name by himself.
In the following screenshot, we can see that the PowerShell script successfully manages to read the encrypted user credentials and connect the Office 365 infrastructure.
After the PowerShell script manages to connect to Office 365, we can start to use the required PowerShell commands.
To be able to verify that we connected to the Windows Azure Active Directory, we can try to type the following PowerShell command – Get-Msoluser
In the following screenshot, we can see that we successfully manage to display the Office 365 user list:
To be able to verify that we connected to Exchange Online, we can try to type the following PowerShell command – Get-Mailbox
In the following screenshot, we can see that we successfully manage to display a list of Exchange Online mailboxes.
You can download an example of the PowerShell script named:
Connect to Office 365 using PowerShell script + using saved encrypted user credentials
The current PowerShell script will enable you to use an encrypted password that was saved in a preliminary step for automatically create a remote PowerShell session to Azure Active Directory and Exchange Online.
You can read more information in the article – How to Connect to Office 365 using PowerShell script + using saved encrypted user credentials