Toolkit CASI (Claims, Azure and SharePoint Integration) - Parte 2
Toolkit CASI (Claims, Azure and SharePoint Integration) - Parte 2
Questa è la seconda parte di una serie di post in cinque parti dedicata al toolkit CASI (Claims, Azure and SharePoint Integration). La prima parte è una panoramica introduttiva dell'intero framework e della soluzione, in cui vengono descritti gli argomenti trattati nella serie. In questo post viene illustrato lo schema dell'approccio adottato:
1. Utilizzo di un'applicazione WCF personalizzata come front-end per dati e contenuti
2. Integrazione delle funzionalità per il riconoscimento delle attestazioni nell'applicazione
3. Introduzione di alcune modifiche aggiuntive per consentire l'inserimento nella cloud di Windows Azure
Utilizzo di WCF
Il framework del kit CASI viene utilizzato principalmente per consentire l'utilizzo di un'applicazione WCF come front-end per i dati di tutte le applicazioni. Come tutte le applicazioni personalizzate, anche queste ultime devono essere create dallo sviluppatore. Per questa parte del progetto non è necessaria praticamente alcuna competenza specifica su SharePoint. Qualsiasi sviluppatore .NET che utilizzi Visual Studio è infatti in grado di creare un'applicazione WCF. Se questo servizio WCF deve essere ospitato in Windows Azure, è consigliabile utilizzare il kit di sviluppo di Windows Azure, scaricare i modelli per la creazione di applicazioni per Azure e iniziare a creare un'applicazione WCF per Azure dall'inizio. La versione corrente del kit CASI presenta tuttavia un'importante limitazione che è necessario tenere presente. In realtà il kit CASI supporta solo l'invio dei principali tipi di dati .NET come parametri ai metodi WCF. Stringhe, valori booleani, integer e date non creano pertanto alcun problema, ma non esiste un modo per passare una classe personalizzata come parametro. Per eseguire tale operazione, è consigliabile creare il parametro come stringa e deserializzarlo in formato XML prima di chiamare il metodo WCF, quindi serializzarlo nuovamente come istanza di un oggetto nel codice WCF. Oltre a questa, finora non ho trovato altre limitazioni significative, ma sono certo che si verrà presto a creare un elenco di funzionalità da aggiungere, appena il kit comincerà ad essere adottato e utilizzato più diffusamente. Ricordate che la versione attuale del kit è solo una prima idea di come integrare tutti gli elementi e io l'ho progettato per soddisfare le esigenze degli scenari principali in cui ho lavorato, decidendo man mano che cosa fosse importante. C'è senza dubbio molto spazio per i miglioramenti che si renderanno necessari a mano a mano che il prodotto verrà utilizzato.
Integrazione delle funzionalità per il riconoscimento delle attestazioni nell'applicazione
Dopo aver creato l'applicazione WCF è necessario integrarvi le funzionalità per il riconoscimento delle attestazioni. Questa parte non è tuttavia di mia competenza, pertanto vi rimando all'eccellente serie di post di blog in quattro parti scritta da Eric White, del team di Office, per illustrare l'integrazione delle attestazioni di SharePoint in un'applicazione WCF. Presupponendo che abbiate già creato il vostro servizio WCF, inizierei con la seconda parte di questa serie di blog, all'indirizzo https://blogs.msdn.com/b/ericwhite/archive/2010/05/13/determining-caller-identity-within-a-wcf-web-service.aspx. È inoltre necessario continuare eseguendo le procedure descritte nella terza parte, all'indirizzo https://blogs.msdn.com/b/ericwhite/archive/2010/06/18/establishing-trust-between-a-wcf-web-service-and-the-sharepoint-2010-security-token-service.aspx , a partire dalla sezione Procedure: Establish Trust between the Web Service and the SharePoint Server. Dovete eseguire tutti i passaggi da questo punto in poi, che di fatto consistono nel copiare nel file web.config dell'applicazione WCF l'identificazione digitale del certificato di firma dei token per il servizio token di sicurezza di SharePoint, insieme ad altre informazioni. Personalmente non seguirei alla lettera la procedura relativa a SSL illustrata nella terza parte, perché l'utilizzo di un certificato autofirmato non è realmente utile quando l'applicazione viene ospitata in Windows Azure. Se non avete altro a disposizione, potete adottare questa soluzione, ma in generale dovete prevedere di richiedere a un'autorità di certificazione appropriata un certificato SSL per l'applicazione WCF ospitata in Windows Azure. NOTA: NON è necessario eseguire la procedura illustrata nella quarta parte della serie di blog di Eric White. Infatti, dopo avere eseguito i passaggi illustrati in precedenza, disporrete di un'applicazione WCF per SharePoint funzionante in grado di riconoscere le attestazioni. Nell'ultima parte di questo post vi illustrerò i passaggi aggiuntivi da eseguire per integrare il servizio nella cloud di Windows Azure.
Integrazione in Windows Azure
Dopo aver creato un'applicazione WCF funzionante per Azure è necessario effettuare alcune operazioni aggiuntive, affinché possa continuare a supportare l'autenticazione delle attestazioni e i token tramite Windows Identity Framework (WIF) ed essere ospitata nella cloud di Windows Azure. Ecco un elenco delle operazioni da eseguire:
1. Configurare il progetto WebRole (ossia il progetto WCF) in modo da utilizzare una directory virtuale locale per il debug. Rispetto al server di sviluppo VS.NET, la directory virtuale locale è molto più semplice da utilizzare per attività come la gestione dei certificati, ovvero quella che vi interessa. Per modificare tale impostazione, è necessario fare doppio clic sulle proprietà del progetto WebRole e quindi passare alla scheda Web. È necessario selezionare il pulsante di opzione "Usa server Web IIS locale" e quindi fate clic sul pulsante Crea directory virtuale. Dopo aver creato la directory virtuale è possibile chiudere le proprietà del progetto.
2. Aggiungere al progetto WebRole un riferimento a Microsoft.Identity. Il riferimento DEVE essere modificato in Copy Local = true e Specific Version = false. Questa operazione è necessaria per copiare l'assembly WIF nella cloud insieme al pacchetto dell'applicazione.
3. Recuperare il seguente hotfix per WCF: https://code.msdn.microsoft.com/KB981002/Release/ProjectReleases.aspx?ReleaseId=4009 per Windows 2008 R2, e https://code.msdn.microsoft.com/KB971842/Release/ProjectReleases.aspx?ReleaseId=3228 per Windows 2008.
4. AGGIUNGERE l'attributo seguente alla classe WCF: [ServiceBehavior(AddressFilterMode = AddressFilterMode.Any)]. Il codice della classe dovrebbe essere pertanto simile al seguente:
namespace CustomersWCF_WebRole
{
[ServiceBehavior(AddressFilterMode = AddressFilterMode.Any)]
public class Customers : ICustomers
{
5. INCLUDERE i dati di configurazione seguenti nell'elemento behavior utilizzato dal servizio, per risolvere i problemi che possono verificarsi con l'assegnazione casuale delle porte nell'ambiente Azure. Per testare questo aspetto localmente, è necessario l'hotfix indicato al punto 3.
<useRequestHeadersForMetadataAddress>
<defaultPorts>
<add scheme="http" port="80" />
<add scheme="https" port="443" />
</defaultPorts>
</useRequestHeadersForMetadataAddress>
Questo è un esempio in contesto del file web.config per il mio servizio WCF:
<behaviors>
<serviceBehaviors>
<behavior name="CustomersWCF_WebRole.CustomersBehavior">
<federatedServiceHostConfiguration name="CustomersWCF_WebRole.Customers"/>
<serviceMetadata httpGetEnabled="true" httpsGetEnabled="true"/>
<serviceDebug includeExceptionDetailInFaults="false"/>
<useRequestHeadersForMetadataAddress>
<defaultPorts>
<add scheme="http" port="80" />
<add scheme="https" port="443" />
</defaultPorts>
</useRequestHeadersForMetadataAddress>
</behavior>
</serviceBehaviors>
</behaviors>
6. Caricare innanzitutto il certificato SSL utilizzato per l'applicazione WCF nel portale di sviluppo di Azure. NOTA: poiché la classe base del kit CASI è obbligata a utilizzare SSL, È NECESSARIO implementare il supporto per SSL nell'applicazione WCF per Windows Azure. Questo è probabilmente un requisito prevedibile per il passaggio di dati potenzialmente sensibili tra un servizio cloud e una farm di SharePoint. Il certificato deve essere quindi aggiunto alle proprietà del ruolo Azure in Visual Studio, facendo doppio clic sul nome del progetto WebRole (nella cartella Ruoli). Ho provato a utilizzare un certificato con caratteri jolly e non ho avuto problemi. Tuttavia, è necessario un certificato PFX e quando create il file PFX dovete verificare che vengano esportati tutti i certificati nella catena. Tutti questi certificati verranno infatti espansi durante il caricamento nel portale di sviluppo di Azure.
7. Il certificato SSL deve essere per Nome.nomeDns.com, anche se tutte le applicazioni per Azure vengono ospitate in cloudapp.net. Io utilizzo ad esempio un certificato SSL con caratteri jolly per *.vbtoys.com. Ho creato nel DNS un nuovo record CNAME denominato azurewcf.vbtoys.com che fa riferimento a myAzureApp.cloudapp.net. Pertanto, quando stabilisco una connessione a https://azurewcf.vbtoys.com il certificato funziona perché la richiesta e il certificato SSL sono per *.vbtoys.com, ma il DNS reindirizza la richiesta in base al record CNAME, ovvero a myAzureApp.cloudapp.net.
8. Nel progetto per Azure fare doppio clic sul nome del progetto WebRole (nella cartella Ruoli) e impostare le proprietà come segue:
a. Scheda Configurazione: Deselezionare Avvia il browser per: endpoint HTTP e HTTPS.
b. Scheda Certificati: aggiungere il certificato da utilizzare per SSL con il servizio. Ad esempio, poiché in laboratorio utilizzo un certificato con caratteri jolly emesso dal mio dominio per tutti i miei server, qui ho aggiunto un certificato con caratteri jolly.
c. Scheda Endpoint: selezionare le caselle per HTTP e HTTPS (i nomi dovrebbero essere rispettivamente HttpIn e HttpsIn). Nella sezione HTTPS, il menu a discesa del certificato SSL ora dovrebbe contenere il certificato SSL aggiunto nel passaggio b.
9. Se si utilizza un metodo WCF che restituisce script, il tag script deve includere l'attributo DEFER per funzionare correttamente quando si utilizza la web part inclusa nel kit CASI o se la funzione JavaScript personalizzata lo assegna all'attributo innerHTML di un tag. Il tag script potrebbe essere ad esempio: <script defer language='javascript'>.
10. Se si utilizza un metodo WCF che restituisce contenuto in cui sono presenti altri tag di formattazione, ad esempio <style>, è necessario racchiuderli in un tag <pre>. In caso contrario, non verrebbero elaborati correttamente quando si utilizza la web part inclusa nel kit CASI o se la funzione JavaScript personalizzata lo assegna all'attributo innerHTML di un tag. Il contenuto restituito con un tag style potrebbe ad esempio avere l'aspetto seguente: <pre><style>.foo {font-size:8pt;}</style></pre>.
Queste sono le operazioni da eseguire per configurare l'applicazione WCF da ospitare in Azure. Di seguito sono riportati alcuni suggerimenti che possono essere utili, e in alcuni casi necessari, a seconda dell'implementazione.
1. Quando create l'indirizzo dell'endpoint che utilizza il servizio, utilizzate il nome completo, ovvero machineName.foo.com, anziché semplicemente machineName. Ciò semplificherà la transizione al formato finale ospitato in Windows Azure e potrebbe anche eliminare gli errori che si verificano quando si utilizzano certificati SSL progettati per l'utilizzo di nomi di dominio completi.
2. Se desiderate utilizzare WSDL su SSL, È CONSIGLIABILE aggiungere l'attributo: httpsGetEnabled="true" all'elemento: <serviceMetadata httpGetEnabled="true" />. In SharePoint Designer è tuttavia presente un bug che impedisce di utilizzare SSL per WSDL.
3. Per i suggerimenti relativi al debug e alle connessioni dati, potete leggere il post all'indirizzo https://blogs.technet.com/b/speschka/archive/2010/09/19/azure-development-tips-for-debugging-and-connection-strings.aspx.
4. Nella maggior parte dei casi è possibile presupporre che lo spazio dei nomi del servizio WCF sia https://tempuri.org. Per istruzioni su come modificare tale impostazione, potete leggere il post all'indirizzo https://blogs.infosupport.com/blogs/edwinw/archive/2008/07/20/WCF_3A00_-namespaces-in-WSDL.aspx.
Servizio WCF completo
Se avete eseguito tutti i passaggi di configurazione precedenti e distribuito l'applicazione WCF in Windows Azure, quando un utente effettua una chiamata a tale servizio WCF da un sito di SharePoint viene inviato anche il relativo token utente, con tutte le attestazioni associate. Poiché dopo queste modifiche il servizio WCF funzionerà anche in locale, potrà essere testato facilmente nel caso in cui desideriate apportare alcune modifiche incrementali prima di eseguire il push dell'applicazione nella cloud. Il token utente ricevuto consente di eseguire alcune operazioni molto interessanti nel servizio WCF. Ad esempio, all'interno del servizio WCF è possibile enumerare tutte le attestazioni dell'utente e, in base a queste ultime, prendere qualsiasi tipo di decisione che richieda autorizzazioni specifiche. Nell'esempio seguente viene utilizzata la sintassi LINQ sul set di attestazioni dell'utente per determinare se l'utente corrente è un amministratore, perché in tal caso nella richiesta verranno restituite informazioni con un livello di dettaglio superiore.
//look for the claims identity
IClaimsIdentity ci =
System.Threading.Thread.CurrentPrincipal.Identity as IClaimsIdentity;
if (ci != null)
{
//see if there are claims present before running through this
if (ci.Claims.Count > 0)
{
//look for a group claim of domain admin
var eClaim = from Microsoft.IdentityModel.Claims.Claim c in ci.Claims
where c.ClaimType ==
"https://schemas.microsoft.com/ws/2008/06/identity/claims/role" &&
c.Value == "Domain Admins"
select c;
//see if we got a match
if (eClaim.Count() > 0)
//there’s a match so this user has the Domain Admins claim
//do something here
}
}
È inoltre possibile effettuare richieste di autorizzazione direttamente nei metodi WCF. Supponete ad esempio di utilizzare un metodo WCF che esegue query su un archivio dati e restituisce l'elenco dei CEO dei clienti. Tali informazioni non devono essere accessibili a tutti i dipendenti, ma solo ai responsabili vendite. Per implementare questa funzionalità in modo semplice ed efficace, è possibile utilizzare una richiesta PrincipalPermission nel metodo, ad esempio:
//the customer CEO list should not be shared with everyone,
//so only show it to people in the Sales Manager role
[PrincipalPermission(SecurityAction.Demand, Role = "Sales Managers")]
public string GetCustomerCEOs()
{
//your code goes here
}
Se ora un utente privo dell'attestazione di responsabile vendite prova a utilizzare codice che chiama questo metodo, verrà visualizzato un errore di accesso negato. Semplice ed efficace.
È importante ricordare che questo impedisce anche lo spoofing. Ad esempio, non potete semplicemente creare un dominio personalizzato in laboratorio, aggiungere un account e creare un ruolo di responsabile vendite a qui aggiungere l'account. Ciò è dovuto alla procedura illustrata nel blog di Eric White, che avete eseguito nella sezione Integrazione delle funzionalità per il riconoscimento delle attestazioni nell'applicazione. Come ricorderete, avete aggiunto il certificato di firma dei token utilizzato dal servizio token di sicurezza di SharePoint. Pertanto, quando riceve un'attestazione, l'applicazione WCF verifica che il token sia stato firmato con la chiave pubblica del servizio token di sicurezza di SharePoint. Solo il servizio token di sicurezza di SharePoint può apporre una firma con tale chiave pubblica, perché è l'unica entità che dispone della chiave privata per il certificato di firma dei token. Questo garantisce che il servizio WCF potrà essere utilizzato solo dagli utenti autenticati dalla farm di SharePoint e che tali utenti disporranno solo delle attestazioni che hanno ricevuto al momento dell'accesso. È importante notare che non vengono incluse solo le attestazioni concesse al momento dell'autenticazione nella relativa directory utente, ma anche tutte le ulteriori attestazioni eventualmente aggiunte in SharePoint tramite un provider di attestazioni personalizzate. Questa è pertanto una soluzione end-to-end veramente integrata.
Passaggi successivi
Nel post successivo inizierò a illustrare la classe base e la web part personalizzate fornite con il kit CASI, che consentono di connettersi alla nuova applicazione WCF per Azure in modo molto semplice e rapido. Inoltre, da ora in poi per illustrare le funzionalità utilizzerò un servizio WCF creato espressamente per il kit CASI. Il file .cs utilizzato per tale servizio è allegato a questo post. Il file non può essere utilizzato così com'è, ma è stato incluso solo per consentirvi di esaminare i vari metodi utilizzati, i tipi di dati che contiene e la modalità di implementazione di determinate funzionalità per questo kit. Nei post successivi utilizzerò soprattutto i metodi a) GetAllCustomersHtml, b) GetCustomerCEOs e c) GetAllCustomers, che sono molto interessanti perché a) restituiscono codice HTML, che di fatto è il tipo restituito preferenziale per la visualizzazione dei dati nelle web part, b) utilizzano una richiesta PrincipalPermission e c) mostrano come restituire un tipo di classe personalizzato dall'applicazione WCF e utilizzare tale classe avanzata dopo il reinserimento dei dati in SharePoint tramite il kit CASI.
Questo è un post di blog localizzato. Consultate l'articolo originale: The Claims, Azure and SharePoint Integration Toolkit Part 2