30-second answer
connect opens a read-only session and tells you what was established. It
collects nothing and writes nothing.
m365-governance connect [-h] --client-id CLIENT_ID
[--site-url SITE_URL] [--tenant-url TENANT_URL]
[--device-login] [--format {text,json}]It is the other half of doctor.
That one says whether the installation is sound. This one says whether the
application registration in front of you can reach the tenant in front of you,
which used to be discovered several minutes into a collection, from a failure
that looked like a tenant problem rather than a consent problem.
What it reports
Two questions, kept apart on the page because they are separate claims.
ESTABLISHED after 6.2s
Address resolution
contoso.sharepoint.com
owned by fcea8c52-d8bb-4836-8ef1-a3ab74265d08
Public discovery, and no session was involved. Authoritative for
the address: two hosts that resolve here to one directory ARE one
organisation. It says nothing about who signed in.
Authenticated session
identity delegated
observed not established
client id 11111111-2222-3333-4444-555555555555
connection TenantAdminWhich directory owns an address is answerable by anybody, from public OpenID discovery, without a token. Which directory a session operated in is answerable only by the session, and nothing reads it yet.
A GUID the whole world can obtain without ever reaching a tenant is not
evidence that a collection looked at that tenant. That is why they are two
fields and not one, and why observed says not established under a sign-in
that worked.
How an attempt ends
| State | Means | Exit |
|---|---|---|
established | A session opened, and it says who it belongs to | 0 |
refused | The tenant answered and would not have us: consent, or the wrong tenant | 1 |
unreachable | Nothing answered, or the local environment cannot try | 1 |
cancelled | You stopped it | 1 |
A tenant that refused is not a tenant that never answered. Collapsing them sends you to check your network when the answer was consent, and to check consent when nothing was listening.
The address resolves before the sign-in, so it is reported whatever the sign-in does. A tenant that refuses you still has an address, and knowing which directory you were actually pointed at is most of a consent diagnosis.
Options
--client-id is required, and the help text says why: PnP.PowerShell has
shipped no application of its own since 2.12.0.
--tenant-url or --site-url. One of them is needed, and connect
says so rather than failing obscurely. --tenant-url is the admin centre,
https://<tenant>-admin.sharepoint.com.
--device-login authenticates with a device code, for hosts with no
browser. The code appears in the output as it is printed, because it expires.
--format json publishes
connection/1.0.0,
a versioned contract with a generated model in the bundle. Validate it and
deserialise it, in that order, exactly as you would an assessment.
It was declared deliberately unversioned until 1.0.0b6, on the reasoning that
a session ends when the process does and so has nothing to persist. That
answers the wrong question: persistence is not the test, dependence is. A
consumer parses this to decide whether a collection may start, and a shape
somebody depends on is a contract whether or not it is called one.
The --help text shipped in 1.0.0b6 still says otherwise. That line is
stale, and the schema in the bundle is what holds.
Exit codes
0 established. 1 the tenant was not reached, whichever of the three ways.
2 refused before trying: a missing argument, or a preflight problem with the
local environment.
Where to go deeper
doctor: the other half, about this machine rather than about a tenant.- Authentication: the app registration, the permissions and why they are what they are.
collect: what to run once a session opens.