Utiliser ACS pour autoriser des compléments hébergés par un fournisseur à faible niveau de fiabilité sur un site SharePoint local

Article
04/08/2023

Conditions préalables

Assurez-vous que vous disposez des éléments suivants :

Un environnement de développement SharePoint en local. Reportez-vous à la rubrique Configurer un environnement de développement local pour les compléments SharePoint.
Un site SharePoint Office 365. Si vous n’en avez pas encore et que vous souhaitez configurer rapidement un environnement de développement, vous pouvez configurer un environnement de développement pour les compléments SharePoint sur Office 365.
Visual Studio installé à distance ou sur un ordinateur exécutant SharePoint, avec la charge de travail Développement Office/SharePoint. Les versions antérieures de Visual Studio nécessitent plutôt le composant Outils de développement Microsoft Office pour Visual Studio . La dernière version de ce composant est disponible ici pour Visual Studio 2013 et ici pour Visual Studio 2015.

Importante

Le retrait d’ACS côté Azure Active Directory n’a pas d’impact sur cette fonctionnalité pour SharePoint. Pour plus d'informations, reportez-vous à l’article relatif à l’impact du retrait d'Azure Access Control pour les compléments SharePoint.

Configurer votre installation locale de SharePoint pour utiliser ACS

La figure suivante décrit les quatre étapes permettant d’activer les connexions dont vous avez besoin dans l’architecture globale d’un complément hébergé par un fournisseur exécuté en local. Elle montre également le flux des jetons OAuth lorsque le complément est en cours d’exécution.

Utiliser ACS avec une installation locale de SharePoint à l’aide d’un site SharePoint Office 365

Faire fonctionner ACS avec une installation de SharePoint sur site en utilisant un site Office 365

Créez un proxy ACS dans votre batterie de serveurs SharePoint sur site.
Installez le certificat de signature de votre serveur sur site pour votre location Office 365.
Ajoutez les noms de domaine complets des sites de la batterie de serveurs SharePoint où vous voulez exécuter les compléments à la collection de noms de principal de service dans votre location Office 365.
Créez un proxy de gestion des compléments sur votre batterie de serveurs SharePoint.

La fonction suivante fait tout le travail pour configurer votre site SharePoint local pour utiliser ACS. Vous pouvez également utiliser cette fonction pour effectuer certaines tâches de nettoyage si vous avez besoin de supprimer des configurations antérieures. Il existe de nombreuses façons d’exécuter la fonction dans PowerShell. La méthode qui suit en est une.

Pour configurer votre installation SharePoint locale pour utiliser ACS

Sur le serveur SharePoint local, copiez le code de la fonction Connect-SPFarmToAAD (disponible ci-dessous) dans un fichier texte nommé MySharePointFunctions.psm1, puis enregistrez-le dans l’un ou l’autre des dossiers suivants (pas les deux). Vous devrez peut-être créer des parties du chemin d’accès, s’il contient des dossiers qui n’existent pas encore. Notez que, dans les deux cas, le dossier le plus bas dans le chemin d’accès doit porter le même nom que le fichier.

Conseil

Le fichier doit être enregistré au format ANSI, et non UTF-8. PowerShell peut donner des erreurs de syntaxe lorsqu’il charge un fichier dans un format non-ANSI. Le Bloc-notes Windows enregistre par défaut au format ANSI. Si vous utilisez un autre éditeur pour enregistrer le fichier, assurez-vous que vous l’enregistrez au format ANSI.
- C:\users\username\documents\windowspowershell\modules\MySharePointFunctions, où username désigne l’administrateur de la batterie de serveurs qui exécute le fichier.
- C:\windows\system32\windowspowershell\V1.0\modules\MySharePointFunctions
La fonction Connect-SPFarmToAAD nécessite que le package NuGet MSOnlineExt fonctionne, installez-le avec l’applet de commande ci-dessous.
```
Install-Module -Name MSOnlineExt
```
Ouvrez le SharePoint Management Shell en tant qu’administrateur et exécutez la cmdlet suivante pour vérifier que le module MySharePointFunctions est répertorié.
```
Get-Module -listavailable
```
Exécutez la cmdlet suivante pour importer le module.
```
Import-Module MySharePointFunctions
```
Exécutez la cmdlet suivante pour vérifier que la fonction Connect-SPFarmToAAD est répertoriée dans le cadre du module.
```
Get-Command -module MySharePointFunctions
```
Exécutez la cmdlet suivante pour vérifier que la fonction Connect-SPFarmToAAD est chargée.
```
ls function:\ | where {$_.Name -eq "Connect-SPFarmToAAD"}
```
Exécutez la fonction Connect-SPFarmToAAD. Veillez à fournir les paramètres obligatoires et tous les paramètres facultatifs qui s’appliquent à votre environnement de développeur. Consultez la section suivante pour obtenir plus d’informations et des exemples.

Paramètres de la fonction Connect-SPFarmToAAD

Paramètre	Valeur
`-AADDomain` (obligatoire)	Domaine . onmicrosoft.com que vous avez créé lorsque vous vous êtes inscrit pour votre site Office 365 (votredomainepersonnalisé. onmicrosoft.com). Lorsque le script vous invite à vous authentifier, utilisez le nom d’utilisateur et le mot de passe créés pour ce domaine : nom_utilisateur@votredomainepersonnalisé*. onmicrosoft.com.
`-SharePointOnlineUrl` (obligatoire)	URL de votre site SharePoint Office 365 (`_https://yourcustomdomain_.sharepoint.com`). Notez que le domaine parent n’est pas onmicrosoft.com.
`-SharePointWeb` (parfois obligatoire)	URL complète (y compris le protocole) de l’application web SharePoint locale dans laquelle vous allez exécuter des compléments hébergés par un fournisseur. Cette fonction n’ajoute qu’une seule application web SharePoint provenant de votre batterie de serveurs locale à ACS. Si vous ne spécifiez pas de valeur, le script sélectionne la première application web de votre batterie de serveurs. Si vous utilisez une collection de sites de l’hôte de sites (HNSC) qui peut être définie avec un caractère générique (comme http://.contoso.com), vous pouvez utiliser cette chaîne comme valeur pour ce paramètre. Si l’application web comporte un mappage des accès de substitution (AAM) pour la zone Internet, vous devez utiliser cette URL AAM pour ce paramètre. Si l’application web SharePoint n’est pas configurée pour le protocole HTTPS, vous devez utiliser le protocole HTTP et vous devez utiliser le commutateur -AllowOverHttp (voir plus loin dans ce tableau).* Si vous souhaitez exécuter des compléments hébergés par un fournisseur qui utilisent ACS sur plusieurs applications web de votre batterie de serveurs, vous devez les ajouter à la collection de nom de principal du service. Le script Windows PowerShell qui suit la fonction `Connect-SPFarmToAAD` vous indique comment ajouter toutes les applications web de votre batterie de serveurs à la collection de nom de principal du service.
`-AllowOverHttp` (facultatif)	Utilisez ce commutateur si vous travaillez avec un environnement de développeur et que vous ne voulez pas utiliser SSL avec vos compléments. Vous devez utiliser ce commutateur si l'application web SharePoint n'est pas configurée pour HTTPS.
`-O365Credentials` (facultatif)	Le premier caractère est un « O » majuscule, et non un zéro. Si vous vous retrouvez souvent à exécuter de nouveau le script à des fins de débogage, ce commutateur vous permet d’éviter de devoir saisir manuellement vos nom et mot de passe O365 à chaque fois. Pour pouvoir utiliser ce paramètre, vous devez créer l’objet informations d’identification que vous lui attribuerez avec ces cmdlets :`$User = "username@yourcustomdomain.onmicrosoft.com"$PWord = ConvertTo-SecureString -String "the_password" -AsPlainText -Force$Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $User, $PWord` Utilisez `$Credential` comme valeur du `-O365Credentials` paramètre .
`-Verbose` (facultatif)	Ce commutateur génère des commentaires plus détaillés qui peuvent être utiles si la fonction est inefficace et si vous devez l’exécuter de nouveau pour le débogage.
`-RemoveExistingACS` (facultatif)	Utilisez ce commutateur si vous souhaitez remplacer une connexion existante à Azure Active Directory. Il supprime un proxy ACS existant si vous en avez déjà créé un pour votre batterie de serveurs.
`-RemoveExistingSTS` (facultatif)	Utilisez ce commutateur si vous souhaitez remplacer une connexion existante à Azure Active Directory. Il supprime un émetteur de jetons de sécurité fiable existant, resté après une connexion antérieure à ACS.
`-RemoveExistingSPOProxy` (facultatif)	Utilisez ce commutateur si vous souhaitez remplacer une connexion existante à Azure Active Directory. Il supprime un proxy de gestion de compléments existant si vous en avez déjà créé un pour votre batterie de serveurs.
`-RemoveExistingAADCredentials` (facultatif)	Utilisez ce commutateur si vous remplacez le site SharePoint Office 365.

Les éléments suivants sont des exemples :

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com -SharePointWeb https://fabrikam.com

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com -SharePointWeb http://northwind.com -AllowOverHttp

Connect-SPFarmToAAD -AADDomain 'MyO365Domain.onmicrosoft.com' -SharePointOnlineUrl https://MyO365Domain.sharepoint.com -SharePointWeb http://northwind.com -AllowOverHttp -RemoveExistingACS -RemoveExistingSTS -RemoveExistingSPOProxy -RemoveExistingAADCredentials

Contenu de MySharePointFunctions.psm1

function Connect-SPFarmToAAD {
param(
    [Parameter(Mandatory)][String]   $AADDomain,
    [Parameter(Mandatory)][String]   $SharePointOnlineUrl,
    #Specify this parameter if you don't want to use the default SPWeb returned
    [Parameter()][String]            $SharePointWeb,
    [Parameter()][System.Management.Automation.PSCredential] $O365Credentials,
    #Use these switches if you're replacing an existing connection to AAD.
    [Parameter()][Switch]            $RemoveExistingACS,
    [Parameter()][Switch]            $RemoveExistingSTS,
    [Parameter()][Switch]            $RemoveExistingSPOProxy,
    #Use this switch if you're replacing the Office 365 SharePoint site.
    [Parameter()][Switch]            $RemoveExistingAADCredentials,
    #Use this switch if you don't want to use SSL when you launch your app.
    [Parameter()][Switch]            $AllowOverHttp
)
    #Prompt for credentials right away.
    if (-not $O365Credentials) {
        $O365Credentials = Get-Credential -Message "Admin credentials for $AADDomain"
    }
    Add-PSSnapin Microsoft.SharePoint.PowerShell
    #Import the Microsoft Online Services Sign-In Assistant.
    Import-Module -Name MSOnline
    #Import the Microsoft Online Services Module for Windows PowerShell.
    Import-Module MSOnlineExt -force -verbose 
    #Set values for Constants.
    New-Variable -Option Constant -Name SP_APPPRINCIPALID -Value '00000003-0000-0ff1-ce00-000000000000' | Out-Null
    New-Variable -Option Constant -Name ACS_APPPRINCIPALID -Value '00000001-0000-0000-c000-000000000000' | Out-Null
    New-Variable -Option Constant -Name ACS_APPPROXY_NAME -Value ACS
    New-Variable -Option Constant -Name SPO_MANAGEMENT_APPPROXY_NAME -Value 'SPO Add-in Management Proxy'
    New-Variable -Option Constant -Name ACS_STS_NAME -Value ACS-STS
    New-Variable -Option Constant -Name AAD_METADATAEP_FSTRING -Value 'https://accounts.accesscontrol.windows.net/{0}/metadata/json/1'
    New-Variable -Option Constant -Name SP_METADATAEP_FSTRING -Value '{0}/_layouts/15/metadata/json/1'
    #Get the default SPWeb from the on-premises farm if no $SharePointWeb parameter is specified.
    if ([String]::IsNullOrEmpty($SharePointWeb)) {
        $SharePointWeb = Get-SPSite | Select-Object -First 1 | Get-SPWeb | Select-Object -First 1 | % Url
    }

    #Configure the realm ID for local farm so that it matches the AAD realm.
    $ACSMetadataEndpoint = $AAD_METADATAEP_FSTRING -f $AADDomain
    $ACSMetadata = Invoke-RestMethod -Uri $ACSMetadataEndpoint
    $AADRealmId = $ACSMetadata.realm

    Set-SPAuthenticationRealm -ServiceContext $SharePointWeb -Realm $AADRealmId
    
    $LocalSTS = Get-SPSecurityTokenServiceConfig
    $LocalSTS.NameIdentifier = '{0}@{1}' -f $SP_APPPRINCIPALID,$AADRealmId
    $LocalSTS.Update()

    #Allow connections over HTTP if the switch is specified.
    if ($AllowOverHttp.IsPresent -and $AllowOverHttp -eq $True) {
        $serviceConfig = Get-SPSecurityTokenServiceConfig
        $serviceConfig.AllowOAuthOverHttp = $true
        $serviceConfig.AllowMetadataOverHttp = $true
        $serviceConfig.Update()
    }

    #Step 1: Set up the ACS proxy in the on-premises SharePoint farm. Remove the existing ACS proxy
    #if the switch is specified.
    if ($RemoveExistingACS.IsPresent -and $RemoveExistingACS -eq $True) {
        Get-SPServiceApplicationProxy | ? DisplayName -EQ $ACS_APPPROXY_NAME | Remove-SPServiceApplicationProxy -RemoveData -Confirm:$false
    }
    if (-not (Get-SPServiceApplicationProxy | ? DisplayName -EQ $ACS_APPPROXY_NAME)) {
        $AzureACSProxy = New-SPAzureAccessControlServiceApplicationProxy -Name $ACS_APPPROXY_NAME -MetadataServiceEndpointUri $ACSMetadataEndpoint -DefaultProxyGroup
    }

    #Remove the existing security token service if the switch is specified.
    if ($RemoveExistingSTS.IsPresent) {
        Get-SPTrustedSecurityTokenIssuer | ? Name -EQ $ACS_STS_NAME | Remove-SPTrustedSecurityTokenIssuer -Confirm:$false
    }
    if (-not (Get-SPTrustedSecurityTokenIssuer | ? DisplayName -EQ $ACS_STS_NAME)) {
        $AzureACSSTS = New-SPTrustedSecurityTokenIssuer -Name $ACS_STS_NAME -IsTrustBroker -MetadataEndPoint $ACSMetadataEndpoint
    }

    #Update the ACS Proxy for OAuth authentication.
    $ACSProxy = Get-SPServiceApplicationProxy | ? Name -EQ $ACS_APPPROXY_NAME
    $ACSProxy.DiscoveryConfiguration.SecurityTokenServiceName = $ACS_APPPRINCIPALID
    $ACSProxy.Update()

    #Retrieve the local STS signing key from JSON metadata.
    $SPMetadata = Invoke-RestMethod -Uri ($SP_METADATAEP_FSTRING -f $SharePointWeb)
    $SPSigningKey = $SPMetadata.keys | ? usage -EQ "Signing" | % keyValue
    $CertValue = $SPSigningKey.value
    
    #Connect to Office 365.
    Connect-MsolService -Credential $O365Credentials
    #Remove existing connection to an Office 365 SharePoint site if the switch is specified.
    if ($RemoveExistingAADCredentials.IsPresent -and $RemoveExistingAADCredentials -eq $true) {
        $msolserviceprincipal = Get-MsolServicePrincipal -AppPrincipalId $SP_APPPRINCIPALID
        [Guid[]] $ExistingKeyIds = Get-MsolServicePrincipalCredential -ObjectId $msolserviceprincipal.ObjectId -ReturnKeyValues $false | % {if ($_.Type -ne "Other") {$_.KeyId}}
        Remove-MsolServicePrincipalCredential -AppPrincipalId $SP_APPPRINCIPALID -KeyIds $ExistingKeyIds
    }
    #Step 2: Upload the local STS signing certificate
    New-MsolServicePrincipalCredential -AppPrincipalId $SP_APPPRINCIPALID -Type Asymmetric -Value $CertValue -Usage Verify

    #Step 3: Add the service principal name of the local web application, if necessary.
    $indexHostName = $SharePointWeb.IndexOf('://') + 3
    $HostName = $SharePointWeb.Substring($indexHostName)
    $NewSPN = '{0}/{1}' -f $SP_APPPRINCIPALID, $HostName
    $SPAppPrincipal = Get-MsolServicePrincipal -AppPrincipalId $SP_APPPRINCIPALID
    if ($SPAppPrincipal.ServicePrincipalNames -notcontains $NewSPN) {
        $SPAppPrincipal.ServicePrincipalNames.Add($NewSPN)
        Set-MsolServicePrincipal -AppPrincipalId $SPAppPrincipal.AppPrincipalId -ServicePrincipalNames $SPAppPrincipal.ServicePrincipalNames
    }

    #Remove the existing SharePoint Online proxy if the switch is specified.
    if ($RemoveExistingSPOProxy.IsPresent -and $RemoveExistingSPOProxy -eq $True) {
        Get-SPServiceApplicationProxy | ? DisplayName -EQ $SPO_MANAGEMENT_APPPROXY_NAME | Remove-SPServiceApplicationProxy -RemoveData -Confirm:$false
    }
    #Step 4: Add the SharePoint Online proxy
    if (-not (Get-SPServiceApplicationProxy | ? DisplayName -EQ $SPO_MANAGEMENT_APPPROXY_NAME)) {
        $spoproxy = New-SPOnlineApplicationPrincipalManagementServiceApplicationProxy -Name $SPO_MANAGEMENT_APPPROXY_NAME -OnlineTenantUri $SharePointOnlineUrl -DefaultProxyGroup
    }  
}

Configurer le complément et l’application web SharePoint pour l’Office Store

Voici une étape de configuration facultative que les administrateurs de batteries de serveurs doivent effectuer dans les environnements de production, s’ils souhaitent que les utilisateurs puissent installer des compléments hébergés par un fournisseur qui utilisent ACS à partir d’Office Store. (Elle n’a aucune utilité pour votre environnement de développement SharePoint, sauf si vous prévoyez d’installer des compléments qui utilisent ACS à partir d’Office Store pour cet environnement.) La cmdlet suivante le permet. Ce code peut être ajouté à la fonction précédente.

New-SPMarketplaceWebServiceApplicationProxy -Name "ApplicationIdentityDataWebServiceProxy" -ServiceEndpointUri "https://oauth.sellerdashboard.microsoft.com/ApplicationIdentityDataWebService.svc" -DefaultProxyGroup

Il est également recommandé, pour les applications web SharePoint de production, d’activer la fonctionnalité Compléments qui nécessitent des points de terminaison accessibles sur Internet après avoir terminé les étapes de configuration. (Voir les instructions suivantes.) Cette fonctionnalité n’effectue pas réellement d’opération. Elle sert simplement d’indicateur précisant à l’Office Store que les compléments hébergés par un fournisseur qui utilisent ACS peuvent être installés sur des sites web dans l’application web SharePoint.

Ce système peut avoir des implications pour le manifeste du complément de votre complément SharePoint. Si vous envisagez de vendre votre complément par le biais de la boutique, il est recommandé d’ajouter l’élément AppPrerequiste suivant dans la section AppPrerequisites du manifeste du complément :

<AppPrerequisite Type="Feature" ID="{7877bbf6-30f5-4f58-99d9-a0cc787c1300}" />

L’effet de la condition préalable est le suivant : lorsque les utilisateurs parcourent la boutique à partir d’une batterie de serveurs SharePoint locale, si la fonctionnalité Compléments qui nécessitent des points de terminaison accessibles sur Internet de l’application web SharePoint parent n’est pas activée, votre complément sera grisé et non installable. Vous vous assurez ainsi que vous n’aurez pas de réclamations de clients ayant installé votre complément sur un site web SharePoint local et constaté qu’il ne fonctionnait pas.

Il existe deux manières d’activer la fonctionnalité. La première consiste à exécuter la cmdlet PowerShell suivante (qui peut être ajoutée à la fin de la fonction précédente) sur n’importe quel serveur SharePoint :

Enable-SPFeature -identity "7877bbf6-30f5-4f58-99d9-a0cc787c1300" -Url http://domain_of_the_SharePoint_web_application

La seconde manière d’activer la fonction consiste à effectuer les étapes suivantes dans l’Administration centrale :

Dans l’Administration centrale de SharePoint, accédez à Gestion des applications>Gérer les applications web.
Sur la page Gérer les applications web, sélectionnez l’application web que vous voulez modifier.
Dans le ruban, sélectionnez Gérer les fonctionnalités.
Dans la liste des fonctionnalités, en regard de Compléments qui nécessitent des points de terminaison accessibles sur Internet, sélectionnez Activer.
Sélectionnez OK.

Configurer des applications web SharePoint supplémentaires dans la batterie de serveurs

Si vous avez d'autres applications web dans votre batterie de serveurs SharePoint et que vous voulez y exécuter les compléments hébergés par un fournisseur qui utilisent l'approbation ACS, vous pouvez utiliser ce script Windows PowerShell (dans SharePoint Management Shell) pour les ajouter à la collection de noms de principal de service.

$SPAppPrincipal = Get-MsolServicePrincipal -AppPrincipalId 00000003-0000-0ff1-ce00-000000000000
$id = "00000003-0000-0ff1-ce00-000000000000/"

Get-SPWebApplication | ForEach-Object {
    $hostName = $_.Url.substring($_.Url.indexof("//") + 2)
    $hostName = $hostName.Remove($hostName.Length - 1, 1)

    $NewSPN = $id + $hostName

    Write-Host "Adding SPN for" $NewSPN

    if ($SPAppPrincipal.ServicePrincipalNames -notcontains $NewSPN) {
       $SPAppPrincipal.ServicePrincipalNames.Add($NewSPN)
       Set-MsolServicePrincipal -AppPrincipalId $SPAppPrincipal.AppPrincipalId -ServicePrincipalNames $SPAppPrincipal.ServicePrincipalNames
    }
}