Usar o ACS para autorizar suplementos hospedados pelo provedor de baixa confiança em um site local do SharePoint

Artigo
04/08/2023

Pré-requisitos

Verifique se você tem o seguinte:

Um ambiente de desenvolvimento do SharePoint no local. Confira Configurar um ambiente de desenvolvimento local para Suplementos do SharePoint.
Um Office 365 site do SharePoint. Se ainda não tiver um e quiser configurar um ambiente de desenvolvimento rapidamente, você poderá configurar um ambiente de desenvolvimento para suplementos do SharePoint em Office 365.
O Visual Studio foi instalado remotamente ou em um computador que executa o SharePoint, com a carga de trabalho de desenvolvimento do Office/SharePoint. Versões anteriores do Visual Studio exigem o componente Ferramentas de Desenvolvedor do Microsoft Office para Visual Studio . A versão mais recente deste componente está disponível aqui para Visual Studio 2013 e aqui para Visual Studio 2015.

Importante

A desativação do ACS do lado do Azure Active Directory não afeta essa funcionalidade no SharePoint. Veja mais detalhes no seguinte artigo: Impacto da desativação do Controle de Acesso do Azure para os Suplementos do SharePoint.

Configurar a instalação local do SharePoint para usar o ACS

A figura a seguir mostra as quatro etapas para a habilitação das conexões que você precisa dentro da arquitetura geral de um suplemento hospedado pelo provedor que é executado em um site local. Ela também mostra o fluxo de tokens OAuth quando o suplemento está sendo executado.

Fazer o ACS trabalhar com uma instalação local do SharePoint usando um site do SharePoint do Office 365

Fazer o ACS trabalhar com uma instalação local do SharePoint usando um site do SharePoint do Office 365

Crie um proxy de ACS no farm do SharePoint local.
Instale o certificado de autenticação do servidor local em sua locação do Office 365.
Adicione os nomes de domínio totalmente qualificado dos sites no farm do SharePoint em que você deseja executar suplementos ao conjunto de UPNs do serviço na sua locação do Office 365.
Crie um proxy de gerenciamento de suplemento no farm do SharePoint.

A seguinte função faz todo o trabalho para configurar seu site do SharePoint local para usar o ACS. Você também poderá usar essa função para realizar algumas tarefas de limpeza, se precisar remover configurações anteriores. Há várias maneiras de executar a função no PowerShell. Veja a seguir um método.

Para configurar seu site local do SharePoint para usar o ACS

No servidor local do SharePoint, copie o código da função Connect-SPFarmToAAD (disponível abaixo) em um arquivo de texto chamado MySharePointFunctions.psm1 e salve-o em uma ou outra das pastas a seguir (não em ambas). Talvez, você tenha que criar partes do caminho, se ele incluir pastas que ainda não existam. Em ambos os casos, a menor pasta no caminho deve ter o mesmo nome do arquivo.

Dica

O arquivo deve ser salvo no formato ANSI, não UTF-8. O PowerShell pode exibir erros de sintaxe ao carregar um arquivo com um formato não ANSI. Por padrão, o Bloco de Notas do Windows salva os arquivos como ANSI. Se você usar qualquer outro editor para salvar o arquivo, salve-o como ANSI.
- C:\users\username\documents\windowspowershell\modules\MySharePointFunctions, em que nomedeusuário é o administrador do farm que está executando o arquivo.
- C:\windows\system32\windowspowershell\V1.0\modules\MySharePointFunctions
A função Connect-SPFarmToAAD requer que o pacote NuGet MSOnlineExt funcione, instale-o com o cmdlet abaixo.
```
Install-Module -Name MSOnlineExt
```
Abra o Shell de Gerenciamento do SharePoint como administrador e execute o cmdlet a seguir para confirmar que o módulo MySharePointFunctions está listado.
```
Get-Module -listavailable
```
Execute o cmdlet a seguir para importar o módulo.
```
Import-Module MySharePointFunctions
```
Execute o cmdlet a seguir para confirmar que a função Connect-SPFarmToAAD está listada como parte do módulo.
```
Get-Command -module MySharePointFunctions
```
Execute o cmdlet a seguir para confirmar que a função Connect-SPFarmToAAD está carregada.
```
ls function:\ | where {$_.Name -eq "Connect-SPFarmToAAD"}
```
Execute a função Connect-SPFarmToAAD. Forneça os parâmetros necessários e eventuais parâmetros opcionais que se aplicam ao seu ambiente de desenvolvedor Confira a próxima seção para obter detalhes e exemplos.

Parâmetros da função Connect-SPFarmToAAD

Parâmetro	Valor
`-AADDomain` (obrigatório)	O domínio .onmicrosoft.com que você criou quando se inscreveu no seu site do Office 365 (seudomíniopersonalizado.onmicrosoft.com). Quando o script solicitar a autenticação, use o nome e a senha do domínio: nomedeusuário@seudomíniopersonalizado*.onmicrosoft.com.
`-SharePointOnlineUrl` (obrigatório)	A URL do seu Office 365 site do SharePoint (`_https://yourcustomdomain_.sharepoint.com`). O domínio pai não é onmicrosoft.com.
`-SharePointWeb` (às vezes obrigatório)	A URL completa (incluindo o protocolo) do aplicativo web do SharePoint local onde você executará os suplementos hospedados pelo provedor. Essa função adiciona apenas um aplicativo web do SharePoint do seu farm local ao ACS. Se você não especificar um valor para isso, o script selecionará o primeiro aplicativo web no seu farm. Se você estiver usando um Conjunto de Site Nomeado por Host (HNSC) que possa ser definido com um curinga (como http://.contoso.com), poderá usar essa cadeia de caracteres como o valor para esse parâmetro. Se o aplicativo web tiver um mapeamento de acesso alternativo (AAM) para a zona da Internet, você deverá usar essa URL de AAM para esse parâmetro. Se o aplicativo web do SharePoint não estiver configurado para HTTPS, você terá que usar o HTTP como protocolo e terá que usar a opção -AllowOverHttp (veja mais adiante nesta tabela).* Se você deseja executar suplementos hospedados no provedor que usem o ACS em mais aplicativos da web no seu farm, precisa adicioná-los ao conjunto de nomes de entidade de serviço. O script do Windows PowerShell que segue a função `Connect-SPFarmToAAD` mostra como adicionar todos os aplicativos Web no seu farm ao conjunto de nomes de entidade de serviço.
`-AllowOverHttp` (opcional)	Use esta opção se você estiver trabalhando com um ambiente de desenvolvedor e não quiser usar SSL com seus suplementos. Você precisará usar essa opção se o aplicativo Web do SharePoint não estiver configurado para HTTPS.
`-O365Credentials` (opcional)	O primeiro caractere é um "O" maiúsculo, não um zero. Se você estiver executando o script repetidamente para fins de depuração, esta opção permite que você não tenha que inserir manualmente o seu nome e a sua senha do Office 365 toda vez. Para poder usar esse parâmetro, crie o objeto de credenciais que você atribuirá a ele com estes 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` Use `$Credential` como o valor do `-O365Credentials` parâmetro.
`-Verbose` (opcional)	Essa opção gera comentários mais detalhados que podem ajudá-lo se a função não estiver funcionando e você precisar executá-la novamente para depuração.
`-RemoveExistingACS` (opcional)	Use esta opção se estiver substituindo uma conexão existente com o Azure Active Directory. Ela removerá um proxy existente do ACS se você já tiver criado um no seu farm.
`-RemoveExistingSTS` (opcional)	Use esta opção se estiver substituindo uma conexão existente com o Azure Active Directory. Ela removerá um emissor de tokens de segurança existente deixado por uma conexão anterior para o ACS.
`-RemoveExistingSPOProxy` (opcional)	Use esta opção se estiver substituindo uma conexão existente com o Azure Active Directory. Ela removerá um proxy de gerenciamento de suplementos existente se você já tiver criado um no seu farm.
`-RemoveExistingAADCredentials` (opcional)	Use esta opção se você estiver substituindo o site do SharePoint do Office 365.

Estes são alguns exemplos:

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

Conteúdo 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
    }  
}

Configurar o suplemento e o aplicativo Web do SharePoint para a Office Store

Há uma etapa de configuração opcional que os administradores de farm deverão realizar em ambientes de produção se quiserem que os usuários possam instalar suplementos hospedados pelo provedor que usem o ACS da Office Store. Ela não tem nenhuma finalidade no seu ambiente de desenvolvimento do SharePoint, a menos que você pretenda instalar suplementos que usem o ACS da loja nesse ambiente. O seguinte cmdlet possibilita isso. Este código pode ser adicionado à função anterior.

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

Também é uma boa prática para a produção de aplicativos web do SharePoint ativar o recurso Suplementos que exigem pontos de extremidade acessíveis voltados à internet após a conclusão das etapas de configuração. Confira as instruções a seguir. Este recurso, na verdade, não faz nada. Ele serve apenas como um sinalizador que informa à Office Store que os suplementos hospedados no provedor que usam o ACS podem ser instalados em sites no aplicativo web do SharePoint.

Esse sistema pode ter implicações para o manifesto de suplemento do seu suplemento do SharePoint. Se você planeja vender o suplemento por meio da loja, é uma prática recomendada adicionar o seguinte AppPrerequiste à seção AppPrerequisites do manifesto de suplemento:

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

O efeito do pré-requisito é que, quando os usuários estiverem navegando na loja a partir de um farm local do SharePoint, o suplemento ficará esmaecido e desinstalável se o aplicativo Web pai do SharePoint não tiver o recurso Suplementos que exigem pontos de extremidade acessíveis voltados à Internet habilitado. Isso garante que você não terá reclamações de clientes que instalam o suplemento em um site local do SharePoint e percebem que ele não funciona.

Há duas maneiras de habilitar o recurso. A primeira é executando o seguinte cmdlet do PowerShell (que pode ser adicionado ao final da função anterior) em qualquer servidor do SharePoint:

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

A outra maneira de habilitar o recurso é executar as seguintes etapas na Administração Central:

Na Administração Central do SharePoint, navegue até Gerenciamento de Aplicativo>Gerenciar aplicativos Web.
Na página Gerenciar Aplicativos Web, selecione o aplicativo Web que deseja alterar.
Na faixa de opções, selecione Gerenciar Recursos.
Na lista de recursos, vá para Suplementos que necessitam de pontos de extremidade voltados para a internet , selecione Ativar.
Selecione OK.

Configurar os aplicativos Web adicionais do SharePoint no farm

Se você tiver aplicativos Web adicionais em seu farm do SharePoint e quiser executar suplementos hospedados pelo provedor que usam confiança ACS neles, poderá usar este script do Windows PowerShell (no Shell de Gerenciamento do SharePoint) para adicioná-los ao conjunto de UPNs do serviço.

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