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 su sulla creazione di un'associazione appropriata, vedere Procedura: creare una classe WSFederationHttpBinding. In alternativa, eseguire Strumento 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 sicurezza.

2. Impostare le proprietà di IssuedTokenClientCredential che controlla i vari aspetti dell'interazione di un client con un servizio token di sicurezza.

3. Impostare le proprietà di X509CertificateRecipientClientCredential, che consente ai certificati richiesti di comunicare in modo protetto con determinati endpoint, ad esempio servizi token di sicurezza.

Nota:

Potrebbe venire generata una CryptographicException quando un client utilizza credenziali rappresentate, l'associazione WSFederationHttpBinding o un token personalizzato e chiavi simmetriche. Chiavi asimmetriche sono utilizzate con l'associazioneWSFederationHttpBinding e token personalizzati quando le proprietà IssuedKeyType e KeyType sono impostate rispettivamente su AsymmetricKey. CryptographicException viene generato quando il client tenta di inviare un messaggio e non esiste un profilo utente per l'identità che il client sta rappresentando. Per limitare questo problema, accedere al computer client o chiamare LoadUserProfile prima di inviare il messaggio.

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

Per generare ed esaminare la configurazione per un servizio federato

1. Eseguire Strumento 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><issuerMetadata> e generato. Questi si trovano all'interno degli elementi <security><wsFederationHttpBinding> per 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 sicurezza intermedio non specifica l'indirizzo del mittente ma un indirizzo dei metadai per un servizio token di sicurezza 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 sicurezza utilizzando un token Windows CardSpace anziché una coppia nome utente/password.

   Nota:

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

   Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken
   

   IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;
   

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 sicurezza sono memorizzati nella cache. Se questa proprietà è impostata su false, il client richiede un nuovo token al servizio token di sicurezza 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.

   itcc.MaxIssuedTokenCachingTime = New TimeSpan(0, 10, 0)
   

   itcc.MaxIssuedTokenCachingTime = new TimeSpan(0, 10, 0);
   

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.

   itcc.IssuedTokenRenewalThresholdPercentage = 80
   

   itcc.IssuedTokenRenewalThresholdPercentage = 80;
   

   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 sicurezza 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.

   itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy
   

   itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy;
   

   Nota:
   Se in un servizio token di sicurezza 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 alla raccolta restituita dalla proprietà IssuerChannelBehaviors.

   itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior)
   

   itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior);
   

Per configurare IssuedTokenClientCredential nella configurazione

1. Creare un elemento <issuedToken><clientCredentials> come figlio dell'elemento 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>ServerEntropy su ClientEntropy o , 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.

   Dim rcc As X509CertificateRecipientClientCredential = _
   client.ClientCredentials.ServiceCertificate
   

   X509CertificateRecipientClientCredential rcc =
       client.ClientCredentials.ServiceCertificate;
   

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

   rcc.ScopedCertificates.Add(New Uri("https://fabrikam.com/sts"), cert)
   

   rcc.ScopedCertificates.Add(new Uri("https://fabrikam.com/sts"), cert);
   

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

   rcc.SetScopedCertificate(StoreLocation.CurrentUser, _
               StoreName.TrustedPeople, _
               X509FindType.FindBySubjectName, _
               "FabrikamSTS", _
               New Uri("https://fabrikam.com/sts"))
   

   public void snippet20(CalculatorClient client)
   {
       X509CertificateRecipientClientCredential rcc = client.ClientCredentials.ServiceCertificate;
       rcc.SetScopedCertificate(StoreLocation.CurrentUser,
                                StoreName.TrustedPeople,
                                X509FindType.FindBySubjectName,
                                "FabrikamSTS",
                                new Uri("https://fabrikam.com/sts"));
   }
   

Per configurare un X509CertificateRecipientClientCredential nella configurazione

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

2. Creare un elemento <add><scopedCertificates> come figlio dell'elemento . 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.

// This method configures the IssuedToken property of the Credentials property of a proxy/channel factory
public static void ConfigureIssuedTokenClientCredentials(ChannelFactory cf, bool cacheTokens,
                                                          TimeSpan tokenCacheTime, int renewalPercentage,
                                                          SecurityKeyEntropyMode entropyMode
                                                          )
{
    if (cf == null)
    {
        throw new ArgumentNullException("ChannelFactory");
    }
    // Set the CacheIssuedTokens property
    cf.Credentials.IssuedToken.CacheIssuedTokens = cacheTokens;

    // Set the MaxIssuedTokenCachingTime property
    cf.Credentials.IssuedToken.MaxIssuedTokenCachingTime = tokenCacheTime;

    // Set the IssuedTokenRenewalThresholdPercentage property
    cf.Credentials.IssuedToken.IssuedTokenRenewalThresholdPercentage = renewalPercentage;

    // Set the DefaulyKeyEntropyMode property
    cf.Credentials.IssuedToken.DefaultKeyEntropyMode = entropyMode;
}

Sicurezza

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 sicurezza risultanti siano quelli previsti. Ciò è particolarmente importante quando un servizio token di sicurezza 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 sicurezza nella catena specifichi un indirizzo dell'emittente o un indirizzo dei metadati dell'emittente.

Per ulteriori informazioni su 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 sicurezza, 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.

Nota:

L'idea client di certificati definiti con ambito per uno specifico URI si applica solo alle applicazioni che stanno effettuando chiamate in uscita a servizi che espongono endpoint a tali URI. Non si applica ai certificati utilizzati per firmare i token emessi, ad esempio quelli configurati nel server nell'insieme restituito da KnownCertificatesdella classe IssuedTokenServiceCredential. Per ulteriori informazioni, vedere Procedura: configurare le credenziali in un servizio federativo.

Vedere anche

Attività

Esempio di federazione
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
How to: Secure Metadata Endpoints

Concetti

Security Considerations with Metadata