Connect-SPOService: Connect to SharePoint Online With PowerShell

How to connect to SharePoint Online with PowerShell

Run Connect-SPOService -Url https://<your-tenant>-admin.sharepoint.com, replacing the placeholder with your tenant's SharePoint admin address. The cmdlet connects a SharePoint Administrator or SharePoint Embedded Administrator to the SharePoint admin center, and you must run it before any other SharePoint Online cmdlet. It comes from the SharePoint Online Management Shell module, Microsoft.Online.SharePoint.PowerShell.

Connect-SPOService -Url https://contoso-admin.sharepoint.com

With no other parameters, PowerShell opens a sign-in dialog. That is also the form to use when the admin account has multifactor authentication (MFA). Only one SharePoint Online connection is supported per Windows PowerShell session and per geo within an organization. If you run the cmdlet again, the existing connection is disconnected and replaced, and the session continues in the newly specified administrator context. Partner admins who manage several organizations from one session must reconnect when they switch.

Before you connect

You need:

• A SharePoint Administrator or SharePoint Embedded Administrator account. The account must be able to open the SharePoint admin center. That page also shows how to work out the tenant name for the admin address.
• The SharePoint Online Management Shell module. Check whether it is already installed, in an administrator PowerShell window:

Get-Module -Name Microsoft.Online.SharePoint.PowerShell -ListAvailable | Select Name,Version

If it is missing and you are on Windows PowerShell 5, install it:

Install-Module -Name Microsoft.Online.SharePoint.PowerShell

Without administrator rights, install it for the current user only:

Install-Module -Name Microsoft.Online.SharePoint.PowerShell -Scope CurrentUser

Microsoft recommends keeping the module current so you have every cmdlet. To update it, in an administrator window:

Update-Module -Name Microsoft.Online.SharePoint.PowerShell

You can also install the SharePoint Online Management Shell from Microsoft's download and open it from the Start screen by typing sharepoint.

PowerShell 7

To run SharePoint Online commands in a Windows PowerShell 7 console, import the module with the -UseWindowsPowerShell parameter first:

Import-Module Microsoft.Online.SharePoint.PowerShell -UseWindowsPowerShell

Connect with a user name and password

Connect-SPOService -Url https://contoso-admin.sharepoint.com -Credential admin@contoso.com

PowerShell then shows the credential dialog and asks for the password of the SharePoint admin account. To pass a credential object from a script instead, build it from a secure string:

$username = "admin@contoso.sharepoint.com"
$password = Read-Host -Prompt "Enter user password" -AsSecureString
$cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $userName, $password
Connect-SPOService -Url https://contoso-admin.sharepoint.com -Credential $cred

Connect when the admin account uses MFA

Leave out -Credential:

Connect-SPOService -Url https://contoso-admin.sharepoint.com

1. In the Microsoft SharePoint Online Management Shell dialog, enter the account name and password of a SharePoint administrator and select Sign in.
2. Follow the prompts for the extra verification, such as a code, and select Sign in again.

You can then run SharePoint Online commands.

Connect with modern authentication

If you hit problems connecting, or you see the message "Could not connect to SharePoint Online", Microsoft's guidance is to use modern authentication:

Connect-SPOService -Credential $creds -Url https://tenant-admin.sharepoint.com -ModernAuth $true -AuthenticationUrl https://login.microsoftonline.com/organizations

-ModernAuth must be used together with -AuthenticationUrl.

Sign in with the system browser

-UseSystemBrowser $true signs in through the Microsoft Authentication Library (MSAL) and your system browser, and connects once sign-in succeeds:

Connect-SPOService -Url https://contoso-admin.sharepoint.com -UseSystemBrowser $true

To avoid typing the parameter every time, set a REG_DWORD value named UseSystemBrowser under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SPO\CMDLETS\. A non-zero value, or the parameter set to true, makes sign-in use the system browser.

Connect without a person signing in

For scheduled scripts, Connect-SPOService can authenticate as an app or as a managed identity. App sign-in needs an app's client ID (-ClientId, alias -ApplicationId) and the tenant ID (-TenantId), plus a certificate in one of three forms.

Certificate file:

$password = Read-Host -Prompt "Enter certificate password" -AsSecureString
Connect-SPOService -Url https://contoso-admin.sharepoint.com -ClientId 00000000-0000-0000-0000-000000000000 -TenantId 11111111-1111-1111-1111-111111111111 -CertificatePath C:\Certs\ContosoAppAuth.pfx -CertificatePassword $password

Certificate thumbprint (the certificate sits in the current user's certificate store):

Connect-SPOService -Url https://contoso-admin.sharepoint.com -ClientId 00000000-0000-0000-0000-000000000000 -TenantId 11111111-1111-1111-1111-111111111111 -CertificateThumbprint "3FAAAA1111AAAAAAAAAAA2222AAAAAAAAAAAAAAA"

Certificate object:

$thumbprint = "3F2A5C9D4E7B8A1234567890ABCDEF1234567890"
$cert = Get-ChildItem Cert:\LocalMachine\My\$thumbprint
Connect-SPOService -Url https://contoso-admin.sharepoint.com -ClientId 00000000-0000-0000-0000-000000000000 -TenantId 11111111-1111-1111-1111-111111111111 -Certificate $cert

Managed identity, system-assigned or user-assigned:

Connect-SPOService -Url https://contoso-admin.sharepoint.com -ManagedIdentity
Connect-SPOService -Url https://contoso-admin.sharepoint.com -ManagedIdentity -ManagedIdentityType UserAssigned -ManagedIdentityClientId 00000000-0000-0000-0000-000000000000

Connect to a sovereign or regional cloud

-Region sets the authentication region. Valid values are Default, ITAR, Delos, France, Germany and China, and the default is Default. ITAR applies only to GCC High and DoD tenants, and Delos only to German sovereign cloud tenants.

Connect-SPOService -Url https://contoso-admin.sharepoint.com -Region ITAR

Connect-SPOService parameters

Parameter	What it does
-Url	The URL of the SharePoint admin center. Required.
-Credential	The admin's credentials. If you leave it out, you are prompted.
-ModernAuth	Turns on modern authentication. Use with -AuthenticationUrl.
-AuthenticationUrl	The Microsoft Entra cross-tenant authentication service URL, for a non-default endpoint.
-UseSystemBrowser	Signs in through MSAL and the system browser.
-Region	The authentication region: Default, ITAR, Delos, France, Germany or China.
-ClientId, -TenantId	The app and tenant for certificate sign-in. Both are required in that mode.
-Certificate, -CertificatePath, -CertificatePassword, -CertificateThumbprint	The certificate to authenticate with, as an object, a .pfx path with optional password, or a thumbprint.
-ManagedIdentity, -ManagedIdentityType, -ManagedIdentityClientId	Sign in with a system-assigned or user-assigned managed identity.
-ClientTag	Adds a tag to the CSOM HTTP traffic, to help identify the calling script.

Fixing "Connect-SPOService is not recognized as the name of a cmdlet"

PowerShell shows this error when the module that defines Connect-SPOService is not available in the session you are using. Work through these checks:

1. Is the module installed? Run Get-Module -Name Microsoft.Online.SharePoint.PowerShell -ListAvailable | Select Name,Version. If nothing returns, install it with Install-Module as shown above.
2. Are you in PowerShell 7? Import the module with Import-Module Microsoft.Online.SharePoint.PowerShell -UseWindowsPowerShell, or run the command from Windows PowerShell or the SharePoint Online Management Shell.
3. Is the SharePoint Client Components SDK installed on the same computer? Microsoft documents a known issue where the module fails to load if both are installed. Uninstall the SDK.
4. Is the module out of date? Run Update-Module -Name Microsoft.Online.SharePoint.PowerShell in an administrator window.

What to run after you connect

Once connected, the same session can run any SharePoint Online cmdlet. Common next steps on this site:

• Check the size of SharePoint storage with Get-SPOSite.
• Lock or unlock a site with Set-SPOSite -LockState.
• Find OneDrives over quota and raise site limits.
• Change SharePoint versioning for libraries.

To see where storage is going before you script anything, the free SharePoint Storage Explorer shows storage by site, library and file.

Frequently asked questions

What is the SharePoint Online admin URL for Connect-SPOService?

It is your tenant name followed by -admin.sharepoint.com, for example https://contoso-admin.sharepoint.com. The tenant name is the first part of any of your SharePoint addresses.

Which role do I need?

SharePoint Administrator or SharePoint Embedded Administrator.

Does Connect-SPOService work with MFA?

Yes. Run it without -Credential and complete the sign-in and verification in the dialog that opens.

Can I use Connect-SPOService in PowerShell 7?

Yes, after you import the module with Import-Module Microsoft.Online.SharePoint.PowerShell -UseWindowsPowerShell.

Can I run it unattended in a script?

Yes. Authenticate as an app with a certificate (-ClientId, -TenantId and a certificate), or with a managed identity.

Can I connect to two tenants at once?

Not in one session. The cmdlet supports one connection per Windows PowerShell session and per geo, and running it again replaces the existing connection.

What does -ModernAuth do?

It turns on modern authentication for the connection and must be used with -AuthenticationUrl. Microsoft suggests it when you cannot connect or get "Could not connect to SharePoint Online".

Related reading

• How to use SharePoint PowerShell - install, commands and examples.
• SharePoint Online PowerShell - an overview of the tools and modules.
• SharePoint admin center - the role, the URL and the tenant admin address.
• SharePoint permission levels - site roles versus admin roles.
• SharePoint Online limits - the numbers behind sites, libraries and storage.