Uso de ACS para autorizar complementos hospedados por un proveedor de confianza bajo en un sitio local de SharePoint

  • Artículo

Requisitos previos

Asegúrese de que dispone de lo siguiente:

Importante

La retirada de ACS en el lado de Azure Active Directory no afecta a esta funcionalidad de SharePoint. Obtenga más información en el siguiente artículo: Impacto de la baja de Azure Access Control para complementos de SharePoint.

Configurar la instalación local de SharePoint para usar ACS

En la ilustración siguiente se muestran los cuatro pasos para habilitar las conexiones que se necesitan en la arquitectura general de un complemento hospedado por el proveedor que se ejecuta en un sitio local. También muestra el flujo de tokens de OAuth cuando el complemento está en ejecución.

Hacer que ACS funcione con una instalación local de SharePoint mediante un sitio de Office 365 SharePoint

Hacer que ACS funcione con una instalación local de SharePoint mediante un sitio de Office 365

  1. Cree un proxy de ACS en la granja de servidores de SharePoint local.

  2. Instale el certificado de firma del servidor local en su arrendamiento de Office 365.

  3. Agregue los nombres de dominio completos de los sitios en la granja de servidores de SharePoint donde desea ejecutar complementos a la colección de nombres principal del servicio en su arrendamiento de Office 365.

  4. Cree un proxy de administración de complementos en su granja de SharePoint.

La siguiente función realiza todo el trabajo necesario para configurar el sitio de SharePoint local para usar ACS. También puede usar esta función para realizar varias tareas de limpieza si quiere quitar configuraciones anteriores. Hay diversas formas de ejecutar la función en PowerShell. Este es un método.

Para configurar la instalación local de SharePoint para usar ACS

  1. En el servidor de SharePoint local, copie el código de la función Connect-SPFarmToAAD (disponible a continuación) en un archivo de texto denominado MySharePointFunctions.psm1 y guárdelo en una u otra de las carpetas siguientes (no en ambas). Puede que tenga que crear partes de la ruta de acceso, si incluye carpetas que aún no existen. Observe que, en ambos casos, la última carpeta de la ruta de acceso ha de tener el mismo nombre que el archivo.

    Sugerencia

    El archivo tiene que guardarse en formato ANSI, no UTF-8. Es posible que PowerShell genere errores de sintaxis cuando se carga un archivo con un formato distinto de ANSI. El Bloc de notas de Windows lo guarda como ANSI de manera predeterminada. Si usa algún otro editor para guardar el archivo, asegúrese de hacerlo como ANSI.

    • C:\users\username\documents\windowspowershell\modules\MySharePointFunctions, donde username es el administrador de granja que ejecuta el archivo.

    • C:\windows\system32\windowspowershell\V1.0\modules\MySharePointFunctions

  2. La función Connect-SPFarmToAAD requiere que el paquete NuGet MSOnlineExt funcione e instálelo con el cmdlet siguiente.

    Install-Module -Name MSOnlineExt

  3. Abra el Shell de administración de SharePoint como administrador y ejecute el siguiente cmdlet para comprobar que el módulo MySharePointFunctions aparece en la lista.

    Get-Module -listavailable

  4. Ejecute el siguiente cmdlet para importar el módulo.

    Import-Module MySharePointFunctions

  5. Ejecute el siguiente cmdlet para comprobar que la función Connect-SPFarmToAAD aparece en la lista como parte del módulo.

    Get-Command -module MySharePointFunctions

  6. Ejecute el siguiente cmdlet para comprobar que la función Connect-SPFarmToAAD se ha cargado.

    ls function:\ | where {$_.Name -eq "Connect-SPFarmToAAD"}

  7. Ejecute la función Connect-SPFarmToAAD. Asegúrese de proporcionar los parámetros obligatorios y cualquier parámetro opcional que se aplique a su entorno de desarrollo. Vea la siguiente sección para obtener información y ejemplos.

Parámetros de la función Connect-SPFarmToAAD

Parámetro Valor
-AADDomain

(obligatorio)		 Dominio *.onmicrosoft.com que creó al registrarse en su sitio de Office 365 (dominioPersonalizado.onmicrosoft.com). Cuando el script le pida que se autentique, use el nombre de usuario y la contraseña que creó para este dominio: nombreDeUsuario@dominioPersonalizado.onmicrosoft.com.
-SharePointOnlineUrl

(obligatorio)		 Dirección URL del sitio de SharePoint Office 365 (_https://yourcustomdomain_.sharepoint.com). Tenga en cuenta que el dominio primario no es onmicrosoft.com.
-SharePointWeb

(obligatorio a veces)		 Dirección URL completa (incluido el protocolo) de la aplicación web de SharePoint local donde se ejecutarán los complementos hospedados por el proveedor. Esta función solo agrega una aplicación web de SharePoint de la granja local en ACS.

Si no se especifica un valor para ella, el script selecciona la primera aplicación web de la granja. Si usa una colección de sitios de nombres de host (HNSC) que se puede definir con comodín (por ejemplo, http://*.contoso.com), puede usar esa cadena como valor de este parámetro.

Si la aplicación web tiene una asignación de acceso alternativo (AAM) para la zona de Internet, debe usar la dirección URL de AAM con este parámetro. Si la aplicación web de SharePoint no está configurada para HTTPS, debe usar HTTP como protocolo y tiene que utilizar el modificador -AllowOverHttp (vea más adelante en esta tabla).

Si quiere ejecutar complementos hospedados por el proveedor que usan ACS en otras aplicaciones web de la granja, tiene que agregarlas a la colección de nombres de entidad de seguridad de servicio.

El script de Windows PowerShell que sigue a la función Connect-SPFarmToAAD muestra cómo agregar todas las aplicaciones web de la granja a la colección de nombres de entidad de seguridad de servicio.
-AllowOverHttp

(opcional)		 Use este modificador si está trabajando con un entorno de desarrollo y no desea usar SSL con los complementos. Debe usar este modificador si la aplicación web de SharePoint no está configurada para HTTPS.
-O365Credentials

(opcional)		 El primer carácter es una letra "O" mayúscula, no un cero. Si tiene que ejecutar varias veces el script con fines de depuración, este modificador le evita tener que escribir manualmente el nombre y la contraseña de O365 cada vez.

Para poder usar este parámetro, debe crear el objeto de credenciales que le va a asignar con estos 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 valor del -O365Credentials parámetro .
-Verbose

(opcional)		 Este modificador genera comentarios más detallados, lo que podría resultar útil si la función no funciona y tiene que volver a ejecutarla para la depuración.
-RemoveExistingACS

(opcional)		 Use este modificador si quiere reemplazar una conexión existente con Azure Active Directory. Quita un proxy de ACS existente si ya ha creado uno en la granja.
-RemoveExistingSTS

(opcional)		 Use este modificador si quiere reemplazar una conexión existente con Azure Active Directory. Quita un emisor de tokens de seguridad de confianza existente que queda de una conexión anterior con ACS.
-RemoveExistingSPOProxy

(opcional)		 Use este modificador si quiere reemplazar una conexión existente con Azure Active Directory. Quita un proxy de administración de complementos existente si ya ha creado uno en la granja.
-RemoveExistingAADCredentials

(opcional)		 Use este modificador si quiere reemplazar el sitio de Office 365 SharePoint.

Estos son algunos ejemplos:

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

Contenido 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 el complemento y la aplicación web de SharePoint para la Tienda Office

Existe un paso de configuración opcional que los administradores de granjas de servidores deben llevar a cabo en entornos de producción si quieren que los usuarios puedan instalar complementos hospedados por el proveedor que usen ACS desde la Tienda Office. (No tiene ninguna utilidad en el entorno de desarrollo de SharePoint, a menos que planee instalar complementos que usen ACS desde la tienda en ese entorno). El siguiente cmdlet lo hace posible. Este código puede agregarse a la función anterior.

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

También se recomienda hacerlo en aplicaciones web de SharePoint de producción para activar la característica Add-ins that require accessible internet facing endpoints (Complementos que necesitan puntos de conexión accesibles desde Internet) una vez completados los pasos de configuración. (Vea las siguientes instrucciones). Esta característica no hace nada en realidad. Simplemente actúa como marca que indica a la Tienda Office que los complementos hospedados por el proveedor que usan ACS pueden instalarse en sitios web de la aplicación web de SharePoint.

Este sistema puede tener implicaciones para el manifiesto de complemento del complemento de SharePoint. Si piensa vender el complemento a través de la tienda, se recomienda agregar el siguiente elemento AppPrerequisite a la sección AppPrerequisites del manifiesto de complemento:

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

El efecto del requisito previo es que, cuando los usuarios exploren la tienda desde una granja de SharePoint local, el complemento se mostrará atenuado y no se podrá instalar si la aplicación web primaria de SharePoint no tiene habilitada la característica Add-ins that require accessible internet facing endpoints (Complementos que necesitan puntos de conexión accesibles desde Internet). Así se asegura de que no recibirá quejas por parte de los clientes que instalen el complemento en un sitio web de SharePoint local y vean que no funciona.

Hay dos formas de habilitar la característica. La primera consiste en ejecutar el siguiente cmdlet de PowerShell (que se puede agregar al final de la función anterior) en cualquier servidor de SharePoint:

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

La otra forma de habilitar la característica es completar estos pasos en Administración central:

  1. En Administración central de SharePoint, vaya a Administración de aplicaciones>Administrar aplicaciones web.

  2. En la página Administrar aplicaciones web, seleccione la aplicación web que quiere cambiar.

  3. En la cinta, seleccione Administrar características.

  4. En la lista de características, junto a Add-ins that require accessible internet facing endpoints (Complementos que necesitan puntos de conexión accesibles desde Internet), seleccione Activar.

  5. Seleccione Aceptar.

Configurar otras aplicaciones web de SharePoint en la granja

Si tiene aplicaciones web adicionales en la granja de servidores de SharePoint y desea ejecutar complementos hospedados por el proveedor que usan confianza de ACS en ellos, puede usar este script de Windows PowerShell (en Shell de administración de SharePoint) para agregarlos a la colección de nombres principales de servicio.

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

Ver también