Table of Contents

Azure ACS Retirement

Microsoft is retiring the use of Azure ACS (Access Control Services) for SharePoint Online.

Azure ACS will stop working for new tenants on November 1st, 2024 and it will stop working for existing tenants and will be fully retired as of April 2nd, 2026. This applies to all environments.

As a result, Ometa has adopted their authentication layers towards all SharePoint environments (Cloud and on-premise subscriptions) to take into account this retirement.

More information about this retirement can be found here.

Important

The following authentication methods will not work anymore towards SharePoint environments:

  • Client Id and Secret
  • Azure Key Vault
  • For SharePoint Online: email and password

The following authentication methods work:

  • For SharePoint Online: Only Azure AD Certificates
  • For SharePoint On-premise: Username and password

Authentication Methods

The Ometa framework offers several authentication methods towards SharePoint. Below is an ordered list of the authentication methods that the framework supports. The first method that is configured in the profile will be used.

Name Necessary Settings Fields Where to use?
Azure AD Certificate
  • ClientID and optionally SharePointOnlineTenant
    If ClientID has a value in the form of **clientId@tenantIdOrUrl**, the field SharePointOnlineTenant is not required.
  • SharePointOnlineAzureADCertificate or Certificate
 SharePoint Online
Username Password
  • Username
  • Password
  • Domain
 SharePoint On-premise

Setup

A few steps are needed to configure SharePoint authentication in the framework. You'll need to register an application in the Microsoft Entra portal and configure SharePoint API permissions on it.

Warning

In the following steps, you will be adding an application to Microsoft Entra. Don't do this under your personal account, but use an account of your organisation.

Register the Ometa Framework as a Microsoft Entra Application

Note

This step is optional if you already registered a Microsoft Entra application for authenticating users with the Microsoft provider in the Ometa Framework.

If so, you can extend that application with the required API permissions. However, you can also choose to create a separate Microsoft Entra application for integrating the Ometa Framework with SharePoint.

  1. Login to the Microsoft Entra Portal, navigate to the App Registrations and click on New registration.

  2. Fill-in the name which you want to use for this application.

    Note

    It is a best practice to name this application using your company's name. When the solution is used by external parties, they will need to provide consent via a user consent prompt. The display name for this application will be used in this user consent screen.
    Using your company name increases trust and confidence for external users when providing this information. If you have any further questions about how Ometa processes sensitive information, please refer to the GDPR article.

  3. Choose which account types will be logging in via this application. When this application will only be used for integrating the Ometa Framework with SharePoint, accounts in this organizational directory only will suffice.

  4. Click on Register.

Register Application

Configure a Certificate

The Microsoft Entra application has now been registered. The next step is to configure a certificate to establish trust between the Ometa Framework and the Microsoft Entra application. This certificate must be stored on the Ometa server with its private key. The public part of the certificate is uploaded to the Microsoft Entra application.

You can either use:

  • Self-Signed Certificates: These are created and signed by you. They are suitable for testing and development but not recommended for production environments due to security concerns.
  • Certificate Authority (CA)-Signed Certificates: These are issued by trusted third-party CAs and are recommended for production environments.

Generating a Self-Signed Certificate

Important

A self-signed certificate should not be used on production environments.

If you don't already have a certificate, a self-signed certificate can be generated using the following steps:

  • Ensure that PowerShell version 7 is installed. The version can be checked with the following command: $PSVersionTable.PSVersion
  • You need PowerShell 7.2 or later to use PnP PowerShell. It is available for Windows, Linux and Mac and can be installed through here.
  • The following command can be used to generate the certificate, change the password and names accordingly:
Install-Module PnP.PowerShell 
Import-Module PnP.PowerShell
New-PnPAzureCertificate -CertificatePassword (ConvertTo-SecureString -String "verySecurePassword" -AsPlainText -Force) -OutCert "c:\temp\ometa.cer" -OutPfx "c:\temp\ometa.pfx" -CommonName "Ometa Certificate" -Organization "Ometa BV" -Country "BE"

More information about PnP PowerShell can be found here.

Using the Certificate

  • Import the certificate on the Ometa server under local machine, using the .pfx file.
  • Upload the certificate to the Microsoft Entra application in the Certificates & secrets section.

Upload Certificate on Azure portal

Configure the certificate in the framework.

  • For SharePoint / BuildingBlock / Mail BuildingBlocks, these are the SharePointOnlineAzureADCertificate / Certificate / Certificate PEM Path and SharePointOnlineTenant/ ClientID / OAuth Client ID fields in the profiles. The value of the certificate should be the subject name and can be found in the details of the certificate in the Computer Certificates.
Important

The Ometa Framework selects the first certificate it finds in the local computer certificate store with the configured subject name. To ensure the correct certificate is selected, please remove any older (expired) certificates with the same subject name.

Note

Due to migration changes, multiple fields are used to check for the certificate and tenant.

  • For the certificate, the fields SharePointOnlineAzureADCertificate, Certificate and Certificate PEM Path are checked
  • For the tenant id or url, the fields SharePointOnlineTenant, ClientID and OAuth Client ID are checked. If the value of the field ClientID or OAuth Client ID is in the form ClientId@TenantIdOrUrl, the SharePointOnlineTenant field can be left empty.

Set Certificate in Ometa Profile

This profile configuration can also be applied to SharePoint profiles, (Mail) BuildingBlock profiles and OData/REST profiles targeting the Microsoft ecosystem (SharePoint, Graph API, ...).

You're now able to integrate the Ometa Framework with your SharePoint environment if the app has the necessary API permissions to access SharePoint.

Configuration in the Ometa Framework

If you intend to use the same authentication method throughout the framework, check the following configurations:

Granting API Permissions to the Client

Once the Microsoft Entra application is set up, it needs sufficient permissions to invoke the SharePoint calls.

See the list above for which permissions you'll need to configure.

Grant Full Control Permission

Afterwards the admin consent should be granted.

Grant Admin Consent.png

When troubleshooting, you will have to restart the web services for Ometa to fetch a new token with the updated permissions.

Sites.Selected

The Sites.Selected SharePoint API permission in Microsoft Entra allows applications to access specific SharePoint sites with granular control. This is particularly useful for scenarios where you want to limit an application’s access to only certain sites rather than the entire SharePoint environment.

  1. Go to the application.
  2. Go to API permissions > Add a permission.
  3. Choose SharePoint and select Application permissions.
  4. Search for and select Sites.Selected. This permission allows your app to access specific SharePoint sites.
  5. Make sure to Grant Admin Consent for the permission to take effect.

Sites Selected

PowerShell

As of September 9th, 2024, it is no longer possible to use PnP PowerShell using -Interactive or -Credentials parameters without registering your own app with Microsoft Entra! The PnP PowerShell team says this change was made to improve security.

This means that you need to ensure a PNP PowerShell in Microsoft Entra with Delegated Graph API Permissions: Sites.FullControl.All. You can either create one manually or use the following PowerShell command:

# Optional install the Pnp.PowerShell module.
Install-Module -Name PnP.PowerShell

Import-Module PnP.PowerShell

# Define variables
$powerShellApplicationName = "PnP PowerShell" # Replace with the name for the PnP PowerShell Application.
$tenantUrl = "https://ometadev.onmicrosoft.com"  # Replace with your tenant URL.

# Creates a new Entra Application specific for PNP PowerShell.
Register-PnPEntraIDAppForInteractiveLogin -ApplicationName $powerShellApplicationName -GraphDelegatePermissions "Sites.FullControl.All" -Tenant $tenantUrl -Interactive

# The Client ID from the PNP PowerShell Application is returned. You need this for setting up a connection to SharePoint.

Grant the Ometa Framework Entra Application FullControl permissions for the "selected" sites.

## Define variables for the application and site which needs sites.selected permissions.
$tenantUrl = ""  # Replace with your tenant URL.
$siteUrl = ""  # Replace with your site URL which needs full control permissions.
$appId = ""  # Replace with your Ometa Framework app's client ID.
$displayName = "" # Replace with the name of the application, for example: Ometa Framework.

$pnpAppId = "" # Replace with the PNP PowerShell App ID

# Create connection with the PNP PowerShell Application
Connect-PnPOnline -Url $tenantUrl -Interactive -ClientId $pnpAppId

# Grant Write permission to the app
$grant = Grant-PnPAzureADAppSitePermission -Permissions "Write" -Site $siteUrl -AppId $appId -DisplayName $displayName

# Change the permission to Full Control
Set-PnPAzureADAppSitePermission -Site $siteUrl -PermissionId $grant.Id -Permissions "FullControl"

Test if the Ometa Framework application has full control permissions through the Sites.Selected API permission. Make sure to open a new terminal.

# Open a new PowerShell Terminal.

Import-Module PnP.PowerShell

# Define variables
$siteUrl = "https://ometadev.sharepoint.com/sites/UASV-20"  # Replace with your site URL.
$appId = "c92956f2-c91c-4e20-a0f3-c2f1c676ced7"  # Replace with your app's client ID.
$tenant = "ometadev.onmicrosoft.com"  # Replace with your tenant name.
$thumbprint = "1F74F1738BCEC157977BDD160F7B417D17127121" # Replace with the thumbprint.

# Connect to SharePoint Online site
Connect-PnPOnline -Url $siteUrl -ClientId $appId -Thumbprint $thumbprint -Tenant $tenant

# Verify by creating a new list (optional)
New-PnPList -Title "Full Control List" -Template DocumentLibrary

Script to know the Thumbprint. You can also find in Microsoft Entra, in the first column.

Thumbprint

Get-ChildItem Cert:\LocalMachine\My | Where-Object {$_.Subject -eq "CN=www.example.com"} | Select-Object Thumbprint

Filling in the Building Blocks Profile

To use App-Only authentication in the Ometa Framework we need to change the profile(s). Fill in the ClientID of the Azure application, the SharePointOnlineAzureADCertificate and the SharePointOnlineTenant.

The Domain and Password fields can be left empty. They are ignored when ClientID and SharePointOnlineAzureADCertificate are set. The Username field can only be left empty if you don't use this profile for site creation.

Warning

If you use this profile for site creation, an owner account must exist in the form of an email address. If the Trigger Case Management setting on the method doesn't contain a custom owner, you need to provide an owner's email address in the Username field of this profile. Otherwise site creation will fail.

SharePoint Building Blocks App-Only Profile