Поставщик маркеровToken Provider

В этом образце показано, как реализовать пользовательский поставщик маркеров.This sample demonstrates how to implement a custom token provider. Поставщик маркеров в Windows Communication Foundation (WCF) используется для предоставления учетных данных инфраструктуре безопасности.A token provider in Windows Communication Foundation (WCF) is used for supplying credentials to the security infrastructure. Поставщик токенов осуществляет общую проверку цели и выдает соответствующие учетные данные, чтобы инфраструктура безопасности смогла обеспечить защиту сообщения.The token provider in general examines the target and issues appropriate credentials so that the security infrastructure can secure the message. WCF поставляется с поставщиком маркеров диспетчера учетных данных по умолчанию.WCF ships with the default Credential Manager Token Provider. WCF также поставляется с поставщиком токена CardSpace.WCF also ships with a CardSpace token provider. Пользовательские поставщики маркеров полезны в следующих случаях:Custom token providers are useful in the following cases:

  • если используется хранилище учетных данных с которым эти поставщики не работают;If you have a credential store that these token providers cannot operate with.

  • Если вы хотите предоставить собственный настраиваемый механизм для преобразования учетных данных с точки, когда пользователь предоставляет сведения о том, когда клиентская платформа WCF использует учетные данные.If you want to provide your own custom mechanism for transforming the credentials from the point when the user provides the details to when the WCF client framework uses the credentials.

  • если строится пользовательский маркер.If you are building a custom token.

В этом образце показано, как построить поставщик пользовательских маркеров, преобразующий входные данные пользователя в другой формат.This sample shows how to build a custom token provider that transforms the input from the user into a different format.

Итак, этот образец демонстрирует следующее:To summarize, this sample demonstrates the following:

  • как клиент может проходить проверку подлинности с использованием пары "имя пользователя/пароль";How a client can authenticate using a username/password pair.

  • как настроить клиент с пользовательским поставщиком маркеров;How a client can be configured with a custom token provider.

  • как сервер может проверить учетные данные клиента с помощью пользовательского объекта UserNamePasswordValidator, проверяющего соответствие имени пользователя и пароля;How the server can validate the client credentials using a password with a custom UserNamePasswordValidator that validates that the username and password match.

  • как сервер проходит проверку подлинности на клиенте с использованием сертификата X.509.How the server is authenticated by the client using the server's X.509 certificate.

В данном образце также показано, как можно получить доступ к удостоверению вызывающего модуля после процесса проверки подлинности пользовательского маркера.This sample also shows how the caller's identity is accessible after the custom token authentication process.

Служба предоставляет одну конечную точку для взаимодействия со службой, определенной в файле конфигурации App.config.The service exposes a single endpoint for communicating with the service, defined using the App.config configuration file. Конечная точка состоит из адреса, привязки и контракта.The endpoint consists of an address, a binding, and a contract. Привязка настраивается с помощью стандартного элемента wsHttpBinding, который по умолчанию использует безопасность сообщений.The binding is configured with a standard wsHttpBinding, which uses message security by default. В этом образце стандартная привязка wsHttpBinding использует проверку подлинности имени пользователя клиента.This sample sets the standard wsHttpBinding to use client username authentication. Кроме того, служба настраивает сертификат службы с помощью поведения serviceCredentials.The service also configures the service certificate using the serviceCredentials behavior. Поведение serviceCredentials позволяет настроить сертификат службы.The serviceCredentials behavior allows you to configure a service certificate. Сертификат службы используется клиентом для проверки подлинности службы и обеспечения защиты сообщения.A service certificate is used by a client to authenticate the service and provide message protection. В следующей конфигурации делается ссылка на сертификат localhost, установленный во время установки образца, как описано в инструкциях по установке далее.The following configuration references the localhost certificate installed during the sample setup as described in the following setup instructions.

<system.serviceModel>
    <services>
      <service
          name="Microsoft.ServiceModel.Samples.CalculatorService"
          behaviorConfiguration="CalculatorServiceBehavior">
        <host>
          <baseAddresses>
            <!-- configure base address provided by host -->
            <add baseAddress ="http://localhost:8000/servicemodelsamples/service"/>
          </baseAddresses>
        </host>
        <!-- use base address provided by host -->
        <endpoint address=""
                  binding="wsHttpBinding"
                  bindingConfiguration="Binding1"
                  contract="Microsoft.ServiceModel.Samples.ICalculator" />
      </service>
    </services>

    <bindings>
      <wsHttpBinding>
        <binding name="Binding1">
          <security mode="Message">
            <message clientCredentialType="UserName" />
          </security>
        </binding>
      </wsHttpBinding>
    </bindings>

    <behaviors>
      <serviceBehaviors>
        <behavior name="CalculatorServiceBehavior">
          <serviceDebug includeExceptionDetailInFaults="False" />
          <!--
        The serviceCredentials behavior allows one to define a service certificate.
        A service certificate is used by a client to authenticate the service and provide message protection.
        This configuration references the "localhost" certificate installed during the setup instructions.
        -->
          <serviceCredentials>
            <serviceCertificate findValue="localhost" storeLocation="LocalMachine" storeName="My" x509FindType="FindBySubjectName" />
          </serviceCredentials>
        </behavior>
      </serviceBehaviors>
    </behaviors>
  </system.serviceModel>

Конфигурация конечной точки клиента состоит из имени конфигурации, абсолютного адреса конечной точки службы, привязки и контракта.The client endpoint configuration consists of a configuration name, an absolute address for the service endpoint, the binding, and the contract. Привязка клиента настраивается с помощью соответствующего режима (Mode) и типа (clientCredentialType) сообщения.The client binding is configured with the appropriate Mode and message clientCredentialType.

<system.serviceModel>
  <client>
    <endpoint name=""
              address="http://localhost:8000/servicemodelsamples/service"
              binding="wsHttpBinding"
              bindingConfiguration="Binding1"
              contract="Microsoft.ServiceModel.Samples.ICalculator">
    </endpoint>
  </client>

  <bindings>
    <wsHttpBinding>
      <binding name="Binding1">
        <security mode="Message">
          <message clientCredentialType="UserName" />
        </security>
      </binding>
    </wsHttpBinding>
  </bindings>
</system.serviceModel>

В следующих шагах показано, как разработать пользовательский поставщик маркеров и интегрировать его с платформой безопасности WCF:The following steps show how to develop a custom token provider and integrate it with the WCF security framework:

  1. Создание пользовательского поставщика маркеров.Write a custom token provider.

    В образце реализуется пользовательский поставщик маркеров, получающий имя пользователя и пароль.The sample implements a custom token provider that obtains the username and password. Пароль должен соответствовать данному имени пользователя.The password must match this username. Этот пользовательский поставщик маркеров приводится исключительно с целью демонстрации; его не рекомендуется использовать в реальном развертывании.This custom token provider is for demonstration purposes only and is not recommended for real world deployment.

    Для выполнения этой задачи пользовательский поставщик маркеров наследует класс SecurityTokenProvider и переопределяет метод GetTokenCore(TimeSpan).To perform this task, the custom token provider derives the SecurityTokenProvider class and overrides the GetTokenCore(TimeSpan) method. Этот метод создает и возвращает новый маркер UserNameSecurityToken.This method creates and returns a new UserNameSecurityToken.

    protected override SecurityToken GetTokenCore(TimeSpan timeout)
    {
        // obtain username and password from the user using console window
        string username = GetUserName();
        string password = GetPassword();
        Console.WriteLine("username: {0}", username);
    
        // return new UserNameSecurityToken containing information obtained from user
        return new UserNameSecurityToken(username, password);
    }
    
  2. Создание пользовательского диспетчера маркеров безопасности.Write custom security token manager.

    Класс SecurityTokenManager используется для создания объекта SecurityTokenProvider для конкретного конструктора SecurityTokenRequirement, который передается в него в методе CreateSecurityTokenProvider.The SecurityTokenManager is used to create SecurityTokenProvider for specific SecurityTokenRequirement that is passed to it in CreateSecurityTokenProvider method. Диспетчер маркеров безопасности также используется для создания структур проверки подлинности маркеров и сериализатора маркеров. В этом образце они не представлены.Security token manager is also used to create token authenticators and a token serializer, but those are not covered by this sample. В данном образце пользовательский диспетчер маркеров безопасности наследуется от класса ClientCredentialsSecurityTokenManager и переопределяет метод CreateSecurityTokenProvider, возвращающий пользовательский поставщик маркеров, когда переданные требования маркера указывают на запрос пользовательского поставщика.In this sample, the custom security token manager inherits from ClientCredentialsSecurityTokenManager class and overrides the CreateSecurityTokenProvider method to return custom username token provider when the passed token requirements indicate that username provider is requested.

    public class MyUserNameSecurityTokenManager : ClientCredentialsSecurityTokenManager
    {
        MyUserNameClientCredentials myUserNameClientCredentials;
    
        public MyUserNameSecurityTokenManager(MyUserNameClientCredentials myUserNameClientCredentials)
            : base(myUserNameClientCredentials)
        {
            this.myUserNameClientCredentials = myUserNameClientCredentials;
        }
    
        public override SecurityTokenProvider CreateSecurityTokenProvider(SecurityTokenRequirement tokenRequirement)
        {
            // if token requirement matches username token return custom username token provider
            // otherwise use base implementation
            if (tokenRequirement.TokenType == SecurityTokenTypes.UserName)
            {
                return new MyUserNameTokenProvider();
            }
            else
            {
                return base.CreateSecurityTokenProvider(tokenRequirement);
            }
        }
    }
    
  3. Создание пользовательских учетных данных клиента.Write a custom client credential.

    Класс учетных данных клиента используется для представления учетных данных, которые сконфигурированы для прокси клиента, и создает диспетчер маркеров безопасности, который используется для получения структур проверки подлинности маркеров, поставщиков маркеров и сериализаторов маркеров.Client credentials class is used to represent the credentials that are configured for the client proxy and creates security token manager that is used to obtain token authenticators, token providers and a token serializer.

    public class MyUserNameClientCredentials : ClientCredentials
    {
        public MyUserNameClientCredentials()
            : base()
        {
        }
    
        protected override ClientCredentials CloneCore()
        {
            return new MyUserNameClientCredentials();
        }
    
        public override SecurityTokenManager CreateSecurityTokenManager()
        {
            // return custom security token manager
            return new MyUserNameSecurityTokenManager(this);
        }
    }
    
  4. Настройка клиента для использования пользовательских учетных данных клиента.Configure the client to use the custom client credential.

    Чтобы клиент мог использовать пользовательские учетные данные клиента, образец удаляет класс учетных данных клиента по умолчанию и предоставляет новый класс учетных данных клиента.In order for the client to use the custom client credential, the sample deletes the default client credential class and supplies the new client credential class.

    static void Main()
    {
        // ...
           // Create a client with given client endpoint configuration
          CalculatorClient client = new CalculatorClient();
    
          // set new credentials
           client.ChannelFactory.Endpoint.Behaviors.Remove(typeof(ClientCredentials));
         client.ChannelFactory.Endpoint.Behaviors.Add(new MyUserNameClientCredentials());
       // ...
    }
    

На стороне службы для вывода информации о вызывающем модуле можно использовать свойство PrimaryIdentity, как показано в следующем примере кода.On the service, to display the caller's information, use the PrimaryIdentity as shown in the following code example. Свойство Current содержит информацию об утверждениях о текущем вызывающем модуле.The Current contains claims information about the current caller.

static void DisplayIdentityInformation()
{
    Console.WriteLine("\t\tSecurity context identity  :  {0}",
        ServiceSecurityContext.Current.PrimaryIdentity.Name);
}

При выполнении примера запросы и ответы операций отображаются в окне консоли клиента.When you run the sample, the operation requests and responses are displayed in the client console window. Чтобы закрыть клиент, нажмите клавишу ВВОД в окне клиента.Press ENTER in the client window to shut down the client.

Пакетный файл SetupSetup Batch File

Входящий в состав образца файл Setup.bat позволяет настроить для сервера соответствующий сертификат, необходимый для выполнения резидентного приложения, для которого требуется обеспечение безопасности на основе сертификата сервера.The Setup.bat batch file included with this sample allows you to configure the server with the relevant certificate to run a self-hosted application that requires server certificate-based security. Этот пакетный файл необходимо изменить, чтобы его можно было использовать на нескольких компьютерах или без размещения приложения.This batch file must be modified to work across computers or to work in a non-hosted case.

Ниже представлен краткие общие сведения о различных разделах пакетных файлов, позволяющий изменять их для выполнения в соответствующей конфигурации.The following provides a brief overview of the different sections of the batch files so that they can be modified to run in the appropriate configuration:

  • Создание сертификата сервера.Creating the server certificate.

    Следующие строки из файла Setup.bat создают используемый в дальнейшем сертификат сервера.The following lines from the Setup.bat batch file create the server certificate to be used. Переменная %SERVER_NAME%задает имя сервера.The %SERVER_NAME% variable specifies the server name. Измените эту переменную, чтобы задать собственное имя сервера.Change this variable to specify your own server name. По умолчанию в этом пакетном файле используется имя localhost.The default value in this batch file is localhost.

    echo ************
    echo Server cert setup starting
    echo %SERVER_NAME%
    echo ************
    echo making server cert
    echo ************
    makecert.exe -sr LocalMachine -ss MY -a sha1 -n CN=%SERVER_NAME% -sky exchange -pe
    
  • Установка сертификата сервера в хранилище доверенных сертификатов клиента.Installing the server certificate into the client's trusted certificate store:

    Следующие строки из файла Setup.bat копируют сертификат сервера в хранилище доверенных лиц клиента.The following lines in the Setup.bat batch file copy the server certificate into the client trusted people store. Этот шаг является обязательным, поскольку сертификаты, созданные с помощью программы Makecert.exe, не получают неявного доверия со стороны клиентской системы.This step is required because certificates generated by Makecert.exe are not implicitly trusted by the client system. Если уже имеется сертификат, имеющий доверенный корневой сертификат клиента, например сертификат, выпущенный корпорацией Майкрософт, выполнять этот шаг по добавлению сертификата сервера в хранилище сертификатов клиента не требуется.If you already have a certificate that is rooted in a client trusted root certificate—for example, a Microsoft issued certificate—this step of populating the client certificate store with the server certificate is not required.

    certmgr.exe -add -r LocalMachine -s My -c -n %SERVER_NAME% -r CurrentUser -s TrustedPeople
    

Примечание

Пакетный файл Setup.bat предназначен для запуска из командной строки Windows SDK.The Setup.bat batch file is designed to be run from a Windows SDK Command Prompt. Требуется, чтобы переменная среды MSSDK указывала на каталог, в котором установлен пакет SDK.It requires that the MSSDK environment variable point to the directory where the SDK is installed. Эта переменная среды автоматически устанавливается в командной строке Windows SDK.This environment variable is automatically set within a Windows SDK Command Prompt.

Настройка и сборка образцаTo set up and build the sample

  1. Убедитесь, что вы выполнили однократную процедуру настройки для Windows Communication Foundation примеров.Ensure that you have performed the One-Time Setup Procedure for the Windows Communication Foundation Samples.

  2. Чтобы выполнить сборку решения, следуйте инструкциям в разделе Создание примеров Windows Communication Foundation.To build the solution, follow the instructions in Building the Windows Communication Foundation Samples.

Запуск образца на одном компьютереTo run the sample on the same computer

  1. Запустите Setup.bat из папки образца установки в командной строке Visual Studio 2012, открытой с правами администратора.Run Setup.bat from the sample installation folder inside a Visual Studio 2012 command prompt opened with administrator privileges. При этом устанавливаются все сертификаты, необходимые для выполнения образца.This installs all the certificates required for running the sample.

    Примечание

    Пакетный файл Setup.bat предназначен для запуска из командной строки Visual Studio 2012.The Setup.bat batch file is designed to be run from a Visual Studio 2012 Command Prompt. Переменная среды PATH, заданная в командной строке Visual Studio 2012, указывает на каталог, содержащий исполняемые файлы, необходимые для скрипта Setup.bat.The PATH environment variable set within the Visual Studio 2012 Command Prompt points to the directory that contains executables required by the Setup.bat script.

  2. Запустите программу Service.exe из каталога \service\bin.Launch service.exe from service\bin.

  3. Запустите программу Client.exe из каталога \client\bin.Launch Client.exe from \client\bin. Действия клиента отображаются в консольном приложении клиента.Client activity is displayed on the client console application.

  4. При запросе имени пользователя введите имя пользователя.At the username prompt, type a user name.

  5. При запросе пароля используйте ту же строку, которая была введена при запросе имени пользователя.At the password prompt, use the same string that was typed for the username prompt.

  6. Если клиент и служба не могут обмениваться данными, см. раздел Советы по устранению неполадок для примеров WCF.If the client and service are not able to communicate, see Troubleshooting Tips for WCF Samples.

Запуск образца на нескольких компьютерахTo run the sample across computers

  1. Создайте на компьютере службы каталог для двоичных файлов службы.Create a directory on the service computer for the service binaries.

  2. Скопируйте файлы служебной программы в каталог службы на компьютере службы.Copy the service program files to the service directory on the service computer. Кроме того, скопируйте файлы Setup.bat и Cleanup.bat на компьютер службы.Also copy the Setup.bat and Cleanup.bat files to the service computer.

  3. Необходимо иметь сертификат сервера с именем субъекта, содержащим полное имя домена компьютера.You must have a server certificate with the subject name that contains the fully-qualified domain name of the computer. Для отображения этого нового имени сертификата необходимо обновить файл Service.exe.config.The Service.exe.config file must be updated to reflect this new certificate name. Сертификат сервера можно создать путем изменения пакетного файла Setup.bat.You can create server certificate by modifying the Setup.bat batch file. Обратите внимание, что файл setup.bat должен быть запущен из Командная строка разработчика для Visual Studio, открытой с правами администратора.Note that the setup.bat file must be run from a Developer Command Prompt for Visual Studio opened with administrator privileges. Необходимо присвоить переменной %SERVER_NAME% полное имя узла компьютера, используемого для размещения службы.You must set %SERVER_NAME% variable to fully-qualified host name of the computer that is used to host the service.

  4. Скопируйте сертификат сервера в хранилище CurrentUser-TrustedPeople клиента.Copy the server certificate into the CurrentUser-TrustedPeople store of the client. Это нужно делать, когда сертификат сервера выдан издателем, которому доверяет клиент.You do not need to do this when the server certificate is issued by a client trusted issuer.

  5. В файле Service.exe.config компьютера службы измените значение базового адреса для указания полного имени компьютера вместо localhost.In the Service.exe.config file on the service computer, change the value of the base address to specify a fully-qualified computer name instead of localhost.

  6. На компьютере службы запустите из командной строки программу service.exe.On the service computer, run service.exe from a command prompt.

  7. Скопируйте на клиентские компьютеры файлы из папки \client\bin\ в папку языка.Copy the client program files from the \client\bin\ folder, under the language-specific folder, to the client computer.

  8. В файле Client.exe.config на клиентском компьютере измените значение адреса конечной точки, чтобы оно соответствовало новому адресу службы.In the Client.exe.config file on the client computer, change the address value of the endpoint to match the new address of your service.

  9. На клиентском компьютере из командной строки запустите программу Client.exe.On the client computer, launch Client.exe from a command prompt window.

  10. Если клиент и служба не могут обмениваться данными, см. раздел Советы по устранению неполадок для примеров WCF.If the client and service are not able to communicate, see Troubleshooting Tips for WCF Samples.

Очистка после образцаTo clean up after the sample

  1. После завершения работы примера запустите в папке примеров файл Cleanup.bat.Run Cleanup.bat in the samples folder once you have finished running the sample.