Start Free Trial   Support

SharePoint Advanced Settings

Advanced Settings

Establishing a Connection

Connecting to SharePoint

Set the URL to a Site Collection to work with all Lists and Documents in all nested Subsites. Set the URL to a specific Site to work with Lists and Documents in that Site only.

URL Example URL
Site https://teams.contoso.com/teamA or https://teamA.contoso.com
Site Collection https://teams.contoso.com

In addition to providing the URL, use one of the following sets of connection properties to authenticate to SharePoint. The default values make it easy to connect in most environments, as shown below.

Authenticating to SharePoint Online

Set SharePointEdition to "SharePoint Online" and set the User and Password to the credentials you use to log onto SharePoint; for example, the credentials to your Microsoft Online Services account.

The following SSO (single sign-on) identity providers are also supported: Azure Active Directory, OneLogin, and OKTA.

  • SSO

    If you have enabled SSO in SharePoint Online, set UseSSO to true in addition to your User and Password.

    If the user account domain is different from the domain configured with the identity provider, set SSODomain to the domain configured with the identity provider. This property may be required for AD FS, OneLogin, and OKTA.

Authenticating to SharePoint On Premises

Set SharePointEdition to "SharePoint OnPremise" to use the following authentication types.

  • Windows (NTLM)

    This is the most common authentication type. As such, the provider is preconfigured to use NTLM as the default; simply set the Windows User and Password to connect.

  • Kerberos and Kerberos Delegation

    To authenticate with Kerberos, set AuthScheme to NEGOTIATE. If needed, provide the User and Password. To use Kerberos Delegation, set AuthScheme to KERBEROSDELEGATION.

    KerberosKDC, KerberosSPN, and KerberosRealm enable control over the components of Kerberos authentication.

  • Forms

    This allows authentication through a custom authentication method, instead of Active Directory. To use this authentication type, set AuthScheme to FORMS and set the User and Password.

Custom Credentials

Desktop Authentication with your OAuth App

Follow the steps below to authenticate with the credentials for a custom OAuth app. 

Get an OAuth Access Token

After setting the following, you are ready to connect:

  • OAuthClientId: Set this to the Client Id in your app settings.
  • OAuthClientSecret: Set this to the Client Secret in your app settings.
  • CallbackURL: Set this to the Redirect URL in your app settings.
  • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken. .
When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:
  1. Extracts the access token from the callback URL and authenticates requests.
  2. Obtains a new access token when the old one expires.
  3. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Web Authentication with your OAuth App

When connecting via a Web application, you need to register a custom OAuth app with SharePoint. You can then use the provider to get and manage the OAuth token values.

Get an OAuth Access Token

Set the following connection properties to obtain the OAuthAccessToken:

  • OAuthClientId: Set this to the Client Id in your app settings.
  • OAuthClientSecret: Set this to the Client Secret in your app settings.

You can then call stored procedures to complete the OAuth exchange:

  1. Call the GetOAuthAuthorizationURL stored procedure. Set the AuthMode input to WEB and set the CallbackURL input to the Redirect URI you specified in your app settings. If necessary, set the Permissions parameter to request custom permissions.

    The stored procedure returns the URL to the OAuth endpoint.

  2. Open the URL, log in, and authorize the application. You are redirected back to the callback URL.
  3. Call the GetOAuthAccessToken stored procedure. Set the AuthMode input to WEB. Set the Verifier input to the "code" parameter in the query string of the callback URL. If necessary, set the Permissions parameter to request custom permissions.

To connect to data, set the OAuthAccessToken connection property to the access token returned by the stored procedure. When the access token expires after ExpiresIn seconds, call GetOAuthAccessToken again to obtain a new access token.

Using Kerberos

This section shows how to use the provider to authenticate to SharePoint using Kerberos.

Authenticating with Kerberos

To authenticate to SharePoint using Kerberos, set the following properties:

  • AuthScheme: Set this to NEGOTIATE
  • KerberosKDC: Set this to the host name or IP Address of your Kerberos KDC machine.
  • KerberosSPN: Set this to the service and host of the SharePoint Kerberos Principal. This will be the value prior to the '@' symbol (for instance, MyService/MyHost) of the principal value (for instance, MyService/MyHost@EXAMPLE.COM).

Retrieve the Kerberos Ticket

You can use one of the following options to retrieve the required Kerberos ticket.

MIT Kerberos Credential Cache File

This option enables you to use the MIT Kerberos Ticket Manager or kinit command to get tickets. Note that you won't need to set the User or Password connection properties with this option.

  1. Ensure that you have an environment variable created called KRB5CCNAME.
  2. Set the KRB5CCNAME environment variable to a path pointing to your credential cache file (for instance, C:\krb_cache\krb5cc_0 or /tmp/krb5cc_0). This file will be created when generating your ticket with MIT Kerberos Ticket Manager.
  3. To obtain a ticket, open the MIT Kerberos Ticket Manager application, click Get Ticket, enter your principal name and password, then click OK. If successful, ticket information will appear in Kerberos Ticket Manager and will now be stored in the credential cache file.
  4. Now that the credential cache file has been created, the provider will use the cache file to obtain the kerberos ticket to connect to SharePoint.

 As an alternative to setting the KRB5CCNAME environment variable, you can directly set the file path using the KerberosTicketCache property. When set, the provider will use the specified cache file to obtain the kerberos ticket to connect to SharePoint.

Keytab File

If the KRB5CCNAME environment variable has not been set, you can retrieve a Kerberos ticket using a Keytab File. To do this, set the User property to the desired username and set the KerberosKeytabFile property to a file path pointing to the keytab file associated with the user.

User and Password

If both the KRB5CCNAME environment variable and the KerberosKeytabFile property have not been set, you can retrieve a ticket using a User and Password combination. To do this, set the User and Password properties to the user/password combo that you use to authenticate with SharePoint.

Cross-Realm Authentication

More complex Kerberos environments may require cross-realm authentication where multiple realms and KDC servers are used (e.g. where one realm/KDC is used for user authentication and another realm/KDC used for obtaining the service ticket).

In such an environment, the KerberosRealm and KerberosKDC properties can be set to the values required for user authentication. The KerberosServiceRealm and KerberosServiceKDC properties can be set to the values required to obtain the service ticket.

Fine Tuning the SharePoint Connection

To make it easier to access data in advanced integrations, use the following connection properties to control column name identifiers and other aspects of data access:

  • UseDisplayNames: Set this to true to return column names that match field names in the underlying API. By default, the provider uses column names that match the field names defined in SharePoint.
  • UseSimpleNames: Set this to true to perform substitutions on special characters in column names that SharePoint allows but that many databases typically do not.
  • ShowPredefinedColumns: Set this to false to exclude fields derived from fields in the list; for example, Author and CreatedAt. This setting excludes the predefined fields from being returned in SELECT * statements and schema discovery.
  • ShowHiddenColumns: When true, columns marked as hidden in SharePoint will be displayed by the provider.

Customizing the SSL Configuration

By default, the provider attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store. To specify another certificate, see the SSLServerCert property for the available formats to do so.

Connecting Through a Firewall or Proxy

To connect through the Windows system proxy, set only the SharePoint authentication properties and the URL. To connect to other proxies, set ProxyAutoDetect to false and in addition set the following.

To authenticate to an HTTP proxy, set ProxyAuthScheme, ProxyUser, and ProxyPassword, in addition to ProxyServer and ProxyPort.

To connect to other proxies, set FirewallType, FirewallServer, and FirewallPort. To tunnel the connection, set FirewallType to TUNNEL. To authenticate to a SOCKS proxy, set FirewallType to SOCKS5. Additionally, specify FirewallUser and FirewallPassword.

Troubleshooting the Connection

To show provider activity from query execution to HTTP calls, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.

  • Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
  • Queries time out: A server that takes too long to respond will exceed the provider's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.

  • The certificate presented by the server cannot be validated: This error indicates that the provider cannot validate the server's certificate through the chain of trust. (If you are using a self-signed certificate, there is only one certificate in the chain).

    To resolve this error, you must verify yourself that the certificate can be trusted and specify to the provider that you trust the certificate. One way you can specify that you trust a certificate is to add the certificate to the trusted system store; another is to set SSLServerCert.