Compartir a través de

Scripts de configuración de nivel de confianza alto para SharePoint

  • Artículo

Se usan los siguientes scripts designar uno o más certificados digitales X.509 como emisores de confianza de tokens de acceso en una granja de Microsoft SharePoint de almacenamiento provisional o de producción. Para buscar un script que sea más adecuado para un entorno de desarrollo de complementos de SharePoint, vea Crear complementos de SharePoint de elevada confianza. Ningún conjunto único de scripts puede funcionar con todas las granjas de SharePoint porque hay muchas formas de adquirir y almacenar los certificados. Por ello, tenga en cuenta lo siguiente:

  • Los scripts están diseñados para ejecutarse en el Shell de administración de SharePoint o en cualquier servidor de SharePoint de la granja.

  • Piense en estos scripts como borradores que es necesario personalizar.

  • Se utilizan como parte del proceso general de publicación de un complemento de SharePoint de elevada confianza. Solo deben usarlos quienes estén familiarizados con los temas Crear complementos de SharePoint que usan la autorización de elevada confianza y Empaquetar y publicar complementos de elevada confianza para SharePoint y los requisitos previos correspondientes.

  • Es necesario que alguien familiarizado con las directivas de certificados del cliente en relación con los complementos revise y personalice los scripts.

  • En los dos scripts principales que aparecen a continuación, HighTrustConfig-ForSharedCertificate.ps1 y HighTrustConfig-ForSingleApp.ps1, se da por hecho que un administrador ha adquirido un certificado para el componente de la aplicación web remota del complemento o los complementos, y que ha almacenado temporalmente una versión .cer del certificado (que no contiene la clave privada) en una carpeta en donde las cuentas de usuario de los siguientes grupos de aplicaciones IIS de los servidores de SharePoint tienen acceso de lectura:

    • SecurityTokenServiceApplicationPool

    • Grupo de complementos que ofrece el sitio web de IIS donde se hospeda la aplicación web del sitio primario de SharePoint para el sitio web de prueba de SharePoint. En el sitio web de IIS SharePoint - 80, el grupo se denomina OServerPortalAppPool.

      Para buscar la cuenta de usuario que un grupo de aplicaciones usa, abra el Administrador de IIS en un servidor de SharePoint y haga doble clic en Grupos de aplicaciones en el panel Conexiones. La columna Identidad de la lista Grupos de aplicaciones que se abre muestra a los usuarios los grupos de aplicaciones.

  • En las instrucciones para los dos scripts principales se presupone también que los certificados se han instalado en IIS en los servidores que hospedan las aplicaciones web remotas. Para obtener las instrucciones, vea Configurar el servidor web remoto con el certificado.

Vea las notas específicas sobre el uso de cada script en las secciones siguientes.

AddSPRootAuthority.ps1

El certificado del componente de la aplicación web remota del complemento de SharePoint de elevada confianza se obtiene de una entidad de certificación (CA) comercial o de una CA de dominio. En cualquier caso, el certificado es el vínculo más bajo de una cadena de certificados, donde cada uno confía en el anterior, que se origina con una entidad de certificación raíz (comercial o de dominio). SharePoint requiere que todos los certificados de la cadena se agreguen a la lista de entidades de certificación raíz de SharePoint.

Puede usar el script siguiente para agregar a la lista cada certificado de la cadena excepto el más bajo. El certificado más bajo de la cadena, el certificado que está enlazado directamente a la aplicación web remota, se agrega a las entidades de certificación raíz en uno de los principales scripts que se describen en secciones posteriores.

Estos son los parámetros para el script:

Parámetro Valor
-CertPath Ruta de acceso completa y nombre de archivo del certificado (archivo .cer).
-CertName El nombre del certificado. Para consultar el nombre, vea las propiedades del certificado.

Por ejemplo, en el escenario común donde el certificado de la aplicación web lo emite un servidor de CA intermedio (también denominado "empresarial") y su certificado, a su vez, lo emite un servidor de CA raíz (también denominado "independiente"), el script se debe ejecutar una vez para cada uno de los certificados de los dos servidores de CA. A continuación ilustramos esto:

./AddSPRootAuthority.ps1 -CertPath "\\CertStorage\RootCA.cer" -CertName "Contoso Root CA"

./AddSPRootAuthority.ps1 -CertPath "C:\RegionalCerts\NorthRegion.cer" -CertName "North Region Intermediate CA"

Si todos los certificados de los complementos de SharePoint de elevada confianza del cliente provienen de la misma cadena de certificados, como ocurriría normalmente, este script no se volverá a usar.

Este es el código del script. Solo tiene que pegarlo en un editor de texto o en el editor de PowerShell (IPowerShell ISE) y guardarlo como AddSPRootAuthority.ps1.

Nota:

El archivo tiene que guardarse en formato ANSI, no UTF-8. PowerShell puede producir errores de sintaxis cuando se ejecuta un archivo con un formato distinto de ANSI. El Bloc de notas y el editor de PowerShell lo guardan de forma predeterminada como ANSI. Si usa algún otro editor para guardar el archivo, asegúrese de hacerlo como ANSI.

param(
  [Parameter(Mandatory)][String] $CertName = $(throw "Usage: AddSPRootAuthority.ps1 -CertPath <full path to .cer file> -CertName <name of certificate>"),
  [Parameter(Mandatory)][String] $CertPath
)
# Stop if there's an error
$ErrorActionPreference = "Stop"

# Make the certificate a trusted root authority in SharePoint
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)
New-SPTrustedRootAuthority -Name $CertName -Certificate $cert

HighTrustConfig-ForSharedCertificate.ps1

La principal tarea de este script es registrar el certificado compartido de los componentes de la aplicación web remota en varios complementos de SharePoint de elevada confianza con SharePoint como entidad de certificación raíz y como emisor de tokens de acceso de confianza. Este script no se usa si el cliente utiliza distintos certificados con cada complemento de SharePoint de elevada confianza. Para ese escenario, vea HighTrustConfig-ForSingleApp.ps1. Si todos los complementos usan el mismo certificado, este script se ejecuta una sola vez. Si algunos conjuntos de complementos usan un certificado distinto de otros conjuntos, este script se ejecuta una vez para cada conjunto.

En la tabla siguiente se describen los parámetros y los modificadores del script. La personalización del script puede introducir cambios en esta tabla.

Parámetro Valor
-CertPath (obligatorio) La ruta de acceso completa al archivo *.cer compartido.
-CertName (obligatorio) Nombre del certificado compartido. Para buscar el nombre, abra IIS en el servidor web remoto que hospeda la aplicación web remota. Resalte el nodo nombreDeServidor y haga doble clic en Certificados. El certificado se muestra en la lista por su nombre.
-TokenIssuerFriendlyName
(opcional)		 Nombre descriptivo y único para el emisor de tokens, hasta 50 caracteres. Esto puede resultar útil si va a depurar problemas con emisores de tokens.

El nombre debe ser único. La inclusión de un GUID garantizaría que fuera único, pero un GUID usa hasta 32 de los 50 caracteres, por lo que se recomienda convertir un GUID en una cadena de Base 64 que se pueda reducir a 22 caracteres.

Si no se usa este parámetro, el script usará el nombre High-Trust Add-ins <base64 version of issuer GUID>.

Este es un ejemplo de cómo ejecutar el script.

./HighTrustConfig-ForSharedCertificate.ps1 -CertPath "C:\Certs\MyCert.cer" -CertName "My Cert" -TokenIssuerFriendlyName "SharePoint High-Trust Add-ins Token Issuer"

Importante

El registro del certificado como emisor de tokens no surte efecto inmediatamente. Puede tardar hasta 24 horas antes de que todos los servidores de SharePoint reconozcan al nuevo emisor de tokens. La ejecución de un iisreset en todos los servidores de SharePoint haría que reconozcan inmediatamente al emisor, si puede hacerlo sin molestar a los usuarios de SharePoint.

Inicie un nuevo archivo en un editor de texto o en el editor de PowerShell y copie lo siguiente en un archivo de texto y guárdelo como HighTrustConfig-ForSharedCertificate.ps1. Use formato ANSI, no UTF-8.

param(
  [Parameter(Mandatory)][String] $CertPath = $(throw "Usage: HighTrustConfig-ForSharedCertificate.ps1 -CertPath <full path to .cer file> -CertName <name of certificate> [-TokenIssuerFriendlyName <friendly name>]"),
  [Parameter(Mandatory)][String] $CertName,
  [Parameter()][String] $TokenIssuerFriendlyName
)
# Stop if there's an error
$ErrorActionPreference = "Stop"

# Ensure friendly name is short enough
if ($TokenIssuerFriendlyName.Length -gt 50)
{
  throw "-TokenIssuerFriendlyName must be unique name of no more than 50 characters."
}

# Get the certificate
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)

# Make the certificate a trusted root authority in SharePoint
New-SPTrustedRootAuthority -Name $CertName -Certificate $certificate

# Get the GUID of the authentication realm
$realm = Get-SPAuthenticationRealm

# Generate a unique specific issuer ID
$specificIssuerId = [System.Guid]::NewGuid().ToString()

# Create full issuer ID in the required format
$fullIssuerIdentifier = $specificIssuerId + '@' + $realm

# Create issuer name
if ($TokenIssuerFriendlyName.Length -ne 0)
{
  $tokenIssuerName = $TokenIssuerFriendlyName
}
else
{
  $tokenIssuerName = "High-Trust Add-ins " + [System.Convert]::ToBase64String($specificIssuerId.ToByteArray()).TrimEnd('=')
}

# Register the token issuer
New-SPTrustedSecurityTokenIssuer -Name $tokenIssuerName -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker

# Output the specific issuer ID to a file in the same folder as this script. The file should be given to the developer of the high-trust SharePoint Add-in.
$specificIssuerId  | Out-File -FilePath "SecureTokenIssuerID.txt"

Sugerencia

Si el script genera un error después de haberse ejecutado correctamente la línea New-SPTrustedRootAuthority, no se puede volver a ejecutar el script hasta que se haya quitado el objeto. Utilice el cmdlet siguiente, donde el valor del parámetro -Identity es el mismo que se usó para el parámetro -CertName del script: Remove-SPTrustedRootAuthority -Identity <certificate name>

Si por algún motivo hay que quitar el emisor de tokens, use el siguiente cmdlet: Remove-SPTrustedSecurityTokenIssuer -Identity <issuer name>

Si se usó el parámetro -TokenIssuerFriendlyName, use el mismo valor para -Identity.

Si no se usó el parámetro -TokenIssuerFriendlyName, un GUID aleatorio forma parte del nombre del emisor. Para obtener el valor necesario para -Identity, ejecute el siguiente cmdlet. Abra el archivo TokenIssuers.txt que se ha producido y busque emisor cuyo nombre es High-Trust Add-ins <base64 version of issuer GUID>. Use ese nombre completo para -Identity.

Get-SPTrustedSecurityTokenIssuer | Out-File -FilePath "TokenIssuers.txt"

HighTrustConfig-ForSingleApp.ps1

La principal tarea de este script es registrar el certificado de la aplicación web remota en un complemento de SharePoint de elevada confianza con SharePoint como entidad de certificación raíz y como emisor de tokens de acceso de confianza. Este script no se usa si el cliente usa un solo certificado para varios complementos de SharePoint. Para ese escenario, vea HighTrustConfig-ForSharedCertificate.ps1. Este script se ejecuta para cada complemento de SharePoint de elevada confianza.

En la tabla siguiente se describen los parámetros y los modificadores del script. La personalización del script puede introducir cambios en esta tabla.

Parámetro Valor
-CertPath (obligatorio) La ruta de acceso completa al archivo *.cer compartido.
-CertName (obligatorio) Nombre del certificado compartido. Para buscar el nombre, abra IIS en el servidor web remoto que hospeda la aplicación web remota. Resalte el nodo nombreDeServidor y haga doble clic en Certificados. El certificado se muestra en la lista por su nombre.
-SPAppClientID (obligatorio) Identificador de cliente (GUID) que se usó al registrar el complemento de SharePoint en appregnew.aspx.
Se utiliza como identificador del emisor para el emisor de tokens. El script se asegura de que esté en minúsculas, que es un requisito para los identificadores del emisor.
-TokenIssuerFriendlyName
(opcional)		 Nombre descriptivo y único para el emisor de tokens, hasta 50 caracteres. Esto puede resultar útil si va a depurar problemas con emisores de tokens.
El nombre debe ser único. Plantéese la posibilidad de usar el nombre del complemento de SharePoint. Si no se usa este parámetro, el script usará el valor de -SPAppClientID.

Este es un ejemplo de cómo llamar al script:

./HighTrustConfig-ForSingleApp.ps1 -CertPath "\\MyServer\Certs\MyCert.cer" -CertName "My Cert" -SPAppClientID "afe332f4-1f87-4c31-89b8-9c343ad7f24e" -TokenIssuerFriendlyName "Payroll add-in"

Importante

El registro del certificado como emisor de tokens no surte efecto inmediatamente. Pueden pasar 24 horas antes de que todos los servidores de SharePoint reconozcan al nuevo emisor de tokens. Ejecute un iisreset en todos los servidores de SharePoint para que reconozcan inmediatamente al emisor (si puede hacerlo sin interrumpir a los usuarios de SharePoint).

Inicie un nuevo archivo en un editor de texto o en el editor de PowerShell y copie lo siguiente en un archivo de texto y guárdelo como HighTrustConfig-ForSingleApp.ps1. Use formato ANSI, no UTF-8.

param(
  [Parameter(Mandatory)][String] $CertPath = $(throw "Usage: HighTrustConfig-ForSingleApp.ps1 -CertPath <full path to .cer file> -CertName <name of certificate> [-SPAppClientID <client ID of SharePoint add-in>] [-TokenIssuerFriendlyName <friendly name>]"),
  [Parameter(Mandatory)][String] $CertName,
  [Parameter(Mandatory)][String] $SPAppClientID,
  [Parameter()][String] $TokenIssuerFriendlyName
)
# Stop if there's an error
$ErrorActionPreference = "Stop"

# Ensure friendly name is short enough
if ($TokenIssuerFriendlyName.Length -gt 50)
{
  throw "-TokenIssuerFriendlyName must be unique name of no more than 50 characters."
}

# Get the certificate
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)

# Make the certificate a trusted root authority in SharePoint
New-SPTrustedRootAuthority -Name $CertName -Certificate $certificate

# Get the GUID of the authentication realm
$realm = Get-SPAuthenticationRealm

# Must use the client ID as the specific issuer ID. Must be lower-case!
$specificIssuerId = New-Object System.String($SPAppClientID).ToLower()

# Create full issuer ID in the required format
$fullIssuerIdentifier = $specificIssuerId + '@' + $realm

# Create issuer name
if ($TokenIssuerFriendlyName.Length -ne 0)
{
  $tokenIssuerName = $TokenIssuerFriendlyName
}
else
{
  $tokenIssuerName = $specificIssuerId
}

# Register the token issuer
New-SPTrustedSecurityTokenIssuer -Name $tokenIssuerName -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier

Sugerencia

Las sugerencias que encontrará al final de la sección anterior también son válidas aquí; pero, para el parámetro -Identity del cmdlet Remove-SPTrustedSecurityTokenIssuer, utilice el identificador de cliente si no se usó el parámetro -TokenIssuerFriendlyName con HighTrustConfig-ForSingleApp.ps1.

Modificaciones necesarias para las suscripciones de sitio

Una suscripción de sitio, en ocasiones denominada espacio empresarial, es un subconjunto de las colecciones de sitios de una granja de SharePoint. Las suscripciones de sitio suelen crearse en granjas de SharePoint hospedadas. Si el cliente del complemento de SharePoint de elevada confianza quiere instalar el complemento en una granja que se ha configurado para suscripciones de sitio, hay que modificar cualquiera de los dos scripts HighTrustConfig-*.ps1 que se use.

Cada suscripción de sitio tiene su propio identificador de dominio kerberos, pero la línea $realm = Get-SPAuthenticationRealm de los scripts siempre devuelve el dominio kerberos de la granja. SharePoint solo considera válidos los tokens de acceso emitidos por un emisor de tokens para el dominio kerberos que se especifiquen después del carácter "@" en el identificador completo del emisor.

Para obtener el dominio kerberos correcto para el sitio web en el que se va a instalar el complemento, el script tiene que usar el parámetro -ServiceContext en la llamada a Get-SPAuthenticationRealm. El objeto de contexto de servicio, a su vez, se crea en la colección de sitios primaria del sitio web de destino.

Este es un ejemplo, donde $WebURL es una variable de cadena con la dirección URL completa de un sitio web de SharePoint, como, por ejemplo, http://marketing.contoso.com/sites/northteam/july. Este código permite que el complemento de elevada confianza se ejecute, no solo en el sitio web especificado, sino en todos los sitios web incluidos en la misma suscripción de sitio.

$Web = Get-SPWeb $WebURL
$sc = Get-SPServiceContext -Site $Web.Site
$realm = Get-SPAuthenticationRealm -ServiceContext $sc

Para completar la modificación del script, agregue un parámetro adicional necesario $WebURL a la lista de parámetros del principio del archivo, como se ve a continuación:

param (
  # other parameters omitted
  [Parameter()][String] $WebURL
)

No se olvide de poner una coma después del parámetro que precede al nuevo parámetro. Expanda el ejemplo "Usage" de la primera línea para que tenga en cuenta el nuevo parámetro, con algo así:

-WebURL <full URL where SP add-in will be installed>

Para que el complemento de SharePoint sea de confianza en todas las suscripciones de sitio, obtenga una referencia a la granja con el cmdlet Get-SPFarm y luego itérela en su propiedad SiteSubscriptions. Pase cada objeto SPSiteSubscription al cmdlet Get-SPServiceContext como valor del parámetro -SiteSubscription. Este es un ejemplo.

$Farm = Get-SPFarm
foreach ($ss in $Farm.SiteSubscriptions)
{
  $sc = Get-SPServiceContext -SiteSubscription $ss
  $realm = Get-SPAuthenticationRealm -ServiceContext $sc

  # All of the lines from the draft script below the call to
  # Get-SPAuthenticationRealm are inserted here inside the loop.
}
# end of script

Ver también