# Authentication

Authentication configuration determines how the provisioning service connects to SharePoint. The method used depends on which properties are configured in SharepointCfg, selected in the priority order below.

# Authentication methods

Priority	Method	Required properties
1	App-only with certificate	`SharepointClientID` + `SharepointCertificatePath`
2	App-only with client secret	`SharepointClientID` (no certificate)
3	Username/password	`SharepointUsername` + `SharepointPassword`
4	Interactive / current user	(no credentials — fallback only)

# App-only authentication

App-only authentication uses an Azure AD app registration and runs unattended without a user account. It is the recommended method for production environments.

# App-only with client secret

Supported on: SharePoint Online, SharePoint 2016

Configure SharepointClientID and SharepointClientAppKey with the app's client secret. No certificate is required.

# App-only with certificate

Supported on: SharePoint Online only

Configure SharepointClientID, SharepointCertificatePath, and SharepointClientAppKey (as the certificate password). Certificate-based authentication is more secure than a client secret and is preferred for SharePoint Online deployments.

Set SharepointCertificatePath to either:

A file path to a .pfx file: C:\certs\myapp.pfx
The thumbprint of a certificate installed in the Windows certificate store

# Registering the app

SharepointClientID/SharepointClientAppKey are obtained differently depending on the target:

SharePoint Online — Azure Portal (Entra ID) app registration:

In the Azure Portal (opens new window), go to Entra ID → App registrations → New registration. Give it a name and register it.
Note the Application (client) ID — this is SharepointClientID.
Under Certificates & secrets, create either:
- A client secret — copy its value immediately (it is only shown once); this is SharepointClientAppKey.
- A certificate — upload the .pfx public key and use the .pfx file (or its Windows certificate-store thumbprint) as SharepointCertificatePath, with the certificate's password as SharepointClientAppKey.
Under API permissions, add the application permissions required for the features in use, then click Grant admin consent.

SharePoint 2016 on-premises — legacy ACS app registration: on-premises SharePoint does not use Entra ID app registrations. Instead, register the app directly against SharePoint's classic add-in model:

Browse to https://<site>/_layouts/15/appregnew.aspx on the target SharePoint site. Generate (or supply) a Client Id and Client Secret, fill in a display name and any domain/redirect URI, then click Create. The generated Client Id/Client Secret are SharepointClientID/SharepointClientAppKey.
Browse to https://<site>/_layouts/15/appinv.aspx. Look up the app by the Client Id from step 1, then supply an app permission request XML specifying the required scope and right, for example:
```
<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
</AppPermissionRequests>
```
Click Create, then approve the trust prompt. This app-only certificate-free flow only supports the client-secret method above — certificate-based app-only authentication is SharePoint Online only.

# Username/password authentication

Username/password authentication uses a dedicated service account. Simpler to configure but requires the account to have appropriate SharePoint permissions and be licensed for SharePoint access.

# SharePoint Online

Required: SharepointUsername, SharepointPassword

Uses SharePoint Online's tenant authentication endpoint.

# On-premises with ADFS

Required: SharepointUsername, SharepointPassword, SharepointADFSUrl, SharepointADFSRealm

For domain accounts, use DOMAIN\username format for SharepointUsername. The domain prefix is parsed automatically.

# On-premises without ADFS

Required: SharepointUsername, SharepointPassword

Uses Windows network credentials. Optionally prefix the username with the domain: DOMAIN\username.

# Interactive / current user (fallback)

When no credentials are configured:

SharePoint Online — opens a browser login prompt (supports MFA). Not suitable for unattended service use.
SharePoint 2016 / on-premises — uses the Windows account the service is running under.

# Property reference

# SharepointUrl

Type: string | Required: Yes | Configurator: "Url"

The URL of the SharePoint site where the matters list and document libraries are located. Must start with https://. A trailing slash is added automatically if omitted.

# SharepointTenantUrl

Type: string | Required: No | Configurator: "SharepointTenantUrl"

Override the tenant admin URL. When not set, the admin URL is derived from SharepointUrl by inserting -admin before the first . (e.g., https://contoso.sharepoint.com/sites/dms → https://contoso-admin.sharepoint.com).

# SharepointOnline

Type: bool | Required: No | Configurator: "Sharepoint Online"

Override automatic SharePoint Online detection. When not set, the service detects SharePoint Online by checking whether the URL contains .sharepoint.. Set to true for private Office 365 environments that do not use the standard .sharepoint.com domain.

# SharepointClientID

Type: string | Required: Conditional | Configurator: "Application Client ID"

Azure AD app registration client ID. When set, app-only authentication is used and takes precedence over username/password.

# SharepointClientAppKey

Type: string | Required: Conditional | Configurator: "Application Secret value/Certificate Password"

For app-only with client secret: the client secret value from the app registration.

For app-only with certificate: the password protecting the .pfx file. Leave empty if the certificate has no password.

Stored encrypted.

# SharepointCertificatePath

Type: string | Required: Conditional | Configurator: "Certificate Path (pfx)/Thumbprint"

Path to a .pfx certificate file, or the thumbprint of a certificate installed in the Windows certificate store. When set alongside SharepointClientID, certificate-based app-only authentication is used. Only effective on SharePoint Online.

# SharepointUsername

Type: string | Required: Conditional | Configurator: "Username"

Username for delegated (username/password) authentication. Use DOMAIN\username format for on-premises domain accounts.

# SharepointPassword

Type: string | Required: Conditional | Configurator: "Password"

Password for SharepointUsername. Stored encrypted.

# SharepointADFSUrl

Type: string | Required: Conditional | Configurator: "ADFS Url"

ADFS WS-Trust endpoint for on-premises ADFS authentication. The https:// prefix is stripped automatically if included. Example: adfs.contoso.local/adfs/services/trust/13/usernamemixed.

# SharepointADFSRealm

Type: string | Required: Conditional | Configurator: "ADFS Realm"

ADFS realm identifier. Required when SharepointADFSUrl is configured. Example: urn:sharepoint:contoso.

# SharepointForceNTLM

Type: bool | Required: No | Default: false | Configurator: "Force NTLM"

Force NTLM authentication for on-premises connections.

# SharepointEnvironment

Type: enum | Required: No | Default: Production | Configurator: "Environment" | Applies to: SharePoint Online only

Azure cloud environment for app-only authentication. Valid values:

Production — public Microsoft 365 cloud (default)
China — Azure China Cloud
USGovernment — Azure US Government Cloud

Ignored on SharePoint 2016 and on-premises.

# Token refresh

The connection to SharePoint is automatically renewed every 4 hours to prevent authentication token expiry during long-running provisioning operations.

SharepointCfg — root configuration object that contains these properties

← Global Settings Configuration Dynamic name values →