Skip to content

SharePoint Online Certificate Connection on Linux

Jump to bottom
directorcia edited this page Oct 22, 2026 · 1 revision

Purpose

o365-connect-spo-cert-linux.ps1 is a Linux-specific entry point for generating a certificate and connecting to the SharePoint Online admin center with certificate-based application authentication. It adapts the common Linux PnP certificate workflow to SharePoint Online tenant administration.

The script delegates certificate generation, optional Entra app provisioning, and PnP.PowerShell connection work to o365-connect-pnp-cert-linux.ps1, which must be in the same directory. The wrapper supplies the SharePoint admin URL as the PnP connection URL and handles profile fields in either adminUrl or siteUrl form.

The resulting connection is a PnP.PowerShell connection in the current PowerShell process. Use PnP cmdlets such as Get-PnPTenantSite; this does not load the Windows-only SharePoint Online Management Shell and does not provide cmdlets such as Get-SPOSite.

Requirements and boundaries

  • Linux and PowerShell 7.4.6 or later.
  • The accompanying o365-connect-pnp-cert-linux.ps1 file.
  • For connection, PnP.PowerShell 3.0.0 or later. If needed, the template can install it for the current user when running interactively.
  • For app provisioning, Microsoft.Graph.Authentication 2.0.0 or later and an administrator able to sign in and consent to the requested application permissions.
  • Provisioning and interactive prompts are unavailable in headless mode.
  • No sudo, OpenSSL, certificate-store installation, or child PowerShell process is used.

This script is not the Windows SharePoint Online Management Shell script. On Windows, use o365-connect-spo-cert.ps1.

Operating modes

Specify exactly one of these modes:

Mode Switch Operation
Generate certificate -GenerateLocalCertificate Creates a self-signed RSA-2048 certificate, a public .cer, and a password-protected private-key .pfx. The default subject is O365-SPO-AppAuth; the default validity is two years. Generation alone does not require PowerShell modules.
Connect -UseCertificateAuth Resolves connection details from explicit parameters and/or a saved profile, validates the PFX, and calls Connect-PnPOnline for the SharePoint admin center.

-ProvisionEntraApp can be added only to certificate generation. It uploads the generated public certificate to an Entra application, creates or reuses its service principal, assigns the required application roles, and saves a connection profile. The private PFX stays local.

How the script operates

1. Validate the environment and selected mode

The wrapper stops if the host is not Linux, the companion PnP template is missing, or both/neither mode switches are selected. App provisioning also requires certificate generation and interactive sign-in; it cannot be combined with -Headless/-noprompt.

2. Choose storage locations

Unless overridden, the wrapper uses:

  • Certificate output directory: $XDG_DATA_HOME/ciaops/spo, or ~/.local/share/ciaops/spo when XDG_DATA_HOME is not an absolute path.
  • Profile map: $XDG_CONFIG_HOME/ciaops/spo/o365-spo-admin-cert-auth.json, or ~/.config/ciaops/spo/o365-spo-admin-cert-auth.json when XDG_CONFIG_HOME is not an absolute path.

-GeneratedCertOutputPath and -CertificateMapPath override those locations. These directories are intended for this script's private data, not shared files. The underlying template restricts dedicated storage directories to owner-only access (mode 700) and creates private files with owner read/write access (mode 600); symbolic links in protected storage paths are rejected. A supplied PFX must also be owner-only.

3. Resolve SharePoint tenant and admin URL

-AdminUrl accepts an HTTPS SharePoint admin-center URL, and -SiteUrl is an alias for it. The URL must use a SharePoint admin host such as https://contoso-admin.sharepoint.com, have no extra path/query/fragment/user information, and use the standard HTTPS port.

If -AdminUrl is omitted, the wrapper derives it from a tenant domain matching name.onmicrosoft.com, producing https://name-admin.sharepoint.com. For a tenant ID, custom domain, renamed tenant, or any other case where that derivation does not apply, supply the correct -AdminUrl explicitly or select a matching profile.

4. Resolve connection parameters from a profile or explicit values

The profile map may be a JSON array or an object with a profiles array. For connection, the wrapper searches the default map (or -CertificateMapPath) when a profile is requested or the explicit connection details are incomplete. It filters by any supplied -ProfileName, -Tenant, and -AdminUrl; exactly one result is required. Zero or multiple matches are errors rather than an implicit selection.

Profiles can use adminUrl or siteUrl for the URL. The wrapper normalizes the selected value into the template's SiteUrl parameter. Relative certificateFilePath values are resolved relative to the profile map's directory. A supplied -CertificateFilePath overrides the saved path.

When all of -Tenant, -AdminUrl, -AppId, and -CertificateFilePath are supplied and no profile name is requested, the wrapper can connect without reading a profile. A Windows-origin profile containing only a certificate thumbprint is not sufficient on Linux: provide an exported PFX file, either using -CertificateFilePath or a certificateFilePath profile property.

During provisioning, the generated profile contains the profile name, tenant, admin URL (stored as siteUrl), app ID, certificate thumbprint, and PFX path. It does not store a PFX password.

5. Generate and optionally provision

Certificate generation prompts for a non-empty PFX password unless one is supplied using -CertificatePassword or -CertificatePasswordEnvironmentVariable. The template creates the RSA-2048/SHA-256 certificate and exports the .cer and encrypted .pfx into the protected output directory. It reports their paths, the certificate thumbprint, and expiry.

With -ProvisionEntraApp, the template then:

  1. Signs in to Microsoft Graph using device-code authentication for the specified -Tenant.
  2. Creates or reuses the app identified by -AppDisplayName (defaulting to -GeneratedCertSubject), rejecting ambiguous duplicate display names.
  3. Adds the public certificate credential without intentionally removing existing credentials, and ensures the required app roles are assigned.
  4. Grants SharePoint Sites.FullControl.All and Microsoft Graph Application.Read.All application permissions, then saves the profile.

Provisioning is a privileged operation: Sites.FullControl.All is tenant-wide SharePoint site full control. Review and approve these permissions deliberately. The Linux provisioning flow does not request Graph Group.Read.All. Newly granted permissions may take time to replicate; the script recommends connecting from a fresh pwsh session.

6. Validate the PFX and connect

For connection, the template obtains the password, resolves the PFX, checks that its permissions are owner-only, imports it using ephemeral key storage, and verifies that:

  • The file contains a private key, not only a public certificate.
  • An optional -CertificateThumbprint matches the PFX.
  • The certificate is currently valid; certificates expiring within 30 days trigger a warning.

The template then imports PnP.PowerShell if required and invokes Connect-PnPOnline with the admin URL, tenant, app ID, PFX path, and password. On success, the connection remains available in the same PowerShell process for subsequent PnP commands. Run the script in the same session as those commands; no disconnect is performed on successful completion.

Parameters

Parameter Purpose
-GenerateLocalCertificate Select certificate-generation mode.
-UseCertificateAuth Select connection mode.
-ProvisionEntraApp During generation, provision an Entra application and save a profile. Requires interactive administrator sign-in.
-Tenant Tenant domain or ID; also filters profile selection.
-AdminUrl / -SiteUrl SharePoint admin-center URL. -SiteUrl is an alias. May be derived for an onmicrosoft.com tenant domain.
-AppId Application (client) ID for explicit connection.
-ProfileName Select a named profile; ambiguous or absent matches are errors. During provisioning, sets the saved profile name.
-CertificateMapPath JSON profile map path.
-CertificateFilePath PFX path for connection; overrides the profile path.
-CertificateThumbprint Optional expected certificate thumbprint; when provided from a profile or explicitly, it is checked against the PFX.
-CertificatePassword SecureString PFX password for generation or connection. Prompts if omitted unless headless.
-CertificatePasswordEnvironmentVariable Name of a process environment variable containing an injected PFX password. Used when the relevant SecureString is omitted.
-GeneratedCertSubject Generated certificate subject and, by default, app display name. Defaults to O365-SPO-AppAuth.
-GeneratedCertYearsValid Generated certificate lifetime, from 1 to 100 years; defaults to 2.
-GeneratedCertOutputPath Certificate output directory.
-AppDisplayName Entra app display name during provisioning; defaults to the generated certificate subject.
-SetupClientId Optional tenant-approved public client ID for Graph device-code sign-in.
-Headless / -noprompt Disable interactive prompts. Requires preinstalled modules and a supplied password; cannot be used for app provisioning.
-noupdate Skip the PnP.PowerShell Gallery version check.
-enableLog Enable the underlying template's timestamped transcript logging. Protect logs: provisioning transcripts may contain short-lived device codes.

Other certificate, logging, and module parameters are passed through to the Linux PnP template. Consult that template's help for additional details.

Examples

Generate a certificate and provision an app

./o365-connect-spo-cert-linux.ps1 `
  -GenerateLocalCertificate `
  -ProvisionEntraApp `
  -Tenant contoso.onmicrosoft.com

The wrapper derives https://contoso-admin.sharepoint.com from this tenant. The operation prompts for the PFX password and for Microsoft Graph device-code administrator sign-in, then saves a profile at the default profile-map path.

Connect with a saved profile

./o365-connect-spo-cert-linux.ps1 `
  -UseCertificateAuth `
  -ProfileName O365-SPO-AppAuth

The script prompts for the profile's PFX password unless provided through a supported secure input.

Connect with explicit parameters

./o365-connect-spo-cert-linux.ps1 `
  -UseCertificateAuth `
  -Tenant contoso.onmicrosoft.com `
  -AdminUrl https://contoso-admin.sharepoint.com `
  -AppId 11111111-2222-3333-4444-555555555555 `
  -CertificateFilePath /home/admin/auth.pfx `
  -CertificatePassword $vaultPassword `
  -Headless

For unattended operation, preinstall the required module and ensure the PFX is owner-only (for example, chmod 600 /home/admin/auth.pfx). Prefer a secret vault or securely injected process environment variable over a literal password in a command or script.

Password and data handling

  • Passwords are never saved in the profile map.
  • -CertificatePasswordEnvironmentVariable reads a process-scoped variable and converts its value to a SecureString for the operation. Environment variables may be visible to other processes running as the same user; prefer a secret vault where practical.
  • On Linux, ConvertFrom-SecureString is not DPAPI encryption. Do not treat a serialized SecureString as protected by the Windows account-bound DPAPI behavior.
  • The PFX contains the private key. Keep it in the dedicated private directory and do not distribute it; only the public .cer is uploaded to Entra.
  • Restrict access to transcript logs. Provisioning may print a short-lived device code.

Common errors and their meaning

  • Specify exactly one mode: add exactly one of -GenerateLocalCertificate or -UseCertificateAuth.
  • Required Linux template is missing: place o365-connect-pnp-cert-linux.ps1 beside this script.
  • Expected one matching profile: adjust the profile name/tenant/admin URL filters, or supply all required connection values explicitly.
  • Connection requires Tenant, AdminUrl, AppId and CertificateFilePath: provide missing values or select a complete profile.
  • Admin URL validation failed: use the HTTPS SharePoint admin-center root URL, not a site URL or a general SharePoint URL.
  • PFX permissions must be owner-only: restrict the file to its owner's read/write permissions (mode 600).
  • Headless mode requires a password or modules are missing: supply a SecureString/environment variable and install required modules before running headlessly.
  • Certificate permissions may take time to replicate: after provisioning, retry from a fresh PowerShell session.

Related documentation

Clone this wiki locally