Procedura: creare un client federato

Articolo
04/10/2024

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

Configurare <wsFederationHttpBinding> o un simile binding personalizzato. Per altre informazioni sulla creazione di un'associazione appropriata, vedere Procedura: Creare un WSFederationHttpBinding. In alternativa, eseguire lo 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.
Impostare le proprietà di IssuedTokenClientCredential che controlla i vari aspetti dell'interazione di un client con un servizio token di sicurezza.
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 altre informazioni sulla creazione di un'associazione appropriata, vedere Procedura: Creare un WSFederationHttpBinding. Per altre informazioni sul funzionamento di un servizio federativo, vedere Federazione.

Per generare ed esaminare la configurazione per un servizio federato

Eseguire lo strumento ServiceModel Metadata Utility Tool (Svcutil.exe) con l'indirizzo dell'URL dei metadati del servizio come parametro della riga di comando.
Aprire il file di configurazione generato in un editor appropriato.
Esaminare gli attributi e il contenuto di tutti gli elementi <issuer> and <issuerMetadata> generati. Si trovano all'interno degli elementi <security> per gli elementi di binding <wsFederationHttpBinding> o personalizzati. 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.
Esaminare eventuali elementi <issuedTokenParameters> aggiuntivi all'interno dell'elemento <alternativeIssuedTokenParameters> commentato. 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 si trovano nel file di configurazione come elementi commentati <alternativeIssuedTokenParameters>.

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

Accedere a IssuedTokenClientCredential tramite la proprietà IssuedToken della classe ClientCredentials (restituita dalla proprietà ClientCredentials della classe ClientBase<TChannel> o tramite la classe ChannelFactory), come illustrato nell'esempio di codice seguente.
```
IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;
```
```
Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken
```
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). Il valore predefinito è true.
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)
```
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.
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.
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

Creare un elemento <issuedToken> come elemento figlio dell'elemento <issuedToken> in un comportamento dell'endpoint.
Se non è richiesta la memorizzazione del token nella cache, impostare l'attributo cacheIssuedTokens (dell'elemento <issuedToken>) su false.
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' />
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" />  
```
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 ServerEntropy su<issuedToken>ClientEntropy oServerEntropy, come richiesto.
```
<issuedToken defaultKeyEntropyMode = "ServerEntropy" />  
```
Facoltativo. Configurare qualsiasi comportamento dell'endpoint personalizzato specifico dell'autorità di certificazione creando un elemento <issuerChannelBehaviors> come elemento figlio dell'elemento <issuedToken>. Per ogni comportamento, creare un elemento <add> come elemento 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

Accedere a X509CertificateRecipientClientCredential tramite la proprietà ServiceCertificate della proprietà ClientCredentials della classe ClientBase<TChannel> o la proprietà ChannelFactory.

X509CertificateRecipientClientCredential rcc =
    client.ClientCredentials.ServiceCertificate;

Dim rcc As X509CertificateRecipientClientCredential = _
client.ClientCredentials.ServiceCertificate

Se è disponibile un'istanza di X509Certificate2 per il certificato per un determinato endpoint, utilizzare il metodo Add della raccolta restituita dalla proprietà ScopedCertificates.
```
rcc.ScopedCertificates.Add(new Uri("http://fabrikam.com/sts"), cert);
```
```
rcc.ScopedCertificates.Add(New Uri("http://fabrikam.com/sts"), cert)
```

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

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

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

Per configurare un X509CertificateRecipientClientCredential nella configurazione

Creare un elemento <scopedCertificates> come elemento figlio dell'elemento <serviceCertificate> che è un elemento figlio dell'elemento <clientCredentials> in un comportamento dell'endpoint.
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="http://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("cf");
    }
    // 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 DefaultKeyEntropyMode property
    cf.Credentials.IssuedToken.DefaultKeyEntropyMode = entropyMode;
}

' This method configures the IssuedToken property of the Credentials property of a proxy/channel factory
Public Shared Sub ConfigureIssuedTokenClientCredentials(ByVal cf As ChannelFactory, _
                                                        ByVal cacheTokens As Boolean, _
                                                        ByVal tokenCacheTime As TimeSpan, _
                                                        ByVal renewalPercentage As Integer, _
                                                        ByVal entropyMode As SecurityKeyEntropyMode)
    If cf Is Nothing Then
        Throw New ArgumentNullException("ChannelFactory")
    End If
    ' Set the CacheIssuedTokens property
    With cf.Credentials.IssuedToken
        .CacheIssuedTokens = cacheTokens

        ' Set the MaxIssuedTokenCachingTime property
        .MaxIssuedTokenCachingTime = tokenCacheTime

        ' Set the IssuedTokenRenewalThresholdPercentage property
        .IssuedTokenRenewalThresholdPercentage = renewalPercentage

        ' Set the DefaultKeyEntropyMode property
        .DefaultKeyEntropyMode = entropyMode
    End With
End Sub

Sicurezza di .NET Framework

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 altre informazioni sull'impostazione delle proprietà LocalIssuerAddress, LocalIssuerBinding e LocalIssuerChannelBehaviors della classe IssuedTokenClientCredential, vedere Procedura: Configurare un'autorità di certificazione 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 alla raccolta restituita dalla proprietà ScopedCertificates.