SharePoint Online PowerShell module adds support for certificate-based authentication

In a welcome, albeit long-awaited, development, Microsoft has finally added support for certificate-based authentication (or CBA) for the SharePoint Online PowerShell module. The news was published as part of the MC1188595 message center post, which unfortunately is a bit light on the details. So let me fill in the gaps for you.

To clarify, we’re talking about support for non-interactive authentication via the so-called client credentials flow, against the good old SharePoint Online resource. That’s a mouthful, I know, so let’s expand a bit. Until now, the only way to connect via the SharePoint Online PowerShell module was to leverage any (admin) user account, with the corresponding authentication methods. With the advent on the Secure Future Initiative and the resulting “hardening” changes to the service, methods such as passing a username/password are becoming increasingly limited or outright blocked.

This in turn has effect on any automation scenarios. Microsoft has long supported non-interactive application-centric OAuth methods, such as the client credentials flow. For whatever reasons the SPO PowerShell module has been slow to adopt them. Granted, PnP and Graph-based alternatives are available, though they come with their own problems, with the former being open-source and therefore not officially supported, whereas the latter offers support for only a very limited set of operations at present.

With the above in mind, adding support for certificate-based authentication for the SPO PowerShell module is a major step, and one that ensures customers and partners alike will still be able to leverage the module and all the operations it supports within their solutions in a supported manner.

Without further ado, time to see this in action. First, we will need to address some of the prerequisites, starting with the SPO module itself – you need to be on a recent build in order to leverage the parameters needed to use certificate-based auth. The change release notes for the module are not published externally, and the message center post doesn’t specify which version is required either, so we will just assume you need the latest one. At the time of writing, this is 16.0.26712.12000.

So as the first step, make sure to update your SPO module version, or install the latest version as needed. An important note is due here – the module still does not support any of the “core” editions of PowerShell, so you cannot use it with PowerShell 7+. Instead, Windows PowerShell is required. For additional details on this, you can refer to the official documentation. And, as mentioned above already, keep in mind that the official documentation does not currently details the CBA method, but it will hopefully do so in a few days time.

Next, we need to take care of the authentication-related configuration. Since we’re going to use the client credentials flow, we need to have an application registration and configure the desired certificate under the Certificates & Secrets page. We’re following the exact same steps as when configuring CBA for any other application, so I’m not going to be adding screenshots and such here. Should you need them, this article covers the major steps of the process. The only difference is with regards to the permissions required. For our purposes we need the Sites.FullControl.All application permission from the SharePoint resource. NOT the Graph resource, even though it offers the exact same scope!

If you are adding the required permissions via the Manifest method, the value for the required resource is 00000003-0000-0ff1-ce00-000000000000, whereas the permission ID is 678536fe-1083-478a-9c59-b99265e6b0d3. Do not forget to grant admin consent, as this is an application permissions after all.

And with that we are ready to connect to SPO via certificate-based authentication. Much like the CBA implementation within the Exchange Online PowerShell module, we can either pass a certificate object directly, point to a .pfx file stored on the local device or pass the thumbnail value of a certificate stored in the current user’s Personal store. We will also need to provide the id of our application object, as well as the tenant id. Here are some examples:

#Connect to SPO via CBA (cert thumbprint)
Connect-SPOService -Url https://tenant-admin.sharepoint.com -TenantId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -ApplicationId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -CertificateThumbprint 01CBF50A70FABCDE714870E4D123457ABE90812C

#Connect to SPO via CBA (.pfx file)
Connect-SPOService -Url https://tenant-admin.sharepoint.com -TenantId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -ClientId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -CertificatePath .\Certificates\2025.pfx -CertificatePassword ("P@ss123#" | ConvertTo-SecureString -AsPlainText -Force)

When using the –CertificateThumbprint parameter make sure that the certificate is stored within the current user’s Personal store and access to the private key has been granted. Some additional notes and examples can be found over at the Connect-SPOService cmdlet’s documentation page. As a bonus tip, you can use -ApplicationId as an alias for the -ClientId parameter.

At this point you should be connected to your organization’s SPO service and be able to execute (most) PowerShell cmdlets. A note within the MC1188595 post mentions that there are some known issues with CBA support, without going into useful detail. Given we have 344 cmdlets available currently, I obviously haven’t bothered to test them all.

We expect most scenarios to work with App-Only authentication. However, there could be rare cases where an API needs an explicit user token for security reasons. In such cases, tenant admins should use interactive flows with admin/user credentials. Feel free to reach out to us if needed.

As more information becomes available, I will try to keep the article updated, at least until the official documentation is up.

In summary, the SharePoint Online PowerShell module finally adds support for certificate-based authentication. CBA works much like with any other Microsoft 365 related module, sans the specific requirements on the resource side. In terms of the actual authentication, you can pass the certificate itself, reference it by thumbprint or use a .pfx file. No support for passing a client secret has been added, nor for passing an access token for that matter. Still, this is a welcome addition that should help enable some automation scenarios.