Managing Usernames and Passwords with PowerShell for SharePoint Online
If you are like me, you find yourself logging into your Office 365 tenant via PowerShell almost every day. And you are probably doing it one of two ways: either you are using a cmdlet to prompt you for the information and then manually typing it in (or cutting and pasting from a text file) OR you have hard coded the plain text credentials into a login script, and you just run it. I will be honest, up until recently I have done both and just hoped no one ever looked in the file labeled passwords.
Thanks to some questions on one of my YouTube Channel videos, I have learned and implemented a better way. In this article, we are going to start at the beginning to talk about the bad, the good, and the best ways to manage your accounts when it comes to PowerShell, including prompting, plain text variables, hashed files, and my new favorite, Windows Credential Manager. Once we have discussed all of the options, then the responsibility is on you to implement the correct solution. Ready? Let’s do this.
One quick note: This article assumes you have already installed the Office 365 PowerShell and the Patterns and Practices PowerShell. If you have not, then check out my previous article on Getting Started with PowerShell for SharePoint Online.
What is “Inside Microsoft Teams”?
“Inside Microsoft Teams” is a webcast series, now in Season 4 for IT pros hosted by Microsoft Product Manager, Stephen Rose. Stephen & his guests comprised of customers, partners, and real-world experts share best practices of planning, deploying, adopting, managing, and securing Teams. You can watch any episode at your convenience, find resources, blogs, reviews of accessories certified for Teams, bonus clips, and information regarding upcoming live broadcasts. Our next episode, “Polaris Inc., and Microsoft Teams- Reinventing how we work and play” will be airing on Oct. 28th from 10-11am PST.
Prompting for Passwords
This is the method that you will see most often, especially in “official” documentation. The idea is you use $Credentials = Get-Credentials , which will then cause a pop-up box to appear where you can type in your username and password that is then stored in a variable. This is a very secure way to go about things, other than the fact that 9 out of 10 people usually have a OneNote document or other documentation that they cut and paste the account info from. You don’t have to admit it, but we all do it. Ignoring that flaw, here is what your PowerShell usually looks like:
$askCred = Get-Credential Connect-msolService -Credential $askCred
That simple bit of PowerShell will have you logged into your tenant and ready to go. You could use something like Get-MsolUser to confirm everything is working.
ProTip: Do you use the same username every time? I bet you do. If so, then you can update the line to $askCred = Get-Credential -Credential [email protected] Then it will fill in the username automatically for you so that you only have to paste type in the password.
Passwords Hard Coded in a Script
I know, I am a bad person for showing this to you, but truth be told it is so common I feel like we at least need to discuss it. So, for better or worse here it is.
$un = "[email protected]" $pw = "HereToBeReadByAnyone" $sp = $pw | ConvertTo-SecureString -AsPlainText -Force $plainCred = New-Object system.management.automation.pscredential -ArgumentList $un, $sp Connect-msolService -Credential $plainCred
It starts with the sin of setting the variables $un and $pw with your information right there in plain text. So not only do they show up on your screen and in our stored script but they will also be in plain text in your transcripts and/or logs. This is not good.
With your secrets not so safely hidden in the variables, you then have to convert the $pw variable to a secure string. This is because PowerShell will not let you use a plain text variable. If you are going to do these bad things, then it is going to force you to convert it and then use the -force parameter to really drive home what a bad idea this whole thing is.
Once you have an encrypted password, then you can create the credential object by setting it using the $un and $sp variables to the variable $plainCred. With $plainCred in hand, you can use that with Connect-MsolService and you are in business. Connect-MsolService doesn’t judge you; it doesn’t know about the plain text, earlier.
This is a terrible way to do things, but because it is so very common, it is included here for completeness. Everyone I know is guilty of some form of this bad behavior. The good news is that you now understand it and could use it if someone held a gun to your head, and knowledge is power.
Using an Encrypted File
This method gives keeping your password secure a fighting chance. What you do is create a file on your local file system that has a hashed version of your password in it. The nice thing is that if someone finds the file, they will just see the crazy hash; they cannot directly use the hash because it is tied to your account. So even if they copy the file to their system and try to access it, they will get an error. Now with all of that said, this isn’t foolproof. The password is only hashed, and I bet if someone tried hard enough (or searched the internet hard enough), they could find a way to reverse it. But at that point, they are maliciously trying to break in, and that makes them a meanie. This method stops the casual passerby from accidentally tripping over your information but not the state sponsored hacker. So, plan accordingly. If you are storing my social security number on your SharePoint site, don’t use this method, either.
The first step, creating the file, just needs to be done once. To do so, you would use the following:
$credentials = Get-Credential $filename = 'C:\safe\secretfile.txt’ $credentials | Export-CliXml -Path $filename
This is prompting you for the username and password and then using the Export-CliXml cmdlet to securely write them to a file. You’ll find more details about it here if you are curious about the cmdlet. The cool thing is that only your account can decrypt the file. I would encourage you to take a moment to open the file with Notepad so that you can see what is going on.
Now that you have the file on your system, you can reference the credentials in all of your scripts using the following:
$credPath = ‘C:\safe\secretfile.txt’ $fileCred = Import-CliXml -Path $credPath Connect-msolService -Credential $fileCred
There is one thing to consider: If you are going to use this as part of an automated process, like a scheduled task, then the account that the job runs as has to be the same account you created the secure file with. Should make sense, you just need to consider which account is used for what.
Pretty cool and pretty easy. This is a solid method for making your life easier. Thanks to Todd Klindt for writing the original blog post on using this method with SharePoint on prem. Everything here was adapted with his permission, so you can’t tell on me but to rub salt in the wound, I should make him proofread this section.
Windows Credential Manager
Get ready for the safest, securest method that will change your life. You will brag to your friends about your skills after you put this method into place. Try not to gloat too much.
Windows has had Credential Manager built in for a long time, and honestly, most of us have just ignored it. The tool to me was always just there to store internal passwords and to give IE/Edge a dumping ground when you stored passwords for websites. Well, today we are going to unlock that monster and show you how to use it with PowerShell.
To open Credential Manager, press the Windows Key and type in Credential Manager. If you don’t know how to use the Windows key, then you can also just manually navigate to Control Panel and find the tool that way. Once there, you will want to click on Windows Credentials, so you have something like the following screenshot.
And don’t worry, you aren’t going blind in just your left eye, I blurred my accounts on purpose. I don’t need any of you looky-loos to go playing with my accounts. Anyway.
Now you want to add your credentials by clicking on Add a Windows Credential.
When prompted for Internet or network address, type in the name you want to use. For me the name is o365, but do what you want. I wouldn’t use a space in the name, though; that’s just a PowerShell nuisance you don’t want.
Then enter your username and password. If it all looks good, then click OK.
Here is my screenshot with fake information. I wish my password was that long.
Now that we have the information securely saved in Credential Manager, we need to download some new cmdlets to use it with PowerShell. To do that, switch back over to your PowerShell console. Make sure you are running PowerShell as an administrator and then type the following:
Install-Module -Name CredentialManager
This will download the CredentailManager module from the PowerShell Gallery. This is not a Microsoft built tool, some kind person built and released it to the world for free. I use it without issue, but if you are the paranoid type, be sure to vet it yourself fully. Not everything on the Internet is true or safe, but I feel pretty good about this one.
Now you can use one of the four cmdlets in this package to make your life so much easier.
$managedCred = Get-StoredCredential -Target o365 Connect-msolService -Credential $askCred
You are just using the new cmdlet Get-StoredCredential to pull from Credential Manager the entry you just created. You store that in a variable, and then you can reference it with your Connect cmdlet. How simple is that? No more typing account info, no more plain text, no more evil villains stealing my social security number. What a happy day.
Protip: Username and passwords stored in Credential Manager can be used with the Patterns and Practices (PNP) PowerShell natively. An example would be:
Connect-PnPOnline -Url https://yourtenant-admin.sharepoint.com -Credentials o365
PowerShell doesn’t get any easier than that.
Now It Is Up to You
We have walked through all of the fun ways you can manage credentials for PowerShell. What method will you use?
As always, because I am the nicest guy you know, there is also a companion video to go with this article. So, if you want to see my beautiful face and hear me talk about all of this, check out the video below.