Passo a passo: criar credenciais de serviço e cliente personalizados

  • Artigo

Este tópico mostra como implementar credenciais personalizadas de cliente e serviço e como usar credenciais personalizadas do código do aplicativo.

Classes de extensibilidade de credenciais

As classes ClientCredentials e ServiceCredentials são os principais pontos de entrada para a extensibilidade de segurança do Windows Communication Foundation (WCF). Essas classes de credenciais fornecem as APIs que permitem que o código do aplicativo defina informações de credenciais e converta tipos de credenciais em tokens de segurança. (Tokens de segurança são o formulário usado para transmitir informações de credencial dentro de mensagens SOAP.) As responsabilidades dessas classes de credenciais podem ser divididas em duas áreas:

  • Forneça as APIs para aplicativos definirem informações de credenciais.

  • Executar como uma fábrica para implementações SecurityTokenManager.

As implementações padrão fornecidas no WCF dão suporte aos tipos de credenciais fornecidos pelo sistema e criam um gerenciador de tokens de segurança capaz de lidar com esses tipos de credenciais.

Motivos para personalizar

Há vários motivos para personalizar classes de credenciais de cliente ou de serviço. O principal é o requisito para alterar o comportamento de segurança padrão do WCF em relação ao tratamento dos tipos de credenciais fornecidos pelo sistema, principalmente pelos seguintes motivos:

  • Alterações que não são possíveis usando outros pontos de extensibilidade.

  • Adicionando novos tipos de credencial.

  • Adicionando novos tipos de token de segurança personalizados.

Este tópico descreve como implementar credenciais personalizadas de cliente e serviço e como usá-los do código do aplicativo.

Primeiro em uma série

Criar uma classe de credenciais personalizadas é apenas a primeira etapa, pois o motivo para personalizar credenciais é alterar o comportamento do WCF em relação ao provisionamento de credenciais, serialização de token de segurança ou autenticação. Outros tópicos nesta seção descrevem como criar serializadores e autenticadores personalizados. Nesse sentido, criar uma classe de credencial personalizada é o primeiro tópico da série. As ações subsequentes (criar serializadores e autenticadores personalizados) só podem ser feitas após a criação de credenciais personalizadas. Outros tópicos que se baseiam neste tópico incluem:

Procedimentos

Para implementar credenciais de cliente personalizadas

  1. Defina uma nova classe derivada da classe ClientCredentials.

  2. Opcional. Adicione novos métodos ou propriedades para novos tipos de credencial. Se você não adicionar novos tipos de credencial, ignore esta etapa. O exemplo a seguir adiciona uma propriedade CreditCardNumber.

  3. Substitua o método CreateSecurityTokenManager. Esse método é chamado automaticamente pela infraestrutura de segurança do WCF quando a credencial de cliente personalizada é usada. Esse método é responsável por criar e retornar uma instância de uma implementação da classe SecurityTokenManager.

    Importante

    É importante observar que o método CreateSecurityTokenManager é substituído para criar um gerenciador de token de segurança personalizado. O gerenciador de token de segurança, derivado de ClientCredentialsSecurityTokenManager, deve retornar um provedor de token de segurança personalizado, derivado de SecurityTokenProvider, para criar o token de segurança real. Se você não seguir esse padrão para criar tokens de segurança, seu aplicativo poderá funcionar incorretamente quando ChannelFactory objetos são armazenados em cache (que é o comportamento padrão para proxies de cliente do WCF), potencialmente resultando em um ataque de elevação de privilégio. O objeto de credencial personalizado é armazenado em cache como parte do ChannelFactory. No entanto, o SecurityTokenManager personalizado é criado em cada invocação, o que atenua a ameaça de segurança desde que a lógica de criação do token seja colocada no SecurityTokenManager.

  4. Substitua o método CloneCore.

    public class MyClientCredentials : ClientCredentials
{
    string creditCardNumber;

    public MyClientCredentials()
    {
        // Perform client credentials initialization.
    }

    protected MyClientCredentials(MyClientCredentials other)
        : base(other)
    {
        // Clone fields defined in this class.
        this.creditCardNumber = other.creditCardNumber;
    }

    public string CreditCardNumber
    {
        get
        {
            return this.creditCardNumber;
        }
        set
        {
            if (value == null)
            {
                throw new ArgumentNullException("value");
            }
            this.creditCardNumber = value;
        }
    }

    public override SecurityTokenManager CreateSecurityTokenManager()
    {
        // Return your implementation of the SecurityTokenManager.
        return new MyClientCredentialsSecurityTokenManager(this);
    }

    protected override ClientCredentials CloneCore()
    {
        // Implement the cloning functionality.
        return new MyClientCredentials(this);
    }
}

    Public Class MyClientCredentials
    Inherits ClientCredentials
    Private creditCardNumberValue As String

    Public Sub New()

    End Sub

    ' Perform client credentials initialization.    
    Protected Sub New(ByVal other As MyClientCredentials)
        MyBase.New(other)
        ' Clone fields defined in this class.
        Me.creditCardNumberValue = other.creditCardNumberValue

    End Sub

    Public Property CreditCardNumber() As String
        Get
            Return Me.creditCardNumberValue
        End Get
        Set
            If value Is Nothing Then
                Throw New ArgumentNullException("value")
            End If
            Me.creditCardNumberValue = value
        End Set
    End Property

    Public Overrides Function CreateSecurityTokenManager() As SecurityTokenManager
        ' Return your implementation of the SecurityTokenManager.
        Return New MyClientCredentialsSecurityTokenManager(Me)

    End Function

    Protected Overrides Function CloneCore() As ClientCredentials
        ' Implement the cloning functionality.
        Return New MyClientCredentials(Me)

    End Function
End Class

Para implementar um gerenciador de token de segurança do cliente personalizado

  1. Defina uma nova classe derivada de ClientCredentialsSecurityTokenManager.

  2. Opcional. Substitua o método CreateSecurityTokenProvider(SecurityTokenRequirement) se uma implementação personalizada SecurityTokenProvider precisar ser criada. Para obter mais informações sobre provedores de token de segurança personalizados, consulte Como criar um provedor de token de segurança personalizado.

  3. Opcional. Substitua o método CreateSecurityTokenAuthenticator(SecurityTokenRequirement, SecurityTokenResolver) se uma implementação personalizada SecurityTokenAuthenticator precisar ser criada. Para obter mais informações sobre autenticadores de token de segurança personalizados, consulte Como criar um autenticador de token de segurança personalizado.

  4. Opcional. Substitua o método CreateSecurityTokenSerializer se um SecurityTokenSerializer personalizado precisar ser criado. Para obter mais informações sobre tokens de segurança personalizados e serializadores de token de segurança personalizados, consulte Como criar um token personalizado.

    internal class MyClientCredentialsSecurityTokenManager :
    ClientCredentialsSecurityTokenManager
{
    MyClientCredentials credentials;

    public MyClientCredentialsSecurityTokenManager(MyClientCredentials credentials)
        : base(credentials)
    {
        this.credentials = credentials;
    }

    public override SecurityTokenProvider CreateSecurityTokenProvider(
        SecurityTokenRequirement tokenRequirement)
    {
        // Return your implementation of the SecurityTokenProvider, if required.
        // This implementation delegates to the base class.
        return base.CreateSecurityTokenProvider(tokenRequirement);
    }

    public override SecurityTokenAuthenticator CreateSecurityTokenAuthenticator(
        SecurityTokenRequirement tokenRequirement, out SecurityTokenResolver outOfBandTokenResolver)
    {
        // Return your implementation of the SecurityTokenAuthenticator, if required.
        // This implementation delegates to the base class.
        return base.CreateSecurityTokenAuthenticator(tokenRequirement, out outOfBandTokenResolver);
    }

    public override SecurityTokenSerializer CreateSecurityTokenSerializer(SecurityTokenVersion version)
    {
        // Return your implementation of the SecurityTokenSerializer, if required.
        // This implementation delegates to the base class.
        return base.CreateSecurityTokenSerializer(version);
    }
}

    
Friend Class MyClientCredentialsSecurityTokenManager
    Inherits ClientCredentialsSecurityTokenManager
    Private credentials As MyClientCredentials


    Public Sub New(ByVal credentials As MyClientCredentials)
        MyBase.New(credentials)
        Me.credentials = credentials

    End Sub


    Public Overrides Function CreateSecurityTokenProvider( _
    ByVal tokenRequirement As SecurityTokenRequirement) As SecurityTokenProvider
        ' Return your implementation of the SecurityTokenProvider, if required.
        ' This implementation delegates to the base class.
        Return MyBase.CreateSecurityTokenProvider(tokenRequirement)

    End Function


    Public Overrides Function CreateSecurityTokenAuthenticator( _
    ByVal tokenRequirement As SecurityTokenRequirement, _
    ByRef outOfBandTokenResolver As SecurityTokenResolver) As SecurityTokenAuthenticator
        ' Return your implementation of the SecurityTokenAuthenticator, if required.
        ' This implementation delegates to the base class.
        Return MyBase.CreateSecurityTokenAuthenticator(tokenRequirement, outOfBandTokenResolver)

    End Function


    Public Overrides Function CreateSecurityTokenSerializer(ByVal version As SecurityTokenVersion) _
    As SecurityTokenSerializer
        ' Return your implementation of the SecurityTokenSerializer, if required.
        ' This implementation delegates to the base class.
        Return MyBase.CreateSecurityTokenSerializer(version)

    End Function
End Class

Para usar credenciais de cliente personalizadas do código do aplicativo

  1. Crie uma instância do cliente gerado que representa a interface de serviço ou crie uma instância apontando ChannelFactory para um serviço com o qual você deseja se comunicar.

  2. Remova o comportamento das credenciais de cliente fornecidas pelo sistema da coleção Behaviors, que pode ser acessada por meio da propriedade Endpoint.

  3. Crie uma nova instância de uma classe de credenciais de cliente personalizada e adicione-a à coleção Behaviors, que pode ser acessada por meio da propriedade Endpoint.

    // Create a client with the client endpoint configuration.
CalculatorClient client = new CalculatorClient();

// Remove the ClientCredentials behavior.
client.ChannelFactory.Endpoint.Behaviors.Remove<ClientCredentials>();

// Add a custom client credentials instance to the behaviors collection.
client.ChannelFactory.Endpoint.Behaviors.Add(new MyClientCredentials());

    ' Create a client with the client endpoint configuration.
Dim client As New CalculatorClient()

' Remove the ClientCredentials behavior.
client.ChannelFactory.Endpoint.Behaviors.Remove(Of ClientCredentials)()

' Add a custom client credentials instance to the behaviors collection.
client.ChannelFactory.Endpoint.Behaviors.Add(New MyClientCredentials())

O procedimento anterior mostra como usar credenciais de cliente do código do aplicativo. As credenciais do WCF também podem ser configuradas usando o arquivo de configuração do aplicativo. O uso da configuração do aplicativo geralmente é preferível à codificação dura porque permite a modificação dos parâmetros do aplicativo sem precisar modificar a origem, a recompilação e a reimplantação.

O próximo procedimento descreve como fornecer suporte para a configuração de credenciais personalizadas.

Criando um manipulador de configuração para credenciais de cliente personalizadas

  1. Defina uma nova classe derivada de ClientCredentialsElement.

  2. Opcional. Adicione propriedades para todos os parâmetros de configuração adicionais que você deseja expor por meio da configuração do aplicativo. O exemplo a seguir adiciona uma propriedade chamada CreditCardNumber.

  3. Substitua a propriedade BehaviorType para retornar o tipo da classe de credenciais de cliente personalizada criada com o elemento de configuração.

  4. Substitua o método CreateBehavior. O método é responsável por criar e retornar uma instância da classe de credencial personalizada com base nas configurações carregadas do arquivo de configuração. Chame o método base ApplyConfiguration(ClientCredentials) desse método para recuperar as configurações de credenciais fornecidas pelo sistema carregadas em sua instância de credenciais de cliente personalizadas.

  5. Opcional. Se você adicionou propriedades adicionais na etapa 2, precisará substituir a propriedade Properties para registrar suas configurações adicionais para a estrutura de configuração reconhecê-las. Combine suas propriedades com as propriedades da classe base para permitir que as configurações fornecidas pelo sistema sejam configuradas por meio desse elemento de configuração de credenciais de cliente personalizado.

    public class MyClientCredentialsConfigHandler : ClientCredentialsElement
{
    ConfigurationPropertyCollection properties;

    public override Type BehaviorType
    {
        get { return typeof(MyClientCredentials); }
    }

    public string CreditCardNumber
    {
        get { return (string)base["creditCardNumber"]; }
        set
        {
            if (String.IsNullOrEmpty(value))
            {
                value = String.Empty;
            }
            base["creditCardNumber"] = value;
        }
    }

    protected override ConfigurationPropertyCollection Properties
    {
        get
        {
            if (this.properties == null)
            {
                ConfigurationPropertyCollection properties = base.Properties;
                properties.Add(new ConfigurationProperty(
                    "creditCardNumber",
                    typeof(System.String),
                    string.Empty,
                    null,
                    new StringValidator(0, 32, null),
                    ConfigurationPropertyOptions.None));
                this.properties = properties;
            }
            return this.properties;
        }
    }

    protected override object CreateBehavior()
    {
        MyClientCredentials creds = new MyClientCredentials();
        creds.CreditCardNumber = CreditCardNumber;
        base.ApplyConfiguration(creds);
        return creds;
    }
}

    
Public Class MyClientCredentialsConfigHandler
    Inherits ClientCredentialsElement
    Private propertiesValue As ConfigurationPropertyCollection


    Public Overrides ReadOnly Property BehaviorType() As Type
        Get
            Return GetType(MyClientCredentials)
        End Get
    End Property

    Public Property CreditCardNumber() As String
        Get
            Return CStr(MyBase.Item("creditCardNumber"))
        End Get
        Set
            If String.IsNullOrEmpty(value) Then
                value = String.Empty
            End If
            MyBase.Item("creditCardNumber") = value
        End Set
    End Property


    Protected Overrides ReadOnly Property Properties() As ConfigurationPropertyCollection
        Get
            If Me.propertiesValue Is Nothing Then
                Dim myProperties As ConfigurationPropertyCollection = MyBase.Properties
                myProperties.Add(New ConfigurationProperty( _
                "creditCardNumber", _
                GetType(System.String), _
                String.Empty, _
                Nothing, _
                New StringValidator(0, 32, Nothing), _
                ConfigurationPropertyOptions.None))
                Me.propertiesValue = myProperties
            End If
            Return Me.propertiesValue
        End Get
    End Property


    Protected Overrides Function CreateBehavior() As Object
        Dim creds As New MyClientCredentials()
        creds.CreditCardNumber = Me.CreditCardNumber
        MyBase.ApplyConfiguration(creds)
        Return creds

    End Function
End Class

Depois que você tiver a classe de manipulador de configuração, ela poderá ser integrada à estrutura de configuração do WCF. Isso permite que as credenciais personalizadas do cliente sejam usadas nos elementos de comportamento do ponto de extremidade do cliente, conforme mostrado no próximo procedimento.

Para registrar e usar um manipulador de configuração de credenciais de cliente personalizado na configuração do aplicativo

  1. Adicione um elemento <extensions> e um elemento <behaviorExtensions> ao arquivo de configuração.

  2. Adicione um elemento <add> ao elemento <behaviorExtensions> e defina o atributo name para um valor apropriado.

  3. Defina o atributo type como o nome de tipo totalmente qualificado. Inclua também o nome do assembly e outros atributos de assembly.

    <system.serviceModel>
  <extensions>
    <behaviorExtensions>
      <add name="myClientCredentials" type="Microsoft.ServiceModel.Samples.MyClientCredentialsConfigHandler, CustomCredentials, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
    </behaviorExtensions>
  </extensions>
</system.serviceModel>

  4. Depois de registrar o manipulador de configuração, o elemento de credenciais personalizadas pode ser usado dentro do mesmo arquivo de configuração em vez do elemento <clientCredentials> fornecido pelo sistema. Você pode usar as propriedades fornecidas pelo sistema e quaisquer novas propriedades adicionadas à implementação do manipulador de configuração. O exemplo a seguir define o valor de uma propriedade personalizada usando o atributo creditCardNumber.

    <behaviors>
  <endpointBehaviors>
    <behavior name="myClientCredentialsBehavior">
      <myClientCredentials creditCardNumber="123-123-123"/>
    </behavior>
  </endpointBehaviors>
</behaviors>

Para implementar credenciais de serviço personalizadas

  1. Defina uma nova classe derivada de ServiceCredentials.

  2. Opcional. Adicione novas propriedades para fornecer APIs para novos valores de credencial que estão sendo adicionados. Se você não adicionar novos valores de credencial, ignore esta etapa. O exemplo a seguir adiciona uma propriedade AdditionalCertificate.

  3. Substitua o método CreateSecurityTokenManager. Esse método é chamado automaticamente pela infraestrutura do WCF quando a credencial de cliente personalizada é usada. Esse método é responsável por criar e retornar uma instância de uma implementação da classe SecurityTokenManager (descrito no próximo procedimento).

  4. Opcional. Substitua o método CloneCore. Isso só será necessário se adicionar novas propriedades ou campos internos à implementação de credenciais de cliente personalizadas.

    public class MyServiceCredentials : ServiceCredentials
{
    X509Certificate2 additionalCertificate;

    public MyServiceCredentials()
    {
    }

    protected MyServiceCredentials(MyServiceCredentials other)
        : base(other)
    {
        this.additionalCertificate = other.additionalCertificate;
    }

    public X509Certificate2 AdditionalCertificate
    {
        get
        {
            return this.additionalCertificate;
        }
        set
        {
            if (value == null)
            {
                throw new ArgumentNullException("value");
            }
            this.additionalCertificate = value;
        }
    }

    public override SecurityTokenManager CreateSecurityTokenManager()
    {
        return base.CreateSecurityTokenManager();
    }

    protected override ServiceCredentials CloneCore()
    {
        return new MyServiceCredentials(this);
    }
}

    Public Class MyServiceCredentials
    Inherits ServiceCredentials
    Private additionalCertificateValue As X509Certificate2

    Public Sub New()

    End Sub

    Protected Sub New(ByVal other As MyServiceCredentials)
        MyBase.New(other)
        Me.additionalCertificate = other.additionalCertificate
    End Sub


    Public Property AdditionalCertificate() As X509Certificate2
        Get
            Return Me.additionalCertificateValue
        End Get
        Set
            If value Is Nothing Then
                Throw New ArgumentNullException("value")
            End If
            Me.additionalCertificateValue = value
        End Set
    End Property

    Public Overrides Function CreateSecurityTokenManager() As SecurityTokenManager
        Return MyBase.CreateSecurityTokenManager()

    End Function


    Protected Overrides Function CloneCore() As ServiceCredentials
        Return New MyServiceCredentials(Me)

    End Function
End Class

Para implementar um gerenciador de token de segurança do serviço personalizado

  1. Defina uma nova classe derivada da classe ServiceCredentialsSecurityTokenManager.

  2. Opcional. Substitua o método CreateSecurityTokenProvider se uma implementação personalizada SecurityTokenProvider precisar ser criada. Para obter mais informações sobre provedores de token de segurança personalizados, consulte Como criar um provedor de token de segurança personalizado.

  3. Opcional. Substitua o método CreateSecurityTokenAuthenticator se uma implementação personalizada SecurityTokenAuthenticator precisar ser criada. Para obter mais informações sobre autenticadores de token de segurança personalizados, consulte o tópico Como criar um autenticador de token de segurança personalizado.

  4. Opcional. Substitua o método CreateSecurityTokenSerializer(SecurityTokenVersion) se um SecurityTokenSerializer personalizado precisar ser criado. Para obter mais informações sobre tokens de segurança personalizados e serializadores de token de segurança personalizados, consulte Como criar um token personalizado.

    internal class MyServiceCredentialsSecurityTokenManager :
    ServiceCredentialsSecurityTokenManager
{
    MyServiceCredentials credentials;

    public MyServiceCredentialsSecurityTokenManager(MyServiceCredentials credentials)
        : base(credentials)
    {
        this.credentials = credentials;
    }

    public override SecurityTokenProvider CreateSecurityTokenProvider(SecurityTokenRequirement tokenRequirement)
    {
        // Return your implementation of SecurityTokenProvider, if required.
        // This implementation delegates to the base class.
        return base.CreateSecurityTokenProvider(tokenRequirement);
    }

    public override SecurityTokenAuthenticator CreateSecurityTokenAuthenticator(SecurityTokenRequirement tokenRequirement, out SecurityTokenResolver outOfBandTokenResolver)
    {
        // Return your implementation of SecurityTokenProvider, if required.
        // This implementation delegates to the base class.
        return base.CreateSecurityTokenAuthenticator(tokenRequirement, out outOfBandTokenResolver);
    }

    public override SecurityTokenSerializer CreateSecurityTokenSerializer(SecurityTokenVersion version)
    {
        // Return your implementation of SecurityTokenProvider, if required.
        // This implementation delegates to the base class.
        return base.CreateSecurityTokenSerializer(version);
    }
}

    Friend Class MyServiceCredentialsSecurityTokenManager
    Inherits ServiceCredentialsSecurityTokenManager
    Private credentials As MyServiceCredentials

    Public Sub New(ByVal credentials As MyServiceCredentials)
        MyBase.New(credentials)
        Me.credentials = credentials

    End Sub


    Public Overrides Function CreateSecurityTokenProvider(ByVal tokenRequirement As SecurityTokenRequirement) _
    As SecurityTokenProvider
        ' Return your implementation of SecurityTokenProvider, if required.
        ' This implementation delegates to the base class.
        Return MyBase.CreateSecurityTokenProvider(tokenRequirement)

    End Function

    Public Overrides Function CreateSecurityTokenAuthenticator( _
    ByVal tokenRequirement As SecurityTokenRequirement, _
    ByRef outOfBandTokenResolver As SecurityTokenResolver) _
    As SecurityTokenAuthenticator
        ' Return your implementation of SecurityTokenProvider, if required.
        ' This implementation delegates to the base class.
        Return MyBase.CreateSecurityTokenAuthenticator(tokenRequirement, outOfBandTokenResolver)

    End Function


    Public Overrides Function CreateSecurityTokenSerializer(ByVal version As SecurityTokenVersion) _
    As SecurityTokenSerializer
        ' Return your implementation of SecurityTokenProvider, if required.
        ' This implementation delegates to the base class.
        Return MyBase.CreateSecurityTokenSerializer(version)

    End Function
End Class

Para usar credenciais de serviço personalizadas do código do aplicativo

  1. Crie uma instância de ServiceHost.

  2. Remova o comportamento das credenciais de serviço fornecidas pelo sistema da coleção Behaviors.

  3. Crie uma nova instância da classe de credenciais de serviço personalizadas e adicione-a à coleção Behaviors.

    // Create a service host with a service type.
ServiceHost serviceHost = new ServiceHost(typeof(Service));

// Remove the default ServiceCredentials behavior.
serviceHost.Description.Behaviors.Remove<ServiceCredentials>();

// Add a custom service credentials instance to the collection.
serviceHost.Description.Behaviors.Add(new MyServiceCredentials());

    ' Create a service host with a service type.
Dim serviceHost As New ServiceHost(GetType(Service))

' Remove the default ServiceCredentials behavior.
serviceHost.Description.Behaviors.Remove(Of ServiceCredentials)()

' Add a custom service credentials instance to the collection.
serviceHost.Description.Behaviors.Add(New MyServiceCredentials())

Adicione suporte para configuração usando as etapas descritas anteriormente nos procedimentos “To create a configuration handler for custom client credentials” e “To register and use a custom client credentials configuration handler in the application configuration”. A única diferença é usar a classe ServiceCredentialsElement em vez da classe ClientCredentialsElement como uma classe base para o manipulador de configuração. Em seguida, o elemento de credencial de serviço personalizado pode ser usado onde quer que o elemento <serviceCredentials> fornecido pelo sistema seja usado.

Confira também