ACS を使用して、オンプレミスの SharePoint サイトで低信頼のプロバイダーホスト型アドインを承認する

[アーティクル]
04/08/2023

前提条件

次のものがあることを確認します。

オンプレミスの SharePoint 開発環境。「SharePoint アドインのオンプレミスの開発環境をセットアップする」を参照してください。
Office 365 SharePoint サイト。まだ存在せず、開発環境をすばやく設定する場合は、Office 365で SharePoint アドインの開発環境を設定できます。
Visual Studio は、 Office/SharePoint 開発のワークロードを使用して、リモートまたは SharePoint を実行しているコンピューターにインストールされています。以前のバージョンの Visual Studio では、代わりに コンポーネント Microsoft Office Developer Tools for Visual Studio が必要です。このコンポーネントの最新バージョンは、Visual Studio 2013および Visual Studio 2015 の場合はここで入手できます。

重要

Azure Active Directory 側での ACS のサポート終了は、SharePoint での同機能への影響はありません。詳細については、「SharePoint アドインに対する Azure アクセス制御の終了の影響」に関する記事を参照してください。

ACS を使用するように SharePoint のオンプレミスのインストールを構成する

次の図に、オンプレミスのサイトで実行されるプロバイダー向けのホスト型アドインのアーキテクチャ全体の中で必要とされる接続を有効にするための 4 つの手順を示します。また、アドイン実行時の OAuth トークンのフローも示します。

Office 365 SharePoint サイトを使用して、ACS を SharePoint のオンプレミスのインストールで連携させる

Office 365 サイトを使用して、ACS を SharePoint のオンプレミスのインストールと連携させる

社内 SharePoint ファームで ACS プロキシを作成します。
社内サーバーの署名証明書を Office 365 テナンシーにインストールします。
アドインを実行する SharePoint ファームのサイトの完全修飾ドメイン名を、Office 365 テナンシーのサービスプリンシパル名コレクションに追加します。
SharePoint ファームでアドイン管理プロキシを作成します。

次の関数で、ACS を使用するようにオンプレミスの SharePoint サイトを構成するのに必要なすべての操作が実行されます。以前の構成を削除する必要がある場合は、この関数を使用してクリーンアップタスクのいくつかを実行することもできます。 PowerShell で関数を実行するには、さまざまな方法があります。その方法の 1 つを次に示します。

ACS を使用するようにオンプレミスの SharePoint サイトを構成する

オンプレミスの SharePoint サーバーで、関数Connect-SPFarmToAADのコード (以下で使用できます) を MySharePointFunctions.psm1 という名前のテキストファイルにコピーし、次のフォルダーのいずれか (両方ではなく) に保存します。存在していないフォルダーを含む場合は、パスの一部を作成しなければならない場合があります。どちらの場合も、パスの最下位のフォルダーは、ファイルと同じ名前である必要があります。

ヒント

ファイルは UTF-8 形式ではなく ANSI 形式で保存する必要があります。 PowerShell で ANSI 以外の形式のファイルを読み込むと、構文エラーが発生する場合があります。 Windows のメモ帳では、既定で ANSI 形式で保存されます。その他のエディターを使用してファイルを保存するときは、必ず ANSI 形式で保存してください。
- C:\users\username\documents\windowspowershell\modules\MySharePointFunctions。ここで、username はファイルを実行するファーム管理者です。
- C:\windows\system32\windowspowershell\V1.0\modules\MySharePointFunctions
関数Connect-SPFarmToAADでは、NuGet パッケージ MSOnlineExt が動作する必要があります。次のコマンドレットを使用してインストールします。
```
Install-Module -Name MSOnlineExt
```
管理者として SharePoint 管理シェルを開き、次のコマンドレットを実行して MySharePointFunctions モジュールが表示されることを確認します。
```
Get-Module -listavailable
```
次のコマンドレットを実行してモジュールをインポートします。
```
Import-Module MySharePointFunctions
```
次のコマンドレットを実行して、モジュールの一部として Connect-SPFarmToAAD 関数が表示されることを確認します。
```
Get-Command -module MySharePointFunctions
```
次のコマンドレットを実行して、Connect-SPFarmToAAD 関数が読み込まれることを確認します。
```
ls function:\ | where {$_.Name -eq "Connect-SPFarmToAAD"}
```
Connect-SPFarmToAAD 関数を実行します。開発者環境に適用される必須のパラメーターと省略可能なパラメーターを必ず指定してください。詳細と例については、次のセクションを参照してください。

Connect-SPFarmToAAD 関数のパラメーター

パラメーター	値
`-AADDomain` (必須)	Office 365 サイト (yourcustomdomain.onmicrosoft.com) にサインアップしたときに作成した .onmicrosoft.com ドメイン。スクリプトによって認証を求められたときは、このドメイン用に作成したユーザー名とパスワード (username@yourcustomdomain*.onmicrosoft.com) を使用します。
`-SharePointOnlineUrl` (必須)	Office 365 SharePoint サイト (`_https://yourcustomdomain_.sharepoint.com`) の URL。親ドメインは onmicrosoft.com ではありません。
`-SharePointWeb` (必須の場合あり)	プロバイダー向けのホスト型アドインを実行するオンプレミスの SharePoint Web アプリケーションの完全な URL (プロトコルを含む)。この関数は、オンプレミスのファームから ACS に 1 つの SharePoint Web アプリケーションのみを追加します。この値を指定しない場合、スクリプトはファームに含まれる最初の Web アプリケーションを選択します。ワイルドカードを使って定義できるホスト名サイトコレクション (HNSC) を使用している場合 (http://.contoso.com* など)、その文字列をこのパラメーターの値として使用できます。 Web アプリケーションにインターネットゾーンの代替アクセスマッピング (AAM) がある場合、その AAM の URL をこのパラメーターに使用する必要があります。 SharePoint Web アプリケーションが HTTPS 対応で構成されていない場合は、HTTP をプロトコルとして使用し、-AllowOverHttp スイッチを使用する必要があります (この表の下部を参照)。 ACS を使用するプロバイダー向けのホスト型アドインを、ファーム内のより多くの Web アプリケーションで実行するには、それらのアドインをサービスプリンシパル名コレクションに追加する必要があります。次に示す Windows PowerShell スクリプトの `Connect-SPFarmToAAD` 関数に続く部分に、ファームのすべての Web アプリケーションをサービスプリンシパル名コレクションに追加する方法を示します。
`-AllowOverHttp` (省略可能)	開発環境で作業していて、アドインに SSL を使用しない場合は、このスイッチを使用します。SharePoint Web アプリケーションが HTTPS 対応で構成されていない場合は、このスイッチを使用する必要があります。
`-O365Credentials` (省略可能)	最初の文字はゼロではなく大文字の "O" です。デバッグ目的でスクリプトを繰り返し実行している場合は、このスイッチを使用すると、O365 の名前とパスワードを毎回手動で入力しなくても済みます。このパラメーターを使用する前に、次のコマンドレットを使用して、パラメーターに割り当てる資格情報オブジェクトを作成する必要があります。`$User = "username@yourcustomdomain.onmicrosoft.com"$PWord = ConvertTo-SecureString -String "the_password" -AsPlainText -Force$Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $User, $PWord` パラメーターの値としてを`-O365Credentials`使用`$Credential`します。
`-Verbose` (省略可能)	このスイッチは、関数が動作せず、デバッグ目的で再実行する必要がある場合に役立つ、より詳細なフィードバックを生成します。
`-RemoveExistingACS` (省略可能)	Azure Active Directory への既存の接続を置き換える場合、このスイッチを使用します。ファームで既に ACS プロキシを作成していた場合、既存の ACS プロキシは削除されます。
`-RemoveExistingSTS` (省略可能)	Azure Active Directory への既存の接続を置き換える場合、このスイッチを使用します。 ACS への以前の接続で残った、信頼されたセキュリティトークンの既存の発行元が削除されます。
`-RemoveExistingSPOProxy` (省略可能)	Azure Active Directory への既存の接続を置き換える場合、このスイッチを使用します。ファームで既にアドイン管理プロキシを作成していた場合、既存のアドイン管理プロキシは削除されます。
`-RemoveExistingAADCredentials` (省略可能)	Office 365 SharePoint サイトを置き換える場合、このスイッチを使用します。

次に、例を示します。

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

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
    }  
}

アドインおよび SharePoint Web アプリケーションを Office ストア用に構成する

ファーム管理者は、ACS を使用するプロバイダー向けのホスト型アドインをユーザーが Office ストアからインストールできるようにしたい場合、以下のオプション構成手順を運用環境で実行する必要があります。 (ACS を使用するアドインをストアからその環境にインストールする予定があるのでない限り、この手順は SharePoint 開発環境には必要ありません。) 次のコマンドレットでこれを実現できます。このコードは前述の関数に追加できます。

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

また、運用環境の SharePoint Web アプリケーションでは、上記の構成手順の完了後に、[アクセスできるインターネット接続エンドポイントが必要なアドイン] 機能をアクティブにすることをお勧めします。 (下記の指示を参照。) この機能では、実際には何も行われません。これは、ACS を使用するプロバイダー向けのホスト型アドインを SharePoint Web アプリケーションの Web サイトにインストールできることを、Office ストアに通知するフラグとしてのみ機能します。

このシステムは、使用する SharePoint アドインのアドインマニフェストに影響を与える場合があります。ストアを通じたアドインの販売を計画する場合、アドインマニフェストの AppPrerequisites セクションに次の AppPrerequisite を追加することをお勧めします。

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

この前提条件を追加すると、ユーザーがオンプレミスの SharePoint ファームからストアを閲覧した際に、親 SharePoint Web アプリケーションで [アクセスできるインターネット接続エンドポイントが必要なアドイン] 機能が有効になっていない場合、アドインは淡色表示され、インストールできなくなります。このようにすると、オンプレミスの SharePoint Web サイトに顧客がインストールしたアドインが機能しないという問題を回避できます。

この機能を有効にする方法は 2 つあります。最初の方法は、次の PowerShell コマンドレット (先行する関数の末尾に追加できます) を任意の SharePoint サーバーで実行する方法です。

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

この機能を有効にするもう 1 つの方法は、サーバーの全体管理で次の手順を実行することです。

[SharePoint サーバーの全体管理] で [アプリケーション管理]>[Web アプリケーション機能の管理] に移動します。
[Web アプリケーション機能の管理] ページで、変更する Web アプリケーションを選択します。
リボンで [機能の管理] を選択します。
[アクセスできるインターネット接続エンドポイントが必要なアドイン] の横にある機能リストから、[アクティブ化] を選択します。
[OK] を選択します。

ファーム内でその他の SharePoint Web アプリケーションを構成する

SharePoint ファームに追加の Web アプリケーションがあり、それらで ACS の信頼を使用するプロバイダーでホストされるアドインを実行する場合は、この Windows PowerShell スクリプトを SharePoint 管理シェルで使用して、サービスプリンシパル名コレクションに追加できます。

$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
    }
}