Configurare le cassette postali del sito in SharePoint Server

Articolo
03/08/2023

SI APPLICA A: yes-img-13 2013 yes-img-16 2016 yes-img-19 2019 yes-img-se Subscription Edition no-img-sop SharePoint in Microsoft 365

In questo articolo viene illustrato come configurare le cassette postali del sito in SharePoint Server e Exchange Server. La funzionalità Cassette postali siti consente agli utenti di SharePoint Server di usufruire della posta elettronica team in un sito. Le cassette postali del sito inoltre offrono collegamenti a raccolte documenti di SharePoint in Microsoft Outlook, consentendo agli utenti di condividere file e messaggi di posta elettronica con altri membri di un team impegnati su un progetto congiunto.

Prima di iniziare

Prima di iniziare questa operazione, verificare le seguenti informazioni sui prerequisiti:

Le cassette postali del sito richiedono Exchange Server 2013 o versioni successive.
Sarà necessario disinstallare qualsiasi versione precedente di Servizi Web Exchange dai server di SharePoint.

Nota

[!NOTA] Potrebbe essere necessario verificare se è installata una versione precedente di Servizi Web Exchange. A tale scopo, eseguire lo script Check-SiteMailboxConfig indicato di seguito.
La funzionalità Cassette postali del sito richiede che la sincronizzazione dei profili utente sia configurata nella farm. Per informazioni su tale configurazione, vedere Pianificare profili utente e identità e Gestire la sincronizzazione dei profili utente in SharePoint Server.
Per la funzionalità Cassette postali siti è necessario che l'applicazione del servizio di gestione delle app sia configurata nella farm. Per informazioni sulla configurazione di questa applicazione, vedere New-SPAppManagementServiceApplication.
Secure Sockets Layer (SSL) configurato per la zona predefinita è un requisito per le applicazioni Web distribuite in scenari che supportano l'autenticazione da server a server e l'autenticazione delle app. Si tratta di uno scenario di questo tipo. Come prerequisito per la configurazione delle cassette postali del sito, il computer che esegue SharePoint Server deve avere SSL configurato. Per altre informazioni, vedere Creare applicazioni Web basate su attestazioni in SharePoint Server e seguire la procedura per creare una raccolta siti SSL e un certificato server.

Si noti che potrebbe essere necessario importare il certificato SSL Exchange Server da Exchange Server a SharePoint Server e da SharePoint Server a Exchange Server. Questa operazione è necessaria solo se il certificato non è considerato attendibile per gli endpoint API, ad esempio un certificato Self-SSL in un ambiente lab. Per importare un certificato SSL non attendibile in un nuovo server:

Aprire Internet Explorer e passare a Outlook Web App (se la distribuzione in SharePoint Server) o il sito di SharePoint SSL (se la distribuzione è su Exchange Server): https://<ExServerName>/owa o https://<SP_FQDN>.
Accettare per considerare attendibile il certificato facendo clic su Continua al sito Web.
Fare clic sulle info dell'errore del certificato in Internet Explorer accanto alla barra degli indirizzi, quindi fare clic su Visualizza certificati.
Selezionare Installa certificato e quindi selezionare Colloca tutti i certificati nel seguente archivio.
Selezionare la casella di controllo per visualizzare gli archivi fisici.
Installare il certificato nel computer locale autorità > di certificazione radice attendibili.
Per eseguire queste procedure, è necessario essere membri dei gruppi di amministratori di SharePoint e Exchange Server e avere Exchange Server operativo con le cassette postali degli utenti finali.
Una soluzione di backup di SharePoint non incorpora le cassette postali del sito di Exchange. Un amministratore di Exchange dovrà assicurarsi che vengano eseguiti backup appropriati delle cassette postali del sito.
Gli utenti che accedono ai file in una raccolta documenti di SharePoint da una cassetta postale del sito devono avere la raccolta documenti configurata come sito attendibile nel browser o verrà visualizzato un avviso che chiede all'utente se vuole considerare attendibile il file.

Configurare SharePoint per le cassette postali del sito in SharePoint Server

Il primo passaggio per la configurazione di Cassette postali del sito è installare l'API per i servizi Web di Exchange Server in ciascun server Web e applicazioni nella farm di SharePoint Server.

Installare l'API per servizi Web Exchange in SharePoint Server

Scaricare EWSManagedAPI.msi dall'Area download Microsoft e salvarlo in una cartella su ogni server Web e applicazioni.
Aprire una finestra di comando come amministratori e passare alla cartella in cui è stato salvato EWSManagedAPI.msi.

Eseguire il comando seguente:

msiexec /I EwsManagedApi.msi addlocal="ExchangeWebServicesApi_Feature"

Reimpostare IIS dalla riga di comando digitando IISReset.

Impostare il trust OAuth e le autorizzazioni per il servizio in SharePoint Server

Il passaggio successivo consiste nel copiare i due script seguenti. Il primo dovrebbe essere salvato come Set-SiteMailboxConfig.ps1 e il secondo come Check-SiteMailboxConfig.ps1.

Set-SiteMailboxConfig.ps1:

# .SYNOPSIS
#
# Set-SiteMailboxConfig helps configure Site Mailboxes for a SharePoint farm
#
# .DESCRIPTION
#
# Establishes trust with an Exchange Server, sets Site Mailbox settings and enables Site Mailboxes for a farm.
#
# .PARAMETER ExchangeSiteMailboxDomain
#
# The FQDN of the Exchange Organization where Site Mailboxes will be created
#
# .PARAMETER ExchangeAutodiscoverDomain
#
# [Optional] The FQDN of an Exchange Autodiscover Virtual Directory
#
# .PARAMETER WebApplicationUrl
#
# [Optional] The URL of a specific web application to configure. If not specified all Web Applications will be configured
#
# .PARAMETER Force
#
# [Optional] Indicate that the script should ignore any configuration issues and enable Site Mailboxes anyway
#
Param
(
   [Parameter(Mandatory=$true)]
   [ValidateNotNullOrEmpty()]   
   [string]$ExchangeSiteMailboxDomain,
   [Parameter(Mandatory=$false)]
   [ValidateNotNullOrEmpty()]   
   [string]$ExchangeAutodiscoverDomain,
   [Parameter(Mandatory=$false)]
   [ValidateNotNullOrEmpty()]   
   [string]$WebApplicationUrl,
   [Parameter(Mandatory=$false)]
   [switch]$Force
)
$script:currentDirectory = Split-Path $MyInvocation.MyCommand.Path
if($WebApplicationUrl -ne $NULL -and $WebApplicationUrl -ne "")
{
    $webapps = Get-SPWebApplication $WebApplicationUrl
}
else
{
    $webapps = Get-SPWebApplication
}
if($webapps -eq $NULL)
{
    if($WebApplicationUrl -ne $NULL)
    {
        Write-Warning "No Web Application Found at $($WebApplicationUrl). Please create a web application and re-run Set-SiteMailboxConfig"
    }
    else
    {
        Write-Warning "No Web Applications Found. Please create a web application and re-run Set-SiteMailboxConfig"
    }
    
    return
}
$rootWeb = $NULL
foreach($webapp in $webapps)
{
    if($rootWeb -eq $NULL)
    {
        $rootWeb = Get-SPWeb $webApp.Url -EA SilentlyContinue
    }
}
if($rootWeb -eq $NULL)
{
    Write-Warning "Unable to find a root site collection. Please create a root site collection on a web application and re-run Set-SiteMailboxConfig"
    return
}
$exchangeServer = $ExchangeAutodiscoverDomain
if($exchangeServer -eq $NULL -or $exchangeServer -eq "")
{
    $exchangeServer = "autodiscover.$($ExchangeSiteMailboxDomain)"
}
Write-Host "Establishing Trust with Exchange Server: $($exchangeServer)"
$metadataEndpoint = "https://$($exchangeServer)/autodiscover/metadata/json/1"
$exchange = Get-SPTrustedSecurityTokenIssuer | Where-Object { $_.MetadataEndpoint -eq $metadataEndpoint }
if($exchange -eq $NULL)  
{
    $exchange = New-SPTrustedSecurityTokenIssuer -Name $exchangeServer -MetadataEndPoint $metadataEndpoint
}
if($exchange -eq $NULL)
{
    Write-Warning "Unable to establish trust with Exchange Server $($exchangeServer). Ensure that $($metadataEndpoint) is accessible."
    if($ExchangeAutodiscoverDomain -eq $NULL -or $ExchangeAutodiscoverDomain -eq "")
    {
        Write-Warning "If $($metadataEndpoint) doesn't exist, you may specify an alternate FQDN using ExchangeAutodiscoverDomain."
    }
    return
}
Write-Host "Granting Permissions to Exchange Server: $($exchangeServer)"
$appPrincipal = Get-SPAppPrincipal -Site $rootWeb.Url -NameIdentifier $exchange.NameId
Set-SPAppPrincipalPermission -AppPrincipal $appPrincipal -Site $rootWeb -Scope SiteSubscription -Right FullControl -EnableAppOnlyPolicy
Write-Host
Write-Host
Write-Host "Verifying Site Mailbox Configuration"
$warnings = & $script:currentDirectory\Check-SiteMailboxConfig.ps1 -ReturnWarningState
if($warnings -and -not $Force)
{
    Write-Warning "Pre-requisites not satisfied. Stopping Set-SiteMailboxConfig. Use -Force to override"
    return
}
elseif($warnings)
{
    Write-Warning "Pre-requisites not satisfied. -Force used to override"
}
foreach($webapp in $webapps)
{
    Write-Host "Configuring Web Application: $($webapp.Url)"
    Write-Host "Setting Exchange Site Mailbox Domain to $($ExchangeSiteMailboxDomain)"
    $webapp.Properties["ExchangeTeamMailboxDomain"] = $ExchangeSiteMailboxDomain
        
    if($ExchangeAutodiscoverDomain -ne $NULL -and $ExchangeAutodiscoverDomain -ne "")
    {
        Write-Host "Setting Exchange Autodiscover Domain to $($ExchangeAutodiscoverDomain)"
        $webapp.Properties["ExchangeAutodiscoverDomain"] = $ExchangeAutodiscoverDomain;
    }
    $webapp.Update()
}
$feature = Get-SPFeature CollaborationMailboxFarm -Farm -ErrorAction Ignore
if($feature -eq $NULL)
{
    Write-Host "Enabling Site Mailboxes for Farm"
    Enable-SPFeature CollaborationMailboxFarm
}
else
{
    Write-Host "Site Mailboxes already enabled for Farm"
}

Check-SiteMailboxConfig.ps1:

Param
(
   [Parameter(Mandatory=$false)]
   [ValidateNotNullOrEmpty()]   
   [switch]$ReturnWarningState
)
Add-PSSnapin Microsoft.SharePoint.Powershell
$anyWarnings = $false
Write-Host "Step 1: Checking for Exchange Web Services"
try
{
    $assm = [System.Reflection.Assembly]::Load("Microsoft.Exchange.WebServices, Version=15.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35")
    if($assm.GlobalAssemblyCache)
    {
        Write-Host -Foreground Green "Found Exchange Web Services in Global Assembly Cache"
        Write-Host "Exchange Web Services Version: $([System.Diagnostics.FileVersionInfo]::GetVersionInfo($assm.Location).FileVersion)"
    }
    else
    {
        Write-Warning "Unable to find Exchange Web Services in Global Assembly Cache"
        $anyWarnings = $true
    }
}
catch
{
    Write-Warning "Unable to find Exchange Web Services in Global Assembly Cache"
    $anyWarnings = $true
}
Write-Host
Write-Host
Write-Host "Step 2: Checking for https web application"
$webapps = Get-SPWebApplication -EA SilentlyContinue
$rootWeb = $NULL
if($webapps -ne $NULL)
{
    $sslWebAppExists = $false
    foreach($webapp in $webapps)
    {
        if($rootWeb -eq $NULL)
        {
            $rootWeb = Get-SPWeb $webApp.Url -EA SilentlyContinue
        }
        if(-not $webapp.Url.StartsWith("https://"))
        {
            Write-Warning "Web Application at $($webapp.Url) does not use HTTPS. Site Mailboxes will not work on this Web Application."
        }
        else
        {
            $sslWebAppExists = $true
            Write-Host -Foreground Green "Found Web Application at $($webapp.Url) that uses HTTPS"
        }
    }
    if(-not $sslWebAppExists)
    {
        Write-Warning "At least one Web Application must be configured for HTTPS in the default zone."
        $anyWarnings = $true
    }
}
else
{
    Write-Warning "No Web Applications Found. Please create a web application and re-run Check-SiteMailboxConfig"
    $anyWarnings = $true
    if($ReturnWarningState)
    {
        return $anyWarnings
    }
    return;
}
if($rootWeb -eq $NULL)
{
    Write-Warning "Unable to find any Sites. Please create a root site collection on a web application and re-run Check-SiteMailboxConfig"
    $anyWarnings = $true
    if($ReturnWarningState)
    {
        return $anyWarnings
    }
    return;
}
# Get App Permissions Management Objects
$appPrincipalManager = [Microsoft.SharePoint.SPAppPrincipalManager]::GetManager($rootWeb)
$appPrincipalPermissionsManager = New-Object -TypeName Microsoft.SharePoint.SPAppPrincipalPermissionsManager -ArgumentList $rootWeb        
Write-Host
Write-Host
Write-Host "Step 3: Checking for trusted Exchange Servers"
$trustedIssuers = Get-SPTrustedSecurityTokenIssuer
$trustedIssuerHosts = @()
if($trustedIssuers -ne $NULL)
{
    $foundTrustedIssuer = $false
    foreach($trustedIssuer in $trustedIssuers)
    {
        if($trustedIssuer.RegisteredIssuerName.StartsWith("00000002-0000-0ff1-ce00-000000000000@"))
        {
            if($trustedIssuer.IsSelfIssuer)
            {
                $foundTrustedIssuer = $true
                $uri = New-Object -TypeName System.Uri -ArgumentList $trustedIssuer.MetadataEndPoint
                
                Write-Host -Foreground Green "Found trusted Exchange Server at $($uri.Host)"
                $appPrincipalName = [Microsoft.SharePoint.SPAppPrincipalName]::CreateFromNameIdentifier($trustedIssuer.RegisteredIssuerName)
                $appPrincipal = $appPrincipalManager.LookupAppPrincipal([Microsoft.SharePoint.SPAppPrincipalIdentityProvider]::External, $appPrincipalName);
                
                if($appPrincipal -ne $NULL)
                {
                    $isValidAppPrincipal = $true;
                    if($appPrincipalPermissionsManager.GetAppPrincipalSiteSubscriptionContentPermission($appPrincipal) -eq [Microsoft.SharePoint.SPAppPrincipalPermissionKind]::FullControl)
                    {
                        Write-Host -Foreground Green "Exchange Server at $($uri.Host) has Full Control permissions"
                        
                    }
                    else
                    {
                        Write-Warning "Exchange Server at $($uri.Host) does not have Full Control permissions"
                        $isValidAppPrincipal = $false;
                        $anyWarnings = $true
                    }
                    if($appPrincipalPermissionsManager.IsAppOnlyPolicyAllowed($appPrincipal))
                    {
                        Write-Host -Foreground Green "Exchange Server at $($uri.Host) has App Only Permissions"
                    }
                    else
                    {
                        Write-Warning "Exchange Server at $($uri.Host) does not have App Only Permissions"
                        $isValidAppPrincipal = $false;
                        $anyWarnings = $true
                    }
                    
                    if($isValidAppPrincipal)
                    {
                        $trustedIssuerHosts += $uri.Host
                    }
                }
                else
                {
                    Write-Warning "Unable to get App Principal for $($uri.Host). Unable to check permissions for this Exchange Server"
                    $anyWarnings = $true
                }
            }
            else
            {
                Write-Warning "Found trusted Exchange Server at $($uri.Host) but it is not a Self Issuer"
                $anyWarnings = $true
            }
        }
    }
    if(-not $foundTrustedIssuer)
    {
        Write-Warning "Unable to find any trusted Exchange Servers"
        $anyWarnings = $true
    }
}
else
{
    Write-Warning "Unable to find any trusted Exchange Servers"
    $anyWarnings = $true
}
Write-Host
Write-Host
Write-Host "Step 4: Report current Site Mailbox Configuration"
if($webapps -ne $NULL)
{
    foreach($webapp in $webapps)
    {
        Write-Host
        Write-Host "Web Application Site Mailbox Configuration: $($webapp.Url)"
        Write-Host "Exchange Site Mailbox Domain: $($webapp.Properties["ExchangeTeamMailboxDomain"])"
        
        if($webapp.Properties["ExchangeAutodiscoverDomain"] -ne $NULL)
        {
            Write-Host "Exchange Autodiscover Domain: $($webapp.Properties["ExchangeAutodiscoverDomain"])"
        }
    }
}
Write-Host
Write-Host "Trusted Exchange Services: $([String]::Join(", ", $trustedIssuerHosts))"
$feature = Get-SPFeature CollaborationMailboxFarm -Farm -ErrorAction Ignore
if($feature -eq $NULL)
{
    Write-Host -ForegroundColor Red "Site Mailboxes are NOT enabled for Farm"
}
else
{
    Write-Host -ForegroundColor Green "Site Mailboxes are enabled for Farm"
}
if($ReturnWarningState)
{
    return $anyWarnings
}

Salvare i due file con estensione ps1 nella stessa cartella in un server applicazioni o front-end di SharePoint Server, dato che uno script chiama l'altro durante l'esecuzione. In una finestra di Microsoft PowerShell (aperta facendo clic con il pulsante destro del mouse sull'icona di PowerShell e scegliendo Esegui come amministratore) passare alla cartella che contiene i file con estensione ps1 ed eseguire lo script Set-SiteMailboxConfig.ps1. Ciò consente agli utenti di eseguire le operazioni seguenti:

Recuperare e installare i metadati di Exchange, assegnando all'entità servizio di Exchange autorizzazioni di controllo completo per la sottoscrizione del sito di SharePoint.
Abilitare la funzionalità Cassette postali siti nell'ambiente SharePoint.
(Facoltativo) Impostare il dominio di destinazione per le cassette postali del sito di Exchange, se il DNS per il dominio non è stato configurato per l'individuazione automatica

Check-SiteMailboxConfig.ps1 viene chiamato come parte dello script Set-SiteMailboxConfig e verifica la corretta esecuzione della configurazione (può essere eseguito anche separatamente).

Il formato dovrebbe essere il seguente:

   .\Set-SiteMailboxConfig.ps1 -ExchangeSiteMailboxDomain \<Domain\> -ExchangeAutodiscoverDomain [Exchange Server] -WebApplicationUrl [URL]

Dove <Dominio> è il nome completo (FQDN) del dominio in cui si trova Exchange Server ed <Exchange Server> è il server Exchange a cui ci si desidera connettere. Questo è un parametro obbligatorio.

I parametri facoltativi sono [Exchange Server], ovvero il server Exchange a cui si intende connettersi (questo parametro è obbligatorio se l'individuazione automatica non è abilitata o configurata correttamente) e [URL], ovvero un URL specifico che è possibile configurare (utilizzato in genere in un ambiente con applicazioni Web SSL e non SSL).

Esempio:

   .\Set-SiteMailboxConfig.ps1 -ExchangeSiteMailboxDomain tailspintoys.com -ExchangeAutodiscoverDomain exchange1.tailspintoys.com -WebApplicationUrl https://tailspintoys.com

Se si verifica un errore durante l'esecuzione dello script, fare riferimento alle indicazioni nella sezione "Risoluzione dei problemi" in questo articolo.

Configurare Exchange Server per le cassette postali del sito

Il passaggio finale consiste nell'impostare il trust OAuth e le autorizzazioni per il servizio nel server di Exchange.

Impostare il trust OAuth e l'autorizzazione per il servizio in Exchange

Nell'istanza di Exchange Server aprire la finestra powershell di gestione di Exchange come amministratore e passare alla directory "C:\Programmi\Microsoft\Exchange Server\V15\Scripts".
Eseguire il comando riportato di seguito:
```
.\Configure-EnterprisePartnerApplication.ps1 -ApplicationType Sharepoint -AuthMetadataUrl https://<SP_FQDN>/_layouts/15/metadata/json/1
```
Dove <SP_FQDN> è l'URL della raccolta siti radice SSL di SharePoint che si desidera configurare.

Risoluzione dei problemi

In caso di problemi, fare riferimento alla tabella seguente.

Tabella dei codici di errore di riferimento durante l'esecuzione di uno script di verifica della configurazione (Check)

Codice di errore	Errore	Note
0	NoError	Controllare i prerequisiti.
1	ExchangeClientNotAvailable	Il client EWS non è stato trovato in SharePoint WFE. Eseguire lo script Check e verificare che le voci siano presenti correttamente nella GAC. potrebbe essere necessario reinstallare il client EWS.
2	UnsupportedVersion	La versione del client Servizi Web Exchange non è compatibile con SharePoint. Eseguire lo script Check per assicurarsi che la versione soddisfi i requisiti minimi. In alternativa, è possibile che sia in uso la versione 2010 o precedente di Exchange Server.
3	InvalidUser	Il parametro TeamMailboxDomain non è un nome di dominio completo (FQDN) o un indirizzo SMTP valido.
4	UnauthorizedUser	Lo script ha ricevuto il codice 401 da Exchange Server. Controllare i passaggi per la configurazione di Exchange.
5	ServerBusy	Timeout di Exchange durante l'individuazione automatica. Dovrebbe essere intermittente, riprovare, ma se è persistente, contattare l'amministratore di Exchange.
6	URLNotAvailable	L'individuazione automatica non è riuscita a restituire un URL per ECP/OWA e ciò significa in genere che la versione del client Servizi Web Exchange non è compatibile con SharePoint. Potrebbe inoltre indicare che le cassette postali del sito non sono abilitate in Exchange e in questo caso è necessario rivolgersi all'amministratore di Exchange.
7	OAuthNotSupported	Non è riuscita la generazione di un token OAuth per conto di SharePoint. La causa è in genere la disabilitazione dell'autenticazione basata sulle attestazioni nell'applicazione Web di SharePoint.
8	OAuthException	Si è verificato un errore durante l'handshake OAuth tra SharePoint ed Exchange. Ciò è in genere causato da problemi di configurazione da server a server, ad esempio una mancata corrispondenza del valore dell'area di autenticazione su entrambi i lati, problemi di certificato per Exchange o SharePoint e così via. Esaminare i certificati e tentare di stabilire o ristabilire l'attendibilità.
9	InvalidAutodiscoverDomain	La proprietà del dominio di individuazione automatica non è impostata su un nome di dominio completo valido.
10	UnknownError	Si è verificata una condizione di errore sconosciuta. Eseguire lo script Check e verificare che sia disponibile un'istanza attendibile valida di SharePoint, esaminare i prerequisiti, verificare che l'individuazione automatica sia stata configurata correttamente con l'amministratore di Exchange.
101	OAuthNotSupportedOverHttp	Quando viene generato questo errore, l'area predefinita dell'applicazione Web non è impostata su SSL e l'impostazione di AllowOauthoverHttp è inoltre false. Eseguire lo script Check per assicurarsi che qualsiasi applicazione Web che verrà utilizzata per ospitare le casette postali del sito sia impostata con SSL nell'area predefinita, come indicato nei prerequisiti.
102	AssociatedOwnersGroupNull	Uno o entrambi i gruppi predefiniti Proprietari e Membri per il sito sono stati eliminati. Entrambi questi due gruppi predefiniti devono esistere in qualsiasi sito in cui gli utenti installano le cassette postali del sito. Un amministratore del sito deve essere in grado di indirizzare un proprietario del sito a ricreare questi gruppi necessari.
103	ExchangeTeamMailboxDomainNotSet	La proprietà ExchangeTeamMailboxDomain non è stata impostata.
104	ExchangeAppPrincipalNotFound	Non è stata trovata alcuna identità app Exchange attendibile. In genere, ciò indica la mancata esecuzione del passaggio New-SPTrustedSecureTokenService. Eseguire lo script Check e assicurarsi che gli URL dell'entità app dell'output siano corretti.
105	ExchangeAppPrincipalMissingPermissions	L'entità app Exchange a cui ci si connette non dispone delle autorizzazioni appropriate nella farm di SharePoint. Eseguire lo script Check e assicurarsi che l'entità app Exchange disponga delle autorizzazioni appropriate nella farm.