方法: フェデレーションクライアントを作成する

[アーティクル]
04/06/2023

Windows Communication Foundation (WCF) での "フェデレーションサービス" 用クライアントの作成は、主に次の 3 つの手順で構成されます。

<wsFederationHttpBinding> または同様のカスタムバインディングを構成します。適切なバインディングを作成する方法の詳細については、「方法: WSFederationHttpBinding を作成する」を参照してください。または、フェデレーションサービスのメタデータエンドポイントに対して ServiceModel メタデータユーティリティツール (Svcutil.exe) を実行し、フェデレーションサービスおよび 1 つ以上のセキュリティトークンサービスとの通信用の構成ファイルを作成します。
クライアントがセキュリティトークンサービスと対話する際のさまざまな側面を制御する IssuedTokenClientCredential のプロパティを設定します。
セキュリティトークンサービスなど、特定のエンドポイントとのセキュリティ保護された通信に必要な証明書を許可する X509CertificateRecipientClientCredential のプロパティを設定します。

Note

クライアントが、偽装された資格情報、CryptographicException バインディングやカスタムの発行済みトークン、および非対称キーを使用すると、WSFederationHttpBinding がスローされる可能性があります。 WSFederationHttpBinding プロパティと IssuedKeyType プロパティをそれぞれ KeyType に設定すると、AsymmetricKey バインディングとカスタムの発行済みトークンで非対称キーが使用されます。クライアントがメッセージを送信しようとするときに、クライアントが偽装している ID のユーザープロファイルが存在しないと、CryptographicException がスローされます。この問題を回避するには、クライアントコンピューターにログオンした後、または LoadUserProfile を呼び出した後に、メッセージを送信します。

ここでは、これらの手順について詳しく説明します。適切なバインディングを作成する方法の詳細については、「方法: WSFederationHttpBinding を作成する」を参照してください。フェデレーションサービスのしくみの詳細については、「フェデレーション」を参照してください。

フェデレーションサービスの構成を生成し、確認するには

サービスのメタデータ URL のアドレスをコマンドラインパラメーターとして使用して、ServiceModel メタデータユーティリティツール (Svcutil.exe) を実行します。
生成された構成ファイルを適切なエディターで開きます。
生成されたすべての <issuer> 要素と <issuerMetadata> 要素の属性と内容を調べます。これらは、<wsFederationHttpBinding> またはカスタムバインディング要素の <security> 要素内にあります。予期されたドメイン名やその他のアドレス情報がアドレスに含まれていることを確認します。この情報をチェックすることは重要です。それは、クライアントがこれらのアドレスに対して認証を行い、ユーザー名とパスワードの組み合わせなどの情報を公開する可能性があるためです。アドレスが予期されたアドレスではない場合、意図しない受信者に情報が公開されるおそれがあります。
コメントアウトされた <alternativeIssuedTokenParameters> 要素内の追加の <issuedTokenParameters> 要素を調べます。 Svcutil.exe ツールを使用してフェデレーションサービスの構成を生成するときに、フェデレーションサービスまたは任意の中間セキュリティトークンサービスが、発行者アドレスを指定せずに、複数のエンドポイントを公開するセキュリティトークンサービスのメタデータアドレスを指定している場合、生成された構成ファイルは最初のエンドポイントを参照します。追加のエンドポイントは、コメントアウトされた <alternativeIssuedTokenParameters> 要素として構成ファイルに含まれます。

これらの <issuedTokenParameters> のいずれかが、構成に既に存在するものよりも適切かどうかを判断します。たとえば、セキュリティトークンサービスに対する認証を行う際は、ユーザー名とパスワードの組み合わせよりも Windows CardSpace トークンを使用する方が、クライアントにとって望ましい場合があります。

Note

サービスと通信するまでに複数のセキュリティトークンサービスをたどる必要がある場合は、中間セキュリティトークンサービスがクライアントを不適切なセキュリティトークンサービスにダイレクトする可能性があります。そのため、<issuedTokenParameters> 内のセキュリティトークンサービスのエンドポイントが、予期されたセキュリティトークンサービスであり、不明なセキュリティトークンサービスでないことを確認します。

コードで IssuedTokenClientCredential を構成するには

次のコード例に示すように、IssuedTokenClientCredential クラスの IssuedToken プロパティまたは ClientCredentials クラスから返された、ClientCredentials クラスの ClientBase<TChannel> プロパティから ChannelFactory にアクセスします。
```
IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;
```
```
Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken
```
トークンキャッシュが不要な場合は、CacheIssuedTokens プロパティを false に設定します。 CacheIssuedTokens プロパティにより、セキュリティトークンサービスからのこれらのトークンをキャッシュするかどうかが制御されます。このプロパティを false に設定すると、クライアントは、以前のトークンがいまだに有効な場合でも、フェデレーションサービスに対してクライアント自体を再認証する必要があるときに、新しいトークンをセキュリティトークンサービスに要求します。このプロパティを true に設定すると、クライアントは、トークンの有効期限が切れていない限り、フェデレーションサービスに対してクライアント自体を再認証する必要があるときに既存のトークンを再利用します。既定では、 trueです。
キャッシュされたトークンの制限時間を設ける必要がある場合は、MaxIssuedTokenCachingTime プロパティを TimeSpan 値に設定します。このプロパティは、トークンがキャッシュされる時間を指定します。指定の時間が経過すると、トークンはクライアントのキャッシュから削除されます。既定では、トークンは無期限でキャッシュされます。制限時間を 10 分に設定する例を次に示します。
```
itcc.MaxIssuedTokenCachingTime = new TimeSpan(0, 10, 0);
```
```
itcc.MaxIssuedTokenCachingTime = New TimeSpan(0, 10, 0)
```
任意。 IssuedTokenRenewalThresholdPercentage をパーセンテージに設定します。既定値は 60 (パーセント) です。このプロパティは、トークンの有効期間をパーセンテージで指定します。たとえば、発行されたトークンが 10 時間有効で、IssuedTokenRenewalThresholdPercentage が 80 に設定されている場合、このトークンは 8 時間後に更新されます。この値を 80% に設定する例を次に示します。
```
itcc.IssuedTokenRenewalThresholdPercentage = 80;
```
```
itcc.IssuedTokenRenewalThresholdPercentage = 80
```
トークンの有効期間と IssuedTokenRenewalThresholdPercentage 値によって決まる更新間隔は、キャッシュ時間が更新しきい時間よりも短い場合には、MaxIssuedTokenCachingTime 値によってオーバーライドされます。たとえば、IssuedTokenRenewalThresholdPercentage とトークンの有効期間を掛けた積が 8 時間であり、MaxIssuedTokenCachingTime 値が 10 分の場合、クライアントは、トークンの更新のために 10 分ごとにセキュリティトークンサービスに連絡します。
メッセージセキュリティやメッセージ資格情報付きトランスポートセキュリティを使用しないバインディング (たとえば、バインディングに SecurityBindingElement が存在しない場合) で CombinedEntropy 以外のキーエントロピモードが必要な場合は、DefaultKeyEntropyMode プロパティを適切な値に設定します。 "エントロピ" モードにより、DefaultKeyEntropyMode プロパティを使用して対称キーを制御できるかどうかが決まります。この既定値は CombinedEntropy であり、この場合、クライアントとトークン発行者の両方から、実際のキーを生成する際に組み合わせるデータが提供されます。これ以外の値は ClientEntropy と ServerEntropy であり、それぞれクライアントまたはサーバーによってキー全体が指定されます。サーバーのデータのみを使用してキーを指定するよう、このプロパティを設定する例を次に示します。
```
itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy;
```
```
itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy
```
Note

セキュリティトークンサービスまたはサービスバインディングに SecurityBindingElement が存在する場合、DefaultKeyEntropyMode で設定された IssuedTokenClientCredential は、KeyEntropyMode の SecurityBindingElement プロパティによってオーバーライドされます。
IssuerChannelBehaviors プロパティによって返されるコレクションに発行者固有のエンドポイント動作を追加して、これらの動作を構成します。
```
itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior);
```
```
itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior)
```

構成で IssuedTokenClientCredential を構成するには

エンドポイント動作で、<issuedToken> 要素の子として <issuedToken> 要素を作成します。
トークンキャッシュが不要な場合は、(<issuedToken> 要素の) cacheIssuedTokens 属性を false に設定します。
キャッシュされたトークンの制限時間が必要な場合は、<issuedToken> 要素の maxIssuedTokenCachingTime 属性を適切な値に設定します。次に例を示します。
<issuedToken maxIssuedTokenCachingTime='00:10:00' />
既定値以外の値にする場合は、<issuedToken> 要素の issuedTokenRenewalThresholdPercentage 属性を適切な値に設定します。次に例を示します。
```
<issuedToken issuedTokenRenewalThresholdPercentage = "80" />  
```
メッセージセキュリティやメッセージ資格情報付きトランスポートセキュリティを使用しないバインディングで CombinedEntropy 以外のキーエントロピモードが必要な場合 (たとえば、バインディングに SecurityBindingElement が存在しない場合) は、必要に応じて次のように defaultKeyEntropyMode 要素の <issuedToken> 属性を ServerEntropy または ClientEntropy に設定します。
```
<issuedToken defaultKeyEntropyMode = "ServerEntropy" />  
```
任意。 <issuedToken> 要素の子として <issuerChannelBehaviors> 要素を作成して、発行者固有のカスタムエンドポイント動作を構成します。各動作について、<issuerChannelBehaviors> 要素の子として <add> 要素を作成します。 <add> 要素の issuerAddress 属性を設定して、動作の発行者アドレスを指定します。 <add> 要素の behaviorConfiguration 属性を設定して、動作自体を指定します。
```
<issuerChannelBehaviors>  
<add issuerAddress="http://fabrikam.org/sts" behaviorConfiguration="FabrikamSTS" />  
</issuerChannelBehaviors>  
```

コードで X509CertificateRecipientClientCredential を構成するには

X509CertificateRecipientClientCredential クラスまたは ServiceCertificate プロパティの ClientCredentials プロパティが持つ ClientBase<TChannel> プロパティを介して、次のように ChannelFactory にアクセスします。
```
X509CertificateRecipientClientCredential rcc =
    client.ClientCredentials.ServiceCertificate;
```
```
Dim rcc As X509CertificateRecipientClientCredential = _
client.ClientCredentials.ServiceCertificate
```
特定のエンドポイントの証明書として X509Certificate2 インスタンスを使用できる場合は、Add プロパティによって返されるコレクションの ScopedCertificates メソッドを使用します。
```
rcc.ScopedCertificates.Add(new Uri("http://fabrikam.com/sts"), cert);
```
```
rcc.ScopedCertificates.Add(New Uri("http://fabrikam.com/sts"), cert)
```

X509Certificate2 インスタンスが使用できない場合は、次の例に示すように、SetScopedCertificate クラスの X509CertificateRecipientClientCredential メソッドを使用します。

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

構成で X509CertificateRecipientClientCredential を構成するには

その要素自体がエンドポイント動作の <clientCredentials> 要素の子である <serviceCertificate> 要素の子として、<scopedCertificates> 要素を作成します。
<add> 要素の子要素として <scopedCertificates> 要素を作成します。適切な証明書を参照するように storeLocation、storeName、x509FindType、findValue の各属性の値を指定します。次の例に示すように、targetUri 属性を、証明書が使用されるエンドポイントのアドレスを指定する値に設定します。
```
<scopedCertificates>  
 <add targetUri="http://fabrikam.com/sts"
      storeLocation="CurrentUser"  
      storeName="TrustedPeople"  
      x509FindType="FindBySubjectName"  
      findValue="FabrikamSTS" />  
</scopedCertificates>  
```

例

IssuedTokenClientCredential クラスのインスタンスをコードで構成する例を、次のコードサンプルに示します。

// 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 のセキュリティ

情報の漏えいを防ぐために、Svcutil.exe ツールを使用してフェデレーションエンドポイントからのメタデータを処理するクライアントでは、生成されたセキュリティトークンサービスアドレスが予期されたものであることを確認する必要があります。これが特に重要なのは、セキュリティトークンサービスが複数のエンドポイントを公開する場合です。この場合、Svcutil.exe ツールは、複数のエンドポイントうちの最初のエンドポイントを使用する構成ファイルを生成しますが、このエンドポイントは、クライアントが使用する必要のあるエンドポイントと異なる場合があるためです。

LocalIssuer が必要な場合

チェーン内の 2 番目から最後までのセキュリティトークンサービスによって発行者アドレスまたは発行者メタデータアドレスが指定されている場合、Svcutil.exe の既定の出力では、ローカル発行者が使用されません。クライアントで常にローカル発行者を使用する場合は、この点に注意が必要です。

IssuedTokenClientCredential クラスの LocalIssuerAddress、LocalIssuerBinding、LocalIssuerChannelBehaviors プロパティなどの設定方法については、「方法: ローカル発行者を設定する」を参照してください。

範囲指定された証明書

証明書ネゴシエーションを使用しないという一般的な理由により、任意のセキュリティトークンサービスとの通信用のサービス証明書を指定する必要がある場合は、ScopedCertificates クラスの X509CertificateRecipientClientCredential プロパティを使用して指定できます。 SetDefaultCertificate メソッドは、パラメーターとして Uri と X509Certificate2 を受け取ります。指定した証明書は、指定した URI のエンドポイントと通信するときに使用されます。または、SetScopedCertificate メソッドを使用して、ScopedCertificates プロパティによって返されるコレクションに証明書を追加することもできます。

Note

特定の URI に範囲指定された証明書というクライアントの概念は、該当する URI でエンドポイントを公開するサービスへの送信呼び出しを行うアプリケーションにだけ適用されます。これは、IssuedTokenServiceCredential クラスの KnownCertificates によって返されたコレクション内のサーバーで構成された証明書など、発行済みトークンの署名に使用される証明書には適用されません。詳細については、「方法: フェデレーションサービスで資格情報を設定する」を参照してください。

次の方法で共有

方法: フェデレーションクライアントを作成する

フェデレーションサービスの構成を生成し、確認するには

コードで IssuedTokenClientCredential を構成するには

構成で IssuedTokenClientCredential を構成するには

コードで X509CertificateRecipientClientCredential を構成するには

構成で X509CertificateRecipientClientCredential を構成するには

例

.NET Framework のセキュリティ

LocalIssuer が必要な場合

範囲指定された証明書

関連項目

その他のリソース

次の方法で共有

方法: フェデレーション クライアントを作成する

フェデレーション サービスの構成を生成し、確認するには

コードで IssuedTokenClientCredential を構成するには

構成で IssuedTokenClientCredential を構成するには

コードで X509CertificateRecipientClientCredential を構成するには

構成で X509CertificateRecipientClientCredential を構成するには

例

.NET Framework のセキュリティ

LocalIssuer が必要な場合

範囲指定された証明書

関連項目

その他のリソース

方法: フェデレーションクライアントを作成する

フェデレーションサービスの構成を生成し、確認するには