You need to connect only once in the Office 365 CLI

When working with the Office 365 CLI, you need to connect to SharePoint only once.

What is Office 365 CLI

Office 365 CLI is a cross-platform CLI that allows you to manage various configuration settings of Office 365 and SharePoint Framework projects no matter which operating system or shell you use. For more information about the Office 365 CLI, see its documentation at aka.ms/o365cli.

Connecting to Office 365 in the Office 365 CLI

Before you can use the Office 365 CLI to manage your tenant, you have to connect to Office 365. Office 365 exposes many services like Azure AD, Microsoft Graph or SharePoint. Each of these services requires specific authentication and to follow this model, the different commands in the Office 365 CLI are organized by services they interact with. For example, all commands that interact with SharePoint begin with spo, eg. spo site list, and commands that use the Microsoft Graph, start with graph, eg. graph o365group list.

Before you can use any of these commands, you have to authenticate with the corresponding service. To connect to the Microsoft Graph you would execute the graph connect command. To connect to SharePoint, you would use the spo connect command, specifying the URL of your site. And this is where things often go wrong.

SharePoint vs. everything else in Office 365

One of the things that separates SharePoint from other services in Office 365 is the fact, that each SharePoint tenant is located on a unique URL. When you want to connect to the Microsoft Graph, you use https://graph.microsoft.com. This URL is the same for everybody. To connect to the Azure AD Graph, you would use https://graph.microsoft.net, again the same URL for each Office 365 tenant. But to connect to SharePoint, you need to specify the unique URL of your tenant. What complicates things even more, is the fact that each SharePoint tenant has three domains: https://contoso-admin.sharepoint.com - which points to the tenant admin site, https://contoso.sharepoint.com - which points to regular sites and https://contoso-my.sharepoint.com - which points to OneDrive for Business sites. And each of these domains requires separate authentication as well. But there is even more.

SharePoint context

If you've worked with the SharePoint Client-Side Object Model (CSOM) or PnP PowerShell, you're likely familiar with the concept of context. Before you perform any action, you establish a context by connecting to the site on which you want to operate. If you want to operate on a different site, you connect to that site, and so on. Exactly this behavior, combined with our poor choice of name for the command to authenticate the Office 365 CLI with Office 365, leads to confusion and overhead.

Connect == log in

Office 365 CLI doesn't have the notion of a context. If the command operates on site collection- or site-specific resources, it requires you to specify the URL of the site (collection). Because of that, when using the Office 365 CLI to manage SharePoint, you only need to connect once to authenticate with SharePoint in your tenant. After that, you can work on any site in your tenant, without having to connect to it first.

Tip: Some commands in the Office 365 CLI require connection to the tenant admin site. Because of that, if possible, you should always connect to the tenant admin site. When operating on different sites, Office 365 CLI will automatically obtain access token to the specified site URL.

Because Microsoft Graph or Azure AD are exposed under a single domain, there is no confusion with what connect means in that context. But SharePoint works differently, and using connect for authentication is confusing.

So to help clarify things, we decided to rename the connect commands, to login, which hopefully will be a clearer indication, that you only need to use it once. To authenticate with SharePoint, you will now call spo login https://contoso-admin.sharepoint.com. To communicate with the Microsoft Graph, you will login using graph login, and so forth.

The login and logout verbs replacing respectively connect and disconnect follow the naming convention of the Azure CLI.

The new login and logout commands work identically as their connect and disconnect predecessors. To avoid breaking changes, you can still use the connect and disconnect but we the CLI will display a deprecation message suggesting using login/logout instead.

This change is reflected in the latest beta of the Office 365 CLI which you can install from npm using npm install -g @pnp/office365-cli@next. It will be released in the next version of the Office 365 CLI v1.7.0 end of September/begin of October '18.

Big thanks to Andrew Connell for bringing this issue up and his thoughts on suggestions for improvement. If you like this change or have some concerns, please let us know on GitHub.

Hopefully this change in the Office 365 CLI clarifies things a little and will help you use it more efficiently.

Comments

comments powered by Disqus