Procedura: creare un client federato

In Windows Communication Foundation (WCF), la creazione di un client per un servizio federato è costituita da tre passaggi principali:

1. Configurare una classe wsFederationHttpBinding element o un'associazione personalizzata simile. Per ulteriori informazioni sulla creazione di un'associazione appropriata, vedere Procedura: creare una classe WSFederationHttpBinding. In alternativa, eseguire ServiceModel Metadata Utility Tool (Svcutil.exe) per l'endpoint dei metadati del servizio federato per generare un file di configurazione per comunicare con il servizio federato e uno o più servizi token di protezione.
2. Impostare le proprietà di IssuedTokenClientCredential che controlla i vari aspetti dell'interazione di un client con un servizio token di protezione.
3. Impostare le proprietà di X509CertificateRecipientClientCredential, che consente ai certificati richiesti di comunicare in modo protetto con determinati endpoint, ad esempio servizi token di protezione.

In questo argomento vengono fornite informazioni dettagliate su queste procedure. Per ulteriori informazioni sulla creazione di un'associazione appropriata, vedere Procedura: creare una classe WSFederationHttpBinding. Per ulteriori informazioni sul funzionamento di un servizio federato, vedere Federazione.

Per generare ed esaminare la configurazione per un servizio federato

1. Eseguire ServiceModel Metadata Utility Tool (Svcutil.exe) con l'indirizzo dell'URL dei metadati del servizio come parametro della riga di comando.

2. Aprire il file di configurazione generato in un editor appropriato.

3. Esaminare gli attributi e il contenuto di qualsiasi elemento <issuer> e <issuerMetadata> generato. Questi si trovano all'interno degli elementi <security> per <wsFederationHttpBinding> o degli elementi delle associazioni personalizzate. Assicurarsi che gli indirizzi contengano i nomi di dominio previsti o altre informazioni sull'indirizzo. È importante controllare queste informazioni perché il client viene autenticato presso questi indirizzi e può fornire informazioni quali coppie di nome utente/password. Se l'indirizzo non è quello previsto, le informazioni potrebbero venire fornite a un destinatario imprevisto.

4. Esaminare qualsiasi elemento aggiuntivo <issuedTokenParameters> all'interno dell'elemento <alternativeIssuedTokenParameters> impostato come commento. Quando viene utilizzato lo strumento Svcutil.exe per generare la configurazione per un servizio federato, se quest'ultimo o qualsiasi servizio token di protezione intermedio non specifica l'indirizzo del mittente ma un indirizzo dei metadai per un servizio token di protezione che espone più endpoint, il file di configurazione risultante fa riferimento al primo endpoint. Gli endpoint aggiuntivi sono presenti nel file di configurazione come elementi <alternativeIssuedTokenParameters> impostati come commenti.

   Stabilire se uno di questi <issuedTokenParameters> è preferibile a quello già presente nella configurazione. Il client, ad esempio, potrebbe preferire autenticarsi presso un servizio token di protezione utilizzando un token Windows CardSpace anziché una coppia nome utente/password.

   Nota

   Nel caso in cui sia necessario attraversare più servizi token di protezione prima di comunicare con il servizio, un servizio token di protezione intermedio potrebbe indirizzare il client a un servizio token di protezione errato. Assicurarsi pertanto che l'endpoint per il servizio token di protezione in <issuedTokenParameters> sia il servizio token di protezione previsto e non un servizio token di protezione sconosciuto.

Per configurare un IssuedTokenClientCredential nel codice

1. Accedere a IssuedTokenClientCredential tramite la proprietà IssuedToken della classe ClientCredentials (restituita dalla proprietà ClientCredentials della classe ClientBase o tramite la classe ChannelFactory), come illustrato nell'esempio di codice seguente.

2. Se non è richiesta la memorizzazione del token nella cache, impostare la proprietà CacheIssuedTokens su false. La proprietà CacheIssuedTokens controlla se tali token da un servizio token di protezione sono memorizzati nella cache. Se questa proprietà è impostata su false, il client richiede un nuovo token al servizio token di protezione ogni volta che deve autenticarsi di nuovo al servizio federato, a prescindere dal fatto che un token precedente sia ancora valido. Se questa proprietà è impostata su true, il client riutilizza un token esistente ogni volta che deve autenticarsi di nuovo al servizio federato (a condizione che il token non sia scaduto). L'impostazione predefinita è true.

3. Se è richiesto un tempo massimo sui token memorizzati nella cache, impostare la proprietà MaxIssuedTokenCachingTime su un valore TimeSpan. La proprietà specifica quanto tempo un token può essere memorizzato nella cache. Allo scadere del periodo di tempo specificato, il token viene rimosso dalla cache del client. Per impostazione predefinita, i token sono memorizzati nella cache per una durata illimitata. Nell'esempio seguente, l'intervallo di tempo viene impostato su 10 minuti.

4. Facoltativo. Impostare IssuedTokenRenewalThresholdPercentage su una percentuale. Il valore predefinito è 60 (percento). La proprietà specifica una percentuale del periodo di validità del token. Se il token emesso è valido, ad esempio, per 10 ore e IssuedTokenRenewalThresholdPercentage è impostato su 80, il token verrà rinnovato dopo otto ore. Nell'esempio seguente il valore viene impostato su 80 percento.

   L'intervallo di rinnovo determinato dal periodo di validità del token e il valore IssuedTokenRenewalThresholdPercentage vengono sottoposti a override da parte del valore MaxIssuedTokenCachingTime nei casi in cui il tempo di memorizzazione nella cache sia inferiore al tempo soglia di rinnovo. Se, ad esempio, il prodotto di IssuedTokenRenewalThresholdPercentage e la durata del token è otto ore e il valore MaxIssuedTokenCachingTime è 10 minuti, il client contatta il servizio token di protezione per un token aggiornato ogni 10 minuti.

5. Se è richiesta una modalità entropia chiave diversa da CombinedEntropy su un'associazione che non utilizza la protezione del messaggio o la protezione del trasporto con le credenziali del messaggio (ad esempio, l'associazione non ha un SecurityBindingElement), impostare la proprietà DefaultKeyEntropyMode su un valore appropriato. La modalità entropia determina se le chiavi simmetriche possono essere controllate utilizzando la proprietà DefaultKeyEntropyMode. Questa impostazione predefinita è CombinedEntropy, dove sia il client che l'emittente del token, forniscono dati combinati per produrre la chiave effettiva. Gli altri valori sono ClientEntropy e ServerEntropy, il che indica che la chiave intera è specificata rispettivamente dal client o dal server. Nell'esempio seguente viene impostata la proprietà per utilizzare solo i dati del server per la chiave.

   Nota

   Se in un servizio token di protezione o in un'associazione del servizio è presente un elemento SecurityBindingElement, DefaultKeyEntropyMode impostata su IssuedTokenClientCredential viene sottoposta a override da parte della proprietà KeyEntropyMode di SecurityBindingElement.

6. Configurare qualsiasi comportamento dell'endopoint specifico per l'emittente aggiungendolo all'insieme restituito dalla proprietà IssuerChannelBehaviors.

Per configurare IssuedTokenClientCredential nella configurazione

1. Creare un elemento <issuedToken> come figlio dell'elemento <clientCredentials> in un comportamento dell'endpoint.

2. Se non è richiesta la memorizzazione del token nella cache, impostare l'attributo cacheIssuedTokens (dell'elemento <issuedToken>) su false.

3. Se è richiesto un tempo massimo sui token memorizzati nella cache, impostare l'attributo maxIssuedTokenCachingTime nell'elemento <issuedToken> su un valore appropriato. Ad esempio:
   <issuedToken maxIssuedTokenCachingTime='00:10:00' />

4. Se si preferisce un valore diverso da quello predefinito, impostare l'attributo issuedTokenRenewalThresholdPercentage nell'elemento <issuedToken> su un valore adatto, ad esempio:

   <issuedToken issuedTokenRenewalThresholdPercentage = "80" />
   

5. Se una modalità entropia chiave diversa da CombinedEntropy è su un'associazione che non utilizza la protezione del messaggio o la protezione del trasporto con le credenziali del messaggio (ad esempio, l'associazione non ha un SecurityBindingElement), impostare l'attributo defaultKeyEntropyMode nell'elemento <issuedToken> su ServerEntropy o ClientEntropy, come richiesto.

   <issuedToken defaultKeyEntropyMode = "ServerEntropy" />
   

6. Facoltativo. Configurare qualsiasi comportamento dell'endpoint personalizzato specifico dell'emittente creando un elemento <issuerChannelBehaviors> come figlio dell'elemento <issuedToken>. Per ogni comportamento, creare un elemento <add> come figlio dell'elemento <issuerChannelBehaviors>. Specificare l'indirizzo dell'emittente del comportamento impostando l'attributo issuerAddress nell'elemento <add>. Specificare il comportamento stesso impostando l'attributo behaviorConfiguration nell'elemento <add>.

   <issuerChannelBehaviors>
   <add issuerAddress="http://fabrikam.org/sts" behaviorConfiguration="FabrikamSTS" />
   </issuerChannelBehaviors>
   

Per configurare un X509CertificateRecipientClientCredential nel codice

1. Accedere a X509CertificateRecipientClientCredential tramite la proprietà ServiceCertificate della proprietà ClientCredentials della classe ClientBase o la proprietà ChannelFactory.

2. Se è disponibile un'istanza di X509Certificate2 per il certificato per un determinato endpoint, utilizzare il metodo Add dell'insieme restituito dalla proprietà ScopedCertificates.

3. Se non è disponibile un'istanza di X509Certificate2, utilizzare il metodo SetScopedCertificate della classe X509CertificateRecipientClientCredential come illustrato nell'esempio seguente.

Per configurare un X509CertificateRecipientClientCredential nella configurazione

1. Creare un elemento <scopedCertificates> come figlio dell'elemento <serviceCertifcate>, che è a sua volta figlio dell'elemento <clientCredentials> in un comportamento dell'endpoint.

2. Creare un elemento <add> come figlio dell'elemento <scopedCertificates>. Specificare i valori per gli attributi storeLocation, storeName, x509FindType e findValue per fare riferimento al certificato appropriato. Impostare l'attributo targetUri su un valore che fornisce l'indirizzo dell'endpoint per il quale deve essere utilizzato il certificato, come illustrato nell'esempio seguente.

   <scopedCertificates>
    <add targetUri="https://fabrikam.com/sts" 
         storeLocation="CurrentUser"
         storeName="TrustedPeople"
         x509FindType="FindBySubjectName"
         findValue="FabrikamSTS" />
   </scopedCertificates>
   

Esempio

Nell'esempio di codice seguente viene configurata un'istanza della classe IssuedTokenClientCredential nel codice.

Protezione

Per impedire che vengano divulgate determinate informazioni, i client che stanno eseguendo lo strumento Svcutil.exe per elaborare i metadati dagli endpoint federati devono assicurarsi che gli indirizzi del servizio token di protezione risultanti siano quelli previsti. Ciò è particolarmente importante quando un servizio token di protezione espone più endpoint, perché lo strumento Svcutil.exe genera il file di configurazione risultante per utilizzare il primo di questi endpoint che potrebbe non essere quello che il client deve utilizzare.

LocalIssuer Required

Se si prevede che i client utilizzino sempre un emittente locale, tenere presente quanto segue: per impostazione predefinita, lo strumento Svcutil.exe fa sì che l'emittente locale non venga utilizzato nel caso in cui il penultimo servizio token di protezione nella catena specifichi un indirizzo dell'emittente o un indirizzo dei metadati dell'emittente.

Per ulteriori informazioni sull'impostazione delle proprietà LocalIssuerAddress, LocalIssuerBinding e LocalIssuerChannelBehaviors della classe IssuedTokenClientCredential, vedere Procedura: configurare un emittente locale.

Certificati con ambito

Se è necessario specificare certificati del servizio per comunicare con qualsiasi servizio token di protezione, in genere perché la negoziazione del certificato non è utilizzata, utilizzare la proprietà ScopedCertificates della classe X509CertificateRecipientClientCredential. Il metodo SetDefaultCertificate prende Uri e X509Certificate2 come parametri. Il certificato specificato viene utilizzato quando si comunica con gli endpoint nell'URI specificato. In alternativa, è possibile utilizzare il metodo SetScopedCertificate per aggiungere un certificato all'insieme restituito dalla proprietà ScopedCertificates.

Vedere anche

Attività

Procedura: disattivare sessioni protette in un'associazione WSFederationHttpBinding
Procedura: creare una classe WSFederationHttpBinding
Procedura: configurare le credenziali in un servizio federativo
Procedura: configurare un emittente locale
Procedura: proteggere endpoint dei metadati

Concetti

Considerazioni sulla protezione con metadati

Altre risorse

Federation Sample