Connect-PnPOnline

Connect to a SharePoint site

Syntax

Connect-PnPOnline
       -Url <String>
                        [-ReturnConnection [<SwitchParameter>]]
                        [-Credentials <CredentialPipeBind>]
                        [-CurrentCredentials [<SwitchParameter>]]
                        [-UseAdfs [<SwitchParameter>]]
                        [-LoginProviderName <String>]
                        [-MinimalHealthScore <Int>]
                        [-RetryCount <Int>]
                        [-RetryWait <Int>]
                        [-RequestTimeout <Int>]
                        [-AuthenticationMode <ClientAuthenticationMode>]
                        [-CreateDrive [<SwitchParameter>]]
                        [-DriveName <String>]
                        [-Scopes <String[]>]
                        [-TenantAdminUrl <String>]
                        [-SkipTenantAdminCheck [<SwitchParameter>]]
                        [-IgnoreSslErrors [<SwitchParameter>]]
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -AccessToken <String>
                        [-ReturnConnection [<SwitchParameter>]]
                        [-Url <String>]
                        [-MinimalHealthScore <Int>]
                        [-RetryCount <Int>]
                        [-RetryWait <Int>]
                        [-RequestTimeout <Int>]
                        [-CreateDrive [<SwitchParameter>]]
                        [-DriveName <String>]
                        [-SkipTenantAdminCheck [<SwitchParameter>]]
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -Graph [<SwitchParameter>]
                        [-LaunchBrowser [<SwitchParameter>]]
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -Scopes <String[]>
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -Url <String>
                        -UseWebLogin [<SwitchParameter>]
                        [-ReturnConnection [<SwitchParameter>]]
                        [-MinimalHealthScore <Int>]
                        [-RetryCount <Int>]
                        [-RetryWait <Int>]
                        [-RequestTimeout <Int>]
                        [-CreateDrive [<SwitchParameter>]]
                        [-DriveName <String>]
                        [-Scopes <String[]>]
                        [-TenantAdminUrl <String>]
                        [-SkipTenantAdminCheck [<SwitchParameter>]]
                        [-IgnoreSslErrors [<SwitchParameter>]]
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -Url <String>
                        -SPOManagementShell [<SwitchParameter>]
                        [-ReturnConnection [<SwitchParameter>]]
                        [-MinimalHealthScore <Int>]
                        [-RetryCount <Int>]
                        [-RetryWait <Int>]
                        [-RequestTimeout <Int>]
                        [-CreateDrive [<SwitchParameter>]]
                        [-DriveName <String>]
                        [-ClearTokenCache [<SwitchParameter>]]
                        [-Scopes <String[]>]
                        [-TenantAdminUrl <String>]
                        [-SkipTenantAdminCheck [<SwitchParameter>]]
                        [-IgnoreSslErrors [<SwitchParameter>]]
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -Url <String>
                        -PnPO365ManagementShell [<SwitchParameter>]
                        [-ReturnConnection [<SwitchParameter>]]
                        [-LaunchBrowser [<SwitchParameter>]]
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -Url <String>
                        -AppId <String>
                        -AppSecret <String>
                        [-ReturnConnection [<SwitchParameter>]]
                        [-MinimalHealthScore <Int>]
                        [-RetryCount <Int>]
                        [-RetryWait <Int>]
                        [-RequestTimeout <Int>]
                        [-Realm <String>]
                        [-CreateDrive [<SwitchParameter>]]
                        [-DriveName <String>]
                        [-Scopes <String[]>]
                        [-TenantAdminUrl <String>]
                        [-SkipTenantAdminCheck [<SwitchParameter>]]
                        [-IgnoreSslErrors [<SwitchParameter>]]
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -Url <String>
                        -ClientId <String>
                        -RedirectUri <String>
                        [-ReturnConnection [<SwitchParameter>]]
                        [-MinimalHealthScore <Int>]
                        [-RetryCount <Int>]
                        [-RetryWait <Int>]
                        [-RequestTimeout <Int>]
                        [-CreateDrive [<SwitchParameter>]]
                        [-DriveName <String>]
                        [-ClearTokenCache [<SwitchParameter>]]
                        [-AzureEnvironment <AzureEnvironment>]
                        [-Scopes <String[]>]
                        [-TenantAdminUrl <String>]
                        [-SkipTenantAdminCheck [<SwitchParameter>]]
                        [-IgnoreSslErrors [<SwitchParameter>]]
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -AppId <String>
                        -AppSecret <String>
                        -AADDomain <String>
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -Url <String>
                        -ClientId <String>
                        -HighTrustCertificate <X509Certificate2>
                        [-ReturnConnection [<SwitchParameter>]]
                        [-MinimalHealthScore <Int>]
                        [-RetryCount <Int>]
                        [-RetryWait <Int>]
                        [-RequestTimeout <Int>]
                        [-CreateDrive [<SwitchParameter>]]
                        [-DriveName <String>]
                        [-TenantAdminUrl <String>]
                        [-SkipTenantAdminCheck [<SwitchParameter>]]
                        [-IgnoreSslErrors [<SwitchParameter>]]
                        [-HighTrustCertificateIssuerId <String>]
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -Url <String>
                        -ClientId <String>
                        -Tenant <String>
                        -CertificatePath <String>
                        [-ReturnConnection [<SwitchParameter>]]
                        [-MinimalHealthScore <Int>]
                        [-RetryCount <Int>]
                        [-RetryWait <Int>]
                        [-RequestTimeout <Int>]
                        [-CreateDrive [<SwitchParameter>]]
                        [-DriveName <String>]
                        [-CertificatePassword <SecureString>]
                        [-AzureEnvironment <AzureEnvironment>]
                        [-Scopes <String[]>]
                        [-TenantAdminUrl <String>]
                        [-SkipTenantAdminCheck [<SwitchParameter>]]
                        [-IgnoreSslErrors [<SwitchParameter>]]
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -Url <String>
                        -ClientId <String>
                        -HighTrustCertificatePath <String>
                        -HighTrustCertificatePassword <String>
                        [-ReturnConnection [<SwitchParameter>]]
                        [-MinimalHealthScore <Int>]
                        [-RetryCount <Int>]
                        [-RetryWait <Int>]
                        [-RequestTimeout <Int>]
                        [-CreateDrive [<SwitchParameter>]]
                        [-DriveName <String>]
                        [-TenantAdminUrl <String>]
                        [-SkipTenantAdminCheck [<SwitchParameter>]]
                        [-IgnoreSslErrors [<SwitchParameter>]]
                        [-HighTrustCertificateIssuerId <String>]
                        [-NoTelemetry [<SwitchParameter>]]
Connect-PnPOnline
       -Url <String>
                        -ClientId <String>
                        -Tenant <String>
                        -PEMCertificate <String>
                        -PEMPrivateKey <String>
                        [-ReturnConnection [<SwitchParameter>]]
                        [-MinimalHealthScore <Int>]
                        [-RetryCount <Int>]
                        [-RetryWait <Int>]
                        [-RequestTimeout <Int>]
                        [-CreateDrive [<SwitchParameter>]]
                        [-DriveName <String>]
                        [-CertificatePassword <SecureString>]
                        [-AzureEnvironment <AzureEnvironment>]
                        [-TenantAdminUrl <String>]
                        [-SkipTenantAdminCheck [<SwitchParameter>]]
                        [-IgnoreSslErrors [<SwitchParameter>]]
                        [-NoTelemetry [<SwitchParameter>]]

Description

If no credentials have been specified, and the CurrentCredentials parameter has not been specified, you will be prompted for credentials.

Examples

------------------EXAMPLE 1------------------

Connect-PnPOnline -Url https://contoso.sharepoint.com

This will prompt for username and password and creates a context for the other PowerShell commands to use. When a generic credential is added to the Windows Credential Manager with https://contoso.sharepoint.com, PowerShell will not prompt for username and password.

------------------EXAMPLE 2------------------

Connect-PnPOnline -Url https://contoso.sharepoint.com -Credentials (Get-Credential)

This will prompt for username and password and creates a context for the other PowerShell commands to use.

------------------EXAMPLE 3------------------

Connect-PnPOnline -Url http://yourlocalserver -CurrentCredentials

This will use the current user credentials and connects to the server specified by the Url parameter.

------------------EXAMPLE 4------------------

Connect-PnPOnline -Url http://yourlocalserver -Credentials 'O365Creds'

This will use credentials from the Windows Credential Manager, as defined by the label 'O365Creds'.

------------------EXAMPLE 5------------------

Connect-PnPOnline -Url http://yourlocalserver -Credentials (Get-Credential) -UseAdfs

This will prompt for username and password and creates a context using ADFS to authenticate.

------------------EXAMPLE 6------------------

Connect-PnPOnline -Url https://yourserver -Credentials (Get-Credential) -CreateDrive
cd SPO:\\
dir

This will prompt you for credentials and creates a context for the other PowerShell commands to use. It will also create a SPO:\ drive you can use to navigate around the site

------------------EXAMPLE 7------------------

Connect-PnPOnline -Url https://yourserver -Credentials (Get-Credential) -AuthenticationMode FormsAuthentication

This will prompt you for credentials and creates a context for the other PowerShell commands to use. It assumes your server is configured for Forms Based Authentication (FBA)

------------------EXAMPLE 8------------------

Connect-PnPOnline -Url https://contoso.sharepoint.de -AppId 344b8aab-389c-4e4a-8fa1-4c1ae2c0a60d -AppSecret a3f3faf33f3awf3a3sfs3f3ss3f4f4a3fawfas3ffsrrffssfd -AzureEnvironment Germany

This will authenticate you to the German Azure environment using the German Azure endpoints for authentication

------------------EXAMPLE 9------------------

Connect-PnPOnline -Url https://contoso.sharepoint.com -SPOManagementShell

This will authenticate you using the SharePoint Online Management Shell application

------------------EXAMPLE 10------------------

Connect-PnPOnline -Url https://contoso.sharepoint.com -PnPO365ManagementShell

This will authenticate you using the PnP O365 Management Shell Multi-Tenant application. A browser window will have to be opened where you have to enter a code that is shown in your PowerShell window.

------------------EXAMPLE 11------------------

Connect-PnPOnline -Url https://contoso.sharepoint.com -PnPO365ManagementShell -LaunchBrowser

This will authenticate you using the PnP O365 Management Shell Multi-Tenant application. A browser window will automatically open and the code you need to enter will be automatically copied to your clipboard.

------------------EXAMPLE 12------------------

Connect-PnPOnline -Url https://contoso.sharepoint.com -AccessToken $myaccesstoken

This will authenticate you using the provided access token

------------------EXAMPLE 13------------------

Connect-PnPOnline -Scopes $arrayOfScopes

Connects to Azure AD and gets and OAuth 2.0 Access Token to consume the Microsoft Graph API including the declared permission scopes. The available permission scopes are defined at the following URL: https://graph.microsoft.io/en-us/docs/authorization/permission_scopes

------------------EXAMPLE 14------------------

Connect-PnPOnline -AppId '<id>' -AppSecret '<secret>' -AADDomain 'contoso.onmicrosoft.com'

Connects to the Microsoft Graph API using application permissions via an app's declared permission scopes. See https://github.com/SharePoint/PnP-PowerShell/tree/master/Samples/Graph.ConnectUsingAppPermissions for a sample on how to get started.

------------------EXAMPLE 15------------------

certutil.exe -csp 'Microsoft Enhanced RSA and AES Cryptographic Provider' -v -p 'password' -importpfx -user c:\HighTrust.pfx NoRoot
Connect-PnPOnline -Url https://yourserver -ClientId <id> -HighTrustCertificate (Get-Item Cert:\CurrentUser\My\<thumbprint>)

Connect to an on-premises SharePoint environment using a high trust certificate, stored in the Personal certificate store of the current user.

------------------EXAMPLE 16------------------

Connect-PnPOnline -Url https://contoso.sharepoint.com -ClientId '<id>' -Tenant 'contoso.onmicrosoft.com' -PEMCertificate <PEM string> -PEMPrivateKey <PEM string>

Connects to SharePoint using app-only tokens via an app's declared permission scopes. See https://github.com/SharePoint/PnP-PowerShell/tree/master/Samples/SharePoint.ConnectUsingAppPermissions for a sample on how to get started.

------------------EXAMPLE 17------------------

Connect-PnPOnline -Url https://yourserver -ClientId 763d5e60-b57e-426e-8e87-b7258f7f8188 -HighTrustCertificatePath c:\HighTrust.pfx -HighTrustCertificatePassword 'password' -HighTrustCertificateIssuerId 6b9534d8-c2c1-49d6-9f4b-cd415620bca8

Connect to an on-premises SharePoint environment using a high trust certificate stored in a .PFX file.

Required Parameters

-AADDomain

The AAD where the O365 app is registred. Eg.: contoso.com, or contoso.onmicrosoft.com.

Only applicable to: SharePoint Online

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-AccessToken

Connect with an existing Access Token

Only applicable to: SharePoint Online

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-AppId

The Application Client ID to use.

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-AppSecret

The Application Client Secret to use.

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-CertificatePath

Path to the certificate (*.pfx)

Only applicable to: SharePoint Online

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-ClientId

The Client ID of the Azure AD Application

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-Graph

Log in using the PnP O365 Management Shell application towards the Graph. You will be asked to consent to:

  • Read and write managed metadata
  • Have full control of all site collections
  • Read user profiles
  • Invite guest users to the organization
  • Read and write all groups
  • Read and write directory data
  • Access the directory as you
  • Read and write identity providers
  • Access the directory as you

Only applicable to: SharePoint Online

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-HighTrustCertificate

The certificate which has been registered in SharePoint as a Trusted Security Token issuer to use for the High Trust connection. Note that CNG key storage providers are not supported.

Only applicable to: SharePoint Server 2013, SharePoint Server 2016

Type:X509Certificate2
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-HighTrustCertificatePassword

The password of the private key certificate (.pfx) to use for the High Trust connection

Only applicable to: SharePoint Server 2013, SharePoint Server 2016

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-HighTrustCertificatePath

The path to the private key certificate (.pfx) to use for the High Trust connection

Only applicable to: SharePoint Server 2013, SharePoint Server 2016

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-PEMCertificate

PEM encoded certificate

Only applicable to: SharePoint Online

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-PEMPrivateKey

PEM encoded private key for the certificate

Only applicable to: SharePoint Online

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-PnPO365ManagementShell

Log in using the PnP O365 Management Shell application. You will be asked to consent to:

  • Read and write managed metadata
  • Have full control of all site collections
  • Read user profiles
  • Invite guest users to the organization
  • Read and write all groups
  • Read and write directory data
  • Access the directory as you
  • Read and write identity providers
  • Access the directory as you

Only applicable to: SharePoint Online

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-RedirectUri

The Redirect URI of the Azure AD Application

Only applicable to: SharePoint Online

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-SPOManagementShell

Log in using the SharePoint Online Management Shell application

Only applicable to: SharePoint Online

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-Tenant

The Azure AD Tenant name,e.g. mycompany.onmicrosoft.com

Only applicable to: SharePoint Online

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-Url

The Url of the site collection to connect to.

Type:String
Position:0
Accept pipeline input:True
Accept wildcard characters:False
-UseWebLogin

If you want to connect to SharePoint with browser based login. This is required when you have multi-factor authentication (MFA) enabled.

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False

Optional Parameters

-AuthenticationMode

Specify to use for instance use forms based authentication (FBA)

Type:ClientAuthenticationMode
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-AzureEnvironment

The Azure environment to use for authentication, the defaults to 'Production' which is the main Azure environment.

Only applicable to: SharePoint Online

Type:AzureEnvironment
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-CertificatePassword

Password to the certificate (*.pfx)

Only applicable to: SharePoint Online

Type:SecureString
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-ClearTokenCache

Clears the token cache.

Only applicable to: SharePoint Online

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-CreateDrive

If you want to create a PSDrive connected to the URL

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-Credentials

Credentials of the user to connect with. Either specify a PSCredential object or a string. In case of a string value a lookup will be done to the Windows Credential Manager for the correct credentials.

Type:CredentialPipeBind
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-CurrentCredentials

If you want to connect with the current user credentials

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-DriveName

Name of the PSDrive to create (default: SPO)

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-HighTrustCertificateIssuerId

The IssuerID under which the certificate has been registered in SharePoint as a Trusted Security Token issuer to use for the High Trust connection. Uses the ClientID if not specified.

Only applicable to: SharePoint Server 2013, SharePoint Server 2016

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-IgnoreSslErrors

Ignores any SSL errors. To be used i.e. when connecting to a SharePoint farm using self signed certificates or using a certificate authority not trusted by this machine.

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-LaunchBrowser

Launch a browser automatically and copy the code to enter to the clipboard

Only applicable to: SharePoint Online

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-LoginProviderName

The name of the ADFS trusted login provider

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-MinimalHealthScore

Specifies a minimal server healthscore before any requests are executed.

Type:Int
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-NoTelemetry

In order to help to make PnP PowerShell better, we can track anonymous telemetry. We track the version of the cmdlets you are using, which cmdlet you are executing and which version of SharePoint you are connecting to. Use Disable-PnPPowerShellTelemetry to turn this off in general or use the -NoTelemetry switch to turn it off for that session.

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-Realm

Authentication realm. If not specified will be resolved from the url specified.

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-RequestTimeout

The request timeout. Default is 180000

Type:Int
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-RetryCount

Defines how often a retry should be executed if the server healthscore is not sufficient. Default is 10 times.

Type:Int
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-RetryWait

Defines how many seconds to wait before each retry. Default is 1 second.

Type:Int
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-ReturnConnection

Returns the connection for use with the -Connection parameter on cmdlets.

Type:SwitchParameter
Position:Named
Accept pipeline input:True
Accept wildcard characters:False
-Scopes

The array of permission scopes for the Microsoft Graph API.

Only applicable to: SharePoint Online

Type:String[]
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-SkipTenantAdminCheck

Should we skip the check if this site is the Tenant admin site. Default is false

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-TenantAdminUrl

The url to the Tenant Admin site. If not specified, the cmdlets will assume to connect automatically to https://<tenantname>-admin.sharepoint.com where appropriate.

Type:String
Position:Named
Accept pipeline input:False
Accept wildcard characters:False
-UseAdfs

If you want to connect to your on-premises SharePoint farm using ADFS

Type:SwitchParameter
Position:Named
Accept pipeline input:False
Accept wildcard characters:False