Delen via

Procedure: Een federatieve client maken

  • Artikel

In Windows Communication Foundation (WCF) bestaat het maken van een client voor een federatieve service uit drie hoofdstappen:

  1. Configureer een <wsFederationHttpBinding> of vergelijkbare aangepaste binding. Zie Een WSFederationHttpBinding maken voor meer informatie over het maken van een geschikte binding. U kunt ook het hulpprogramma hulpprogramma voor metagegevens van ServiceModel (Svcutil.exe) uitvoeren op het metagegevenseindpunt van de federatieve service om een configuratiebestand te genereren voor communicatie met de federatieve service en een of meer beveiligingstokenservices.

  2. Stel de eigenschappen van de IssuedTokenClientCredential eigenschappen in waarmee verschillende aspecten van de interactie van een client met een beveiligingstokenservice worden bepaald.

  3. Stel de eigenschappen van het X509CertificateRecipientClientCredentialcertificaat in, waarmee certificaten die nodig zijn om veilig te communiceren met bepaalde eindpunten, zoals beveiligingstokenservices, kunnen worden ingesteld.

Notitie

Er CryptographicException kan een fout optreden wanneer een client geïmiteerde referenties, de WSFederationHttpBinding binding of een aangepast token en asymmetrische sleutels gebruikt. Asymmetrische sleutels worden gebruikt met de bindings- en aangepaste tokens wanneer respectievelijk WSFederationHttpBinding de IssuedKeyType en KeyType eigenschappen zijn ingesteld op AsymmetricKey. De CryptographicException fout wordt gegenereerd wanneer de client probeert een bericht te verzenden en er geen gebruikersprofiel bestaat voor de identiteit die de client nabootst. Meld u aan bij de clientcomputer of oproep LoadUserProfile voordat u het bericht verzendt om dit probleem op te lossen.

Dit onderwerp bevat gedetailleerde informatie over deze procedures. Zie Een WSFederationHttpBinding maken voor meer informatie over het maken van een geschikte binding. Zie Federatie voor meer informatie over hoe een federatieve service werkt.

De configuratie voor een federatieve service genereren en onderzoeken

  1. Voer het hulpprogramma voor metagegevens van ServiceModel (Svcutil.exe) uit met het adres van de metagegevens-URL van de service als opdrachtregelparameter.

  2. Open het gegenereerde configuratiebestand in een geschikte editor.

  3. Bekijk de kenmerken en inhoud van gegenereerde verleners> en <issuerMetadata-elementen>.< Deze bevinden zich in de <beveiligingselementen> voor de <wsFederationHttpBinding>- of aangepaste bindingselementen. Zorg ervoor dat de adressen de verwachte domeinnamen of andere adresgegevens bevatten. Het is belangrijk om deze informatie te controleren omdat de client zich bij deze adressen verifieert en informatie kan vrijgeven, zoals gebruikersnaam/wachtwoordparen. Als het adres niet het verwachte adres is, kan dit leiden tot openbaarmaking van informatie aan een onbedoelde ontvanger.

  4. Bekijk eventuele aanvullende uitgegevenTokenParameters-elementen <> in het uitgecommentarieerde <alternativeIssuedTokenParameters> element. Wanneer u het hulpprogramma Svcutil.exe gebruikt voor het genereren van configuratie voor een federatieve service, als de federatieve service of tussenliggende beveiligingstokenservices geen verleneradres opgeven, maar eerder een metagegevensadres opgeven voor een beveiligingstokenservice die meerdere eindpunten beschikbaar maakt, verwijst het resulterende configuratiebestand naar het eerste eindpunt. Aanvullende eindpunten bevinden zich in het configuratiebestand als uit commentaar voorziene <alternativeIssuedTokenParameters> elementen.

    Bepaal of een van deze <issuedTokenParameters> de voorkeur heeft voor degene die al aanwezig is in de configuratie. De client kan bijvoorbeeld de voorkeur geven aan verificatie bij een beveiligingstokenservice met behulp van een Windows CardSpace-token in plaats van een gebruikersnaam/wachtwoordpaar.

    Notitie

    Wanneer meerdere beveiligingstokenservices moeten worden doorkruist voordat de communicatie met de service wordt uitgevoerd, is het mogelijk dat een tussenliggende beveiligingstokenservice de client naar een onjuiste beveiligingstokenservice leidt. Zorg er daarom voor dat het eindpunt voor de beveiligingstokenservice in de <issuedTokenParameters> de verwachte beveiligingstokenservice is en niet een onbekende beveiligingstokenservice.

Een IssuedTokenClientCredential configureren in code

  1. Open de IssuedTokenClientCredential via de IssuedToken eigenschap van de ClientCredentials klasse (geretourneerd door de ClientCredentials eigenschap van de ClientBase<TChannel> klasse of via de ChannelFactory klasse), zoals wordt weergegeven in de volgende voorbeeldcode.

    IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;

    Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken

  2. Als tokencaching niet vereist is, stelt u de CacheIssuedTokens eigenschap falsein op . De CacheIssuedTokens eigenschap bepaalt of dergelijke tokens van een beveiligingstokenservice in de cache worden opgeslagen. Als deze eigenschap is ingesteld op false, vraagt de client een nieuw token aan bij de beveiligingstokenservice wanneer deze zichzelf opnieuw moet verifiëren bij de federatieve service, ongeacht of een eerder token nog steeds geldig is. Als deze eigenschap is ingesteld trueop, gebruikt de client een bestaand token wanneer het opnieuw moet worden geverifieerd bij de federatieve service (zolang het token niet is verlopen). De standaardwaarde is true.

  3. Als een tijdslimiet is vereist voor tokens in de cache, stelt u de MaxIssuedTokenCachingTime eigenschap in op een TimeSpan waarde. De eigenschap geeft aan hoe lang een token in de cache kan worden opgeslagen. Nadat de opgegeven periode is verstreken, wordt het token verwijderd uit de clientcache. Tokens worden standaard voor onbepaalde tijd in de cache opgeslagen. In het volgende voorbeeld wordt de tijdsduur ingesteld op 10 minuten.

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

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

  4. Optioneel. Stel het in IssuedTokenRenewalThresholdPercentage op een percentage. De standaardwaarde is 60 (procent). De eigenschap geeft een percentage van de geldigheidsperiode van het token op. Als het uitgegeven token bijvoorbeeld 10 uur geldig is en IssuedTokenRenewalThresholdPercentage is ingesteld op 80, wordt het token na acht uur verlengd. In het volgende voorbeeld wordt de waarde ingesteld op 80 procent.

    itcc.IssuedTokenRenewalThresholdPercentage = 80;

    itcc.IssuedTokenRenewalThresholdPercentage = 80

    Het verlengingsinterval dat wordt bepaald door de geldigheidsperiode van het token en de IssuedTokenRenewalThresholdPercentage waarde wordt overschreven door de MaxIssuedTokenCachingTime waarde in gevallen waarin de cachetijd korter is dan de tijd van de verlengingsdrempel. Als het product van en de duur van IssuedTokenRenewalThresholdPercentage het token bijvoorbeeld acht uur is en de MaxIssuedTokenCachingTime waarde 10 minuten is, neemt de client elke tien minuten contact op met de beveiligingstokenservice voor een bijgewerkt token.

  5. Als een andere sleutel-entropiemodus dan CombinedEntropy nodig is voor een binding die geen berichtbeveiliging of transportbeveiliging gebruikt met berichtreferenties (bijvoorbeeld. de binding heeft geen SecurityBindingElement), stelt u de DefaultKeyEntropyMode eigenschap in op een geschikte waarde. De entropiemodus bepaalt of symmetrische sleutels kunnen worden beheerd met behulp van de DefaultKeyEntropyMode eigenschap. Deze standaardwaarde is CombinedEntropy, waarbij zowel de client als de tokenverlener gegevens levert die worden gecombineerd om de werkelijke sleutel te produceren. Andere waarden zijn ClientEntropy en ServerEntropy, wat betekent dat de volledige sleutel wordt opgegeven door respectievelijk de client of de server. In het volgende voorbeeld wordt de eigenschap ingesteld om alleen de servergegevens voor de sleutel te gebruiken.

    itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy;

    itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy

    Notitie

    Als een SecurityBindingElement is opgenomen in een beveiligingstokenservice of servicebinding, wordt de DefaultKeyEntropyMode set ingeschakeld IssuedTokenClientCredential door de KeyEntropyMode eigenschap van de SecurityBindingElement.

  6. Configureer eventuele gedrag van verleners voor eindpunten door deze toe te voegen aan de verzameling die door de IssuerChannelBehaviors eigenschap wordt geretourneerd.

    itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior);

    itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior)

De IssuedTokenClientCredential configureren in de configuratie

  1. Maak een uitgegevenToken-element> als onderliggend element van het< afgegevenToken-element> in een eindpuntgedrag.<

  2. Als tokencaching niet vereist is, stelt u het cacheIssuedTokens kenmerk (van het <issuedToken> element) in op false.

  3. Als een tijdslimiet is vereist voor tokens in de cache, stelt u het maxIssuedTokenCachingTime kenmerk voor het <issuedToken> element in op een geschikte waarde. Bijvoorbeeld: <issuedToken maxIssuedTokenCachingTime='00:10:00' />

  4. Als een andere waarde dan de standaardwaarde de voorkeur heeft, stelt u het issuedTokenRenewalThresholdPercentage kenmerk voor het <issuedToken> element in op een geschikte waarde, bijvoorbeeld:

    <issuedToken issuedTokenRenewalThresholdPercentage = "80" />

  5. Als een andere sleutel-entropiemodus dan CombinedEntropy zich op een binding bevindt die geen berichtbeveiliging of transportbeveiliging gebruikt met berichtreferenties (bijvoorbeeld de binding heeft geen SecurityBindingElement), stelt u het defaultKeyEntropyMode kenmerk voor het <issuedToken> element in op een ServerEntropy of ClientEntropy indien nodig.

    <issuedToken defaultKeyEntropyMode = "ServerEntropy" />

  6. Optioneel. Configureer elk aangepast eindpuntgedrag voor verleners door een <issuerChannelBehaviors> element als onderliggend element van het <issuedToken> element te maken. Maak voor elk gedrag een <add> element als een onderliggend element van het <issuerChannelBehaviors> element. Geef het adres van de verlener van het gedrag op door het issuerAddress kenmerk op het element in te <add> stellen. Geef het gedrag zelf op door het behaviorConfiguration kenmerk op het element in te <add> stellen.

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

Een X509CertificateRecipientClientCredential configureren in code

  1. Toegang tot de X509CertificateRecipientClientCredential ServiceCertificate eigenschap van de eigenschap van de ClientCredentials ClientBase<TChannel> klasse of de ChannelFactory eigenschap.

    X509CertificateRecipientClientCredential rcc =
    client.ClientCredentials.ServiceCertificate;

    Dim rcc As X509CertificateRecipientClientCredential = _
client.ClientCredentials.ServiceCertificate

  2. Als een X509Certificate2 exemplaar beschikbaar is voor het certificaat voor een bepaald eindpunt, gebruikt u de Add methode van de verzameling die door de ScopedCertificates eigenschap wordt geretourneerd.

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

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

  3. Als een X509Certificate2 exemplaar niet beschikbaar is, gebruikt u de SetScopedCertificate methode van de X509CertificateRecipientClientCredential klasse, zoals wordt weergegeven in het volgende voorbeeld.

    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"))

Een X509CertificateRecipientClientCredential configureren in de configuratie

  1. Maak een scopedCertificates-element> als een onderliggend element van het <serviceCertificate-element> dat zelf een onderliggend element is van het <clientCredentials-element> in een eindpuntgedrag.<

  2. Maak een <add> element als onderliggend element van het <scopedCertificates> element. Geef waarden op voor de storeLocationkenmerken , storeNameen findValue x509FindTypekenmerken die naar het juiste certificaat moeten verwijzen. Stel het targetUri kenmerk in op een waarde waarmee het adres van het eindpunt wordt opgegeven waarvoor het certificaat moet worden gebruikt, zoals wordt weergegeven in het volgende voorbeeld.

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

Opmerking

In het volgende codevoorbeeld wordt een exemplaar van de IssuedTokenClientCredential klasse in code geconfigureerd.

// 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

.NET Framework-beveiliging

Om mogelijke openbaarmaking van gegevens te voorkomen, moeten clients die het hulpprogramma Svcutil.exe uitvoeren om metagegevens van federatieve eindpunten te verwerken, ervoor zorgen dat de resulterende serviceadressen voor beveiligingstokens zijn wat ze verwachten. Dit is met name belangrijk wanneer een beveiligingstokenservice meerdere eindpunten beschikbaar maakt, omdat het Svcutil.exe hulpprogramma het resulterende configuratiebestand genereert voor het gebruik van het eerste dergelijke eindpunt, wat mogelijk niet het eindpunt is dat de client moet gebruiken.

LocalIssuer vereist

Als clients naar verwachting altijd een lokale verlener gebruiken, moet u rekening houden met het volgende: de standaarduitvoer van Svcutil.exe leidt ertoe dat de lokale verlener niet wordt gebruikt als de tweede-op-laatste beveiligingstokenservice in de keten een adres voor verlener of metagegevensadres van de uitgever opgeeft.

Zie How to: Configure a Local Issuer (Een lokale verlener configureren) voor meer informatie over het instellen van de LocalIssuerAddress, LocalIssuerBindingen LocalIssuerChannelBehaviors eigenschappen van de IssuedTokenClientCredential klasse.

Scoped Certificates

Als servicecertificaten moeten worden opgegeven voor communicatie met een van de beveiligingstokenservices, meestal omdat certificaatonderhandeling niet wordt gebruikt, kunnen ze worden opgegeven met behulp van de ScopedCertificates eigenschap van de X509CertificateRecipientClientCredential klasse. De SetDefaultCertificate methode gebruikt een Uri en een als parameters X509Certificate2 . Het opgegeven certificaat wordt gebruikt bij het communiceren met eindpunten op de opgegeven URI. U kunt ook de SetScopedCertificate methode gebruiken om een certificaat toe te voegen aan de verzameling die door de ScopedCertificates eigenschap wordt geretourneerd.

Notitie

Het clientidee van certificaten die zijn gericht op een bepaalde URI, is alleen van toepassing op toepassingen die uitgaande aanroepen doen naar services die eindpunten op die URI's beschikbaar maken. Het is niet van toepassing op certificaten die worden gebruikt voor het ondertekenen van uitgegeven tokens, zoals certificaten die zijn geconfigureerd op de server in de verzameling die door de KnownCertificates IssuedTokenServiceCredential klasse wordt geretourneerd. Zie How to: Configure Credentials on a Federation Service(s) (Referenties configureren in een Federation Service) voor meer informatie.

Zie ook