Como: Criar um cliente federado

Artigo
03/05/2024

No Windows Communication Foundation (WCF), a criação de um cliente para um serviço federado consiste em três etapas principais:

Configure uma <associação wsFederationHttpBinding> ou uma associação personalizada semelhante. Para obter mais informações sobre como criar uma associação apropriada, consulte Como criar um WSFederationHttpBinding. Como alternativa, execute a ServiceModel Metadata Utility Tool (Svcutil.exe) no ponto de extremidade de metadados do serviço federado para gerar um arquivo de configuração para comunicação com o serviço federado e um ou mais serviços de token de segurança.
Defina as propriedades do que controla IssuedTokenClientCredential vários aspetos da interação de um cliente com um serviço de token de segurança.
Defina as propriedades do , que permite que os X509CertificateRecipientClientCredentialcertificados necessários se comuniquem com segurança com determinados pontos de extremidade, como serviços de token de segurança.

Nota

Um CryptographicException pode ser lançado quando um cliente usa credenciais representadas, a WSFederationHttpBinding associação ou um token emitido de forma personalizada e chaves assimétricas. As chaves assimétricas são usadas com os WSFederationHttpBinding tokens de vinculação e emitidos sob medida quando as IssuedKeyType propriedades e KeyType são definidas como AsymmetricKey. O CryptographicException é lançado quando o cliente tenta enviar uma mensagem e um perfil de usuário não existe para a identidade que o cliente está representando. Para atenuar esse problema, faça logon no computador cliente ou ligue LoadUserProfile antes de enviar a mensagem.

Este tópico fornece informações detalhadas sobre esses procedimentos. Para obter mais informações sobre como criar uma associação apropriada, consulte Como criar um WSFederationHttpBinding. Para obter mais informações sobre como um serviço federado funciona, consulte Federação.

Para gerar e examinar a configuração de um serviço federado

Execute a ServiceModel Metadata Utility Tool (Svcutil.exe) com o endereço da URL de metadados do serviço como um parâmetro de linha de comando.
Abra o arquivo de configuração gerado em um editor apropriado.
Examine os atributos e o conteúdo de quaisquer elementos de metadados gerados <pelo> emissor e <pelo emitente.> Eles estão localizados dentro dos elementos de segurança> para os< elementos wsFederationHttpBinding> ou ligações personalizadas.< Certifique-se de que os endereços contêm os nomes de domínio esperados ou outras informações de endereço. É importante verificar essas informações porque o cliente se autentica nesses endereços e pode divulgar informações como pares de nome de usuário/senha. Se o endereço não for o endereço esperado, isso pode resultar na divulgação de informações para um destinatário não intencional.
Examine quaisquer elementos issuedTokenParameters> adicionais <dentro do elemento comentado<alternativeIssuedTokenParameters>. Ao usar a ferramenta Svcutil.exe para gerar configuração para um serviço federado, se o serviço federado ou quaisquer serviços de token de segurança intermediários não especificarem um endereço de emissor, mas especificarem um endereço de metadados para um serviço de token de segurança que exponha vários pontos de extremidade, o arquivo de configuração resultante se refere ao primeiro ponto de extremidade. Pontos de extremidade adicionais estão no arquivo de configuração como elementos comentados <alternativeIssuedTokenParameters> .

Determine se um deles <issuedTokenParameters> é preferível ao já presente na configuração. Por exemplo, o cliente pode preferir autenticar-se em um serviço de token de segurança usando um token do Windows CardSpace em vez de um par de nome de usuário/senha.

Nota

Quando vários serviços de token de segurança devem ser percorridos antes de se comunicar com o serviço, é possível que um serviço de token de segurança intermediário direcione o cliente para um serviço de token de segurança incorreto. Portanto, certifique-se de que o ponto de extremidade para o serviço de token de segurança no <issuedTokenParameters> é o serviço de token de segurança esperado e não um serviço de token de segurança desconhecido.

Para configurar um IssuedTokenClientCredential no código

Acesse a IssuedTokenClientCredential propriedade through da IssuedToken classe (retornada pela ClientCredentials propriedade da classe ou através da ChannelFactory classe), conforme mostrado no código de ClientCredentials ClientBase<TChannel> exemplo a seguir.
```
IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;
```
```
Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken
```
Se o cache de token não for necessário, defina a CacheIssuedTokens propriedade como false. A CacheIssuedTokens propriedade controla se esses tokens de um serviço de token de segurança são armazenados em cache. Se essa propriedade estiver definida como false, o cliente solicitará um novo token do serviço de token de segurança sempre que precisar se autenticar novamente no serviço federado, independentemente de um token anterior ainda ser válido. Se essa propriedade estiver definida como true, o cliente reutilizará um token existente sempre que precisar se autenticar novamente no serviço federado (desde que o token não tenha expirado). A predefinição é true.
Se for necessário um limite de tempo em tokens armazenados em cache, defina a MaxIssuedTokenCachingTime propriedade como um TimeSpan valor. A propriedade especifica por quanto tempo um token pode ser armazenado em cache. Após o período de tempo especificado, o token é removido do cache do cliente. Por padrão, os tokens são armazenados em cache indefinidamente. O exemplo a seguir define o período de tempo como 10 minutos.
```
itcc.MaxIssuedTokenCachingTime = new TimeSpan(0, 10, 0);
```
```
itcc.MaxIssuedTokenCachingTime = New TimeSpan(0, 10, 0)
```
Opcional. Defina o IssuedTokenRenewalThresholdPercentage como uma porcentagem. O padrão é 60 (por cento). A propriedade especifica uma porcentagem do período de validade do token. Por exemplo, se o token emitido for válido por 10 horas e IssuedTokenRenewalThresholdPercentage estiver definido como 80, o token será renovado após oito horas. O exemplo a seguir define o valor como 80%.
```
itcc.IssuedTokenRenewalThresholdPercentage = 80;
```
```
itcc.IssuedTokenRenewalThresholdPercentage = 80
```
O intervalo de renovação determinado pelo período de validade do token e o IssuedTokenRenewalThresholdPercentage valor são substituídos MaxIssuedTokenCachingTime pelo valor nos casos em que o tempo de cache é menor do que o tempo limite de renovação. Por exemplo, se o produto e a duração do token for de oito horas e o MaxIssuedTokenCachingTime valor for de 10 minutos, o cliente contata o serviço de token de IssuedTokenRenewalThresholdPercentage segurança para obter um token atualizado a cada 10 minutos.
Se um modo de entropia de chave diferente do CombinedEntropy necessário em uma associação que não usa segurança de mensagem ou segurança de transporte com credenciais de mensagem (por exemplo, a associação não tem um SecurityBindingElement), defina a DefaultKeyEntropyMode propriedade como um valor apropriado. O modo de entropia determina se as chaves simétricas podem ser controladas usando a DefaultKeyEntropyMode propriedade. Esse padrão é CombinedEntropy, onde o cliente e o emissor do token fornecem dados que são combinados para produzir a chave real. Outros valores são ClientEntropy e ServerEntropy, o que significa que toda a chave é especificada pelo cliente ou pelo servidor, respectivamente. O exemplo a seguir define a propriedade para usar apenas os dados do servidor para a chave.
```
itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy;
```
```
itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy
```
Nota

Se um SecurityBindingElement estiver presente em um serviço de token de segurança ou vinculação de serviço, o DefaultKeyEntropyMode conjunto em IssuedTokenClientCredential será substituído pela KeyEntropyMode propriedade do SecurityBindingElement.
Configure quaisquer comportamentos de ponto de extremidade específicos do emissor adicionando-os à coleção retornada IssuerChannelBehaviors pela propriedade.
```
itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior);
```
```
itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior)
```

Para configurar o IssuedTokenClientCredential na configuração

Crie um <elemento issuedToken> como filho do <elemento issuedToken> em um comportamento de ponto de extremidade.
Se o <issuedToken> cache de token não for necessário, defina o cacheIssuedTokens atributo (do elemento ) como false.
Se for necessário um limite de tempo em tokens armazenados em cache, defina o maxIssuedTokenCachingTime <issuedToken> atributo no elemento para um valor apropriado. Por exemplo: <issuedToken maxIssuedTokenCachingTime='00:10:00' />
Se preferir um valor diferente do padrão, defina o issuedTokenRenewalThresholdPercentage <issuedToken> atributo no elemento como um valor apropriado, por exemplo:
```
<issuedToken issuedTokenRenewalThresholdPercentage = "80" />
```
Se um modo de entropia de chave diferente estiver CombinedEntropy em uma associação que não usa segurança de mensagem ou segurança de transporte com credenciais de mensagem (por exemplo, a associação não tem um SecurityBindingElement), defina o <issuedToken> defaultKeyEntropyMode atributo no elemento como um ou ClientEntropy ServerEntropy conforme necessário.
```
<issuedToken defaultKeyEntropyMode = "ServerEntropy" />
```
Opcional. Configure qualquer comportamento de ponto de extremidade personalizado específico do emissor criando um <issuerChannelBehaviors> elemento como filho do <issuedToken> elemento. Para cada comportamento, crie um <add> elemento como filho do <issuerChannelBehaviors> elemento. Especifique o endereço do emissor do comportamento definindo o issuerAddress <add> atributo no elemento . Especifique o comportamento em si definindo o behaviorConfiguration <add> atributo no elemento .
```
<issuerChannelBehaviors>
<add issuerAddress="http://fabrikam.org/sts" behaviorConfiguration="FabrikamSTS" />
</issuerChannelBehaviors>
```

Para configurar um X509CertificateRecipientClientCredential no código

Aceda ao X509CertificateRecipientClientCredential através da ServiceCertificate propriedade da ClientCredentials propriedade da ClientBase<TChannel> classe ou da ChannelFactory propriedade.

X509CertificateRecipientClientCredential rcc =
    client.ClientCredentials.ServiceCertificate;

Dim rcc As X509CertificateRecipientClientCredential = _
client.ClientCredentials.ServiceCertificate

Se uma X509Certificate2 instância estiver disponível para o certificado para um determinado ponto de extremidade, use o Add método da coleção retornada pela ScopedCertificates propriedade.
```
rcc.ScopedCertificates.Add(new Uri("http://fabrikam.com/sts"), cert);
```
```
rcc.ScopedCertificates.Add(New Uri("http://fabrikam.com/sts"), cert)
```

Se uma X509Certificate2 instância não estiver disponível, use o SetScopedCertificate X509CertificateRecipientClientCredential método da classe como mostrado no exemplo a seguir.

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

Para configurar um X509CertificateRecipientClientCredential na configuração

Crie um <elemento scopedCertificates> como filho do< elemento serviceCertificate> que é, ele próprio, filho do <elemento clientCredentials> em um comportamento de ponto de extremidade.
Crie um <add> elemento como filho do <scopedCertificates> elemento. Especifique valores para os storeLocationatributos , storeName, x509FindTypee para findValue fazer referência ao certificado apropriado. Defina o targetUri atributo como um valor que forneça o endereço do ponto de extremidade para o qual o certificado deve ser usado, conforme mostrado no exemplo a seguir.
```
<scopedCertificates>
 <add targetUri="http://fabrikam.com/sts"
      storeLocation="CurrentUser"
      storeName="TrustedPeople"
      x509FindType="FindBySubjectName"
      findValue="FabrikamSTS" />
</scopedCertificates>
```

Exemplo

O exemplo de código a seguir configura uma instância da IssuedTokenClientCredential classe no código.

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

Segurança do .NET Framework

Para evitar a possível divulgação de informações, os clientes que estão executando a ferramenta Svcutil.exe para processar metadados de pontos de extremidade federados devem garantir que os endereços de serviço de token de segurança resultantes sejam os esperados. Isso é especialmente importante quando um serviço de token de segurança expõe vários pontos de extremidade, porque a ferramenta Svcutil.exe gera o arquivo de configuração resultante para usar o primeiro desses pontos de extremidade, que pode não ser aquele que o cliente deveria estar usando.

LocalIssuer necessário

Se for esperado que os clientes sempre usem um emissor local, observe o seguinte: a saída padrão de Svcutil.exe resulta no não uso do emissor local se o penúltimo serviço de token de segurança na cadeia especificar um endereço de emissor ou endereço de metadados do emissor.

Para obter mais informações sobre como definir as LocalIssuerAddresspropriedades , LocalIssuerBindinge LocalIssuerChannelBehaviors da classe, consulte Como configurar um emissor local.IssuedTokenClientCredential

Certificados com escopo

Se os certificados de serviço precisarem ser especificados para comunicação com qualquer um dos serviços de token de segurança, normalmente porque a negociação de certificados não está sendo usada, eles podem ser especificados usando a ScopedCertificates X509CertificateRecipientClientCredential propriedade da classe. O SetDefaultCertificate método leva a Uri e um X509Certificate2 como parâmetros. O certificado especificado é usado ao se comunicar com pontos de extremidade no URI especificado. Como alternativa, você pode usar o SetScopedCertificate método para adicionar um certificado à coleção retornada ScopedCertificates pela propriedade.