В комплект поставки Windows® Identity Foundation (WIF) входит программа FedUtil.exe. Она позволяет устанавливать доверие приложения проверяющей стороны к службам маркеров безопасности (STS). С ее помощью можно делать следующее:

В последующих разделах показано, как выполнять эти задачи с помощью FedUtil. Эти же задачи можно выполнять вручную, внося соответствующие изменения в файл web.config приложения проверяющей стороны (что и делает FedUtil).

Примечание.
Поскольку FedUtil изменяет файл конфигурации, это может привести к изменению существующей конфигурации безопасности приложения. Хотя FedUtil не удаляет ненужные разделы файла, а преобразует их в комментарии, после завершения работы FedUtil необходимо просмотреть файл конфигурации и убедиться, что в нем не оказались закомментированы строки с данными безопасности, от которых зависит работа приложения. Следует также иметь в виду, что FedUtil создает резервную копию имеющегося файла конфигурации.

1. Создание локальной службы STS

В этом упражнении создается локальная служба STS для совместного использования с приложением проверяющей стороны ASP.NET, поддерживающим утверждения. Для этого необходимо будет запустить FedUtil в среде Visual Studio. В данном случае разрабатывается приложение проверяющей стороны ASP.NET, поддерживающее утверждения, со службой STS, не предназначенной для использования в производственной среде. Ниже будет показано, как переключиться на службу STS для производственной среды.

Примечание.
Для корректной работы FedUtil необходимо запустить Visual Studio в режиме с повышенными правами.

В Visual Studio откройте меню "Файл" и выберите "Создать", "Веб-сайт". Выберите пункт "Веб-сайт ASP.NET с поддержкой утверждений".

Затем щелкните правой кнопкой мыши проект в обозревателе решений и выберите команду "Добавить ссылку на службу STS".

Откроется программа FedUtil. Откроется диалоговое окно FedUtil со страницей приветствия служебной программы федерации:

На этой странице необходимо заполнить два поля:

  1. Расположение конфигурации приложения: укажите путь к файлу web.config службы . Если программа FedUtil запущена не из Visual Studio или из меню "Сервис" в Visual Studio без открытия проекта, это поле будет пустым. Если программа FedUtil запущена из контекстного меню проекта в Visual Studio, данное поле уже будет содержать путь к файлу web.config этого проекта. Файл web.config должен к этому моменту существовать и находиться в состоянии по умолчанию (в том, в каком он был создан средствами Visual Studio). Если программа FedUtil запускается несколько раз для одного и того же файла web.config, она будет просто перезаписывать содержимое, добавляемое в web.config.

  2. URI приложения: укажите универсальный код ресурса (URI) службы ASP.NET. Следует иметь в виду, что это SVC-файл. Если программа FedUtil запущена не из Visual Studio или из меню "Сервис" в Visual Studio без открытия проекта, это поле будет пустым. Если программа FedUtil запущена из контекстного меню проекта в Visual Studio, данное поле будет содержать два кода URI для этого проекта: один с именем localhost и другой с полным доменным именем данного компьютера (если оно определено). Этот код URI используется в качестве значения области при настройке приложения для поддержки утверждений. Он также используется в качестве первого URI аудитории. Если требуется задать дополнительные URI аудитории, это необходимо сделать вручную. Если код URI не является безопасным (т. е. не начинается с https://), при нажатии кнопки "Далее" появится соответствующее предупреждение.

После ввода необходимых сведений нажмите кнопку "Далее". Откроется страница "Служба STS". Выберите параметр "Создать проект службы STS в текущем решении".

Следует иметь в виду, что если программа FedUtil запущена не из Visual Studio или из меню "Сервис" в Visual Studio без открытия проекта, параметр "Создать проект службы STS в текущем решении" будет недоступен.

Нажмите кнопку "Далее". Откроется страница "Сводка".

На странице "Сводка" отображаются данные, введенные в диалоговом окне "Сведения о приложении", сведения о создания службы STS, утверждения, запрашиваемые приложением, и изменения, которые FedUtil внесет в конфигурацию приложения.

Нажмите кнопку "Готово".

Если сейчас открыть файл web.config, можно увидеть, что он изменен программой FedUtil:

  • Добавлены следующие настройки приложения:

      Копировать код 
    <appSettings> <add key="FederationMetadataLocation" value="C:\inetpub\wwwroot\ClaimsAwareWebSite1_STS\FederationMetadata\2007-06\FederationMetadata.xml" /> </appSettings>
  • Всем пользователям предоставлен доступ к метаданным федерации:

      Копировать код 
    <location path="FederationMetadata"> <system.web> <authorization> <allow users="*" /> </authorization> </system.web> </location>
  • В элемент <system.Web>/<httpModules> добавляются элементы WSFederationAuthenticationModule и SessionAuthenticationModule:

      Копировать код 
    <httpModules> ... <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> </httpModules>
  • Эти же элементы также добавляются в элемент <system.webServer>/<modules>:

      Копировать код 
    <system.webServer> ... <modules> <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> </modules> ... </system.webServer>
  • Наконец, в элемент <microsoft.identityModel>/<service> вносятся следующие изменения:

      Копировать код 
    <microsoft.identityModel> <service> <audienceUris> <add value="http://localhost:58496/ClaimsAwareWebSite2/" /> </audienceUris> <federatedAuthentication enabled="true"> <wsFederation passiveRedirectEnabled="true" issuer="http://localhost:58497/ClaimsAwareWebSite2_STS/" realm="http://localhost:58496/ClaimsAwareWebSite2/" requireHttps="false" /> <cookieHandler requireSsl="false" /> </federatedAuthentication> <applicationService> <claimTypeRequired> <claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="http://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" /> </claimTypeRequired> </applicationService> <issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"> <trustedIssuers> <add thumbprint="0E2A9EB75F1AFC321790407FA4B130E0E4E223E2" name="CN=STSTestCert" /> </trustedIssuers> </issuerNameRegistry> </service> </microsoft.identityModel>
    • Добавляется элемент <audienceUris>, в котором указывается код URI приложения проверяющей стороны ASP.NET, поддерживающего утверждения.

    • Добавляется элемент <federatedAuthentication>, в котором указывается расположение службы STS для данного приложения проверяющей стороны ASP.NET, поддерживающего утверждения. В данном упражнении используется локальная служба STS.

    • Добавляется элемент <applicationService>/<claimTypeRequired>, в котором указываются утверждения, которые должны присутствовать во всех маркерах, выпускаемых для приложения службой STS. В данном упражнении используются утверждения по умолчанию "name" (имя) и "role" (роль). Обратите внимание, что проверяющая сторона фактически не зависит от этих требований к типу утверждений. Эти требования внесены в файл конфигурации по двум указанным ниже причинам.

      1. Приложения проверяющей стороны могут использовать эти требования для проверки того, содержит ли входящий маркер данные утверждения. Эту проверку можно выполнить в классе ClaimsAuthenticationManager.

      2. Эти требования позволяют проверяющим сторонам легко обновить требования к типу утверждений для приложения проверяющей стороны.

    • Добавлен элемент <issuerNameRegistry>/<trustedIssuers>, в котором указан сертификат, используемый службой STS для подписания выдаваемых ею маркеров. Для подписания создаваемых маркеров служба STS будет использовать сертификат по умолчанию. Этот сертификат с именем STSTestCert автоматически добавляется в хранилище сертификатов для использования службой STS. Файл сертификата включается в проект службы STS. Пароль файла — STSTest. Его не следует использовать в производственной среде. Сертификат, используемый по умолчанию, можно заменить любым другим сертификатом. Убедитесь, что пользователь процесса IIS имеет доступ к закрытому ключу любого такого сертификата. Можно также создать тип, производный от IssuerNameRegistry, для выполнения программной проверки сертификатов доверенных поставщиков.



Если открыть обозреватель решений, можно увидеть, что программа FedUtil добавила в решение новый проект. Это проект локальной службы STS. Обратите также внимание, что документ метаданных федерации добавлен и в приложение проверяющей стороны, и в локальную службу STS.

Обратите внимание, что маркеры, выпускаемые данной локальной службой STS, не шифруются.

Чтобы добавить дополнительные утверждения, которые будут выпускаться локальной службой STS, откройте в проекте службы STS файл CustomSecurityTokenService.cs, расположенный в папке App_Code, перейдите к методу GetOutputClaimsIdentity и добавьте необходимые утверждения.

2. Регистрация существующей службы STS для производственной среды

В данном упражнении устанавливается доверие проверяющей стороны ASP.NET к существующей службе STS.

В Visual Studio откройте меню "Файл" и выберите "Создать", "Веб-сайт". Выберите пункт "Веб-сайт ASP.NET с поддержкой утверждений". Щелкните правой кнопкой мыши проект в обозревателе решений и выберите команду "Добавить ссылку на STS". Откроется программа FedUtil. На странице "Вас приветствует служебная программа федерации" проверьте правильность сведений о расположении конфигурации приложения и кода URI приложения, после чего нажмите кнопку "Далее".

На странице "Сведения о приложении" выберите параметр "Использовать существующую службу STS".

Укажите расположение конечной точки метаданных федерации для службы STS производственной среды. Чтобы проверить доступность документа метаданных, нажмите кнопку "Проверить расположение". Эта кнопка инициирует запрос к указанной конечной точке, ответ на который выводится в окне веб-браузера по умолчанию. В данном упражнении используется служба STS Службы федерации Active Directory® (AD FS) 2.0. После ввода расположения документа метаданных федерации нажмите кнопку "Далее".

Следует иметь в виду, что если указать службу STS, сертификат которой не является доверенным для локального хранилища сертификатов, появится следующее предупреждение: "ID1025: Цепочка сертификатов обработана, но обработка прервана на корневом сертификате, у которого отсутствует доверие к поставщику доверия". Чтобы продолжить настройку, несмотря на предупреждение, нажмите кнопку "Да". В противном случае нажмите "Нет" и выберите другую службу STS.

Откроется еще одна страница со сведениями о приложении и предложением выбрать режим шифрования.

Узнайте у администратора службы STS, поддерживается ли службой STS для производственной среды шифрование маркеров. Если это так, рекомендуется включить шифрование. В данном упражнении выберите параметр "Включить шифрование". Теперь необходимо выбрать сертификат, который будет использоваться службой STS для шифрования маркеров для проверяющей стороны.

"Использовать сертификат по умолчанию" означает, что если локальная служба STS уже создала сертификат для шифрования маркеров, этот же сертификат будет использоваться и для расшифровки. При регистрации службы STS для производственной среды такая ситуация весьма нехарактерна, поскольку в таких службах, как правило, не используются сертификаты, которые применялись для локальной службы STS. Этот параметр не рекомендуется использовать в производственной среде. Если сертификат службы уже существует, его можно использовать повторно.

Если выбрать существующий сертификат, программа FedUtil выведет список сертификатов из локального хранилища. Сертификат должен иметь закрытый ключ и имя субъекта. Убедитесь, что учетная запись (например NETWORK SERVICE), с которой запускается приложение, имеет доступ к закрытому ключу сертификата.

В данном упражнении можно использовать сертификат по умолчанию или выбрать существующий сертификат. Сделав выбор, нажмите кнопку "Далее".

Откроется страница "Предлагаемые утверждения".

На ней приводится список утверждений, предлагаемых службой STS. FedUtil формирует этот список путем загрузки метаданных из службы STS и их синтаксического разбора. По умолчанию FedUtil настраивает в конфигурации проверяющей стороны в качестве обязательных утверждений только утверждения для имени и роли. Сведения о том, как настроить дополнительные утверждения в качестве обязательных для приложения проверяющей стороны, см. в разделе "Настройка приложения для поддержки дополнительных обязательных утверждений". Если приложению проверяющей стороны требуются утверждения, не предлагаемые службой STS, обратитесь к администратору службы STS с просьбой о внесении соответствующих изменений.

Нажмите кнопку "Далее". Откроется страница "Сводка".

Если был выбран тестовый сертификат, на странице сведений о приложении будет выведено следующее примечание: "Выбранный сертификат приложения: в личное хранилище сертификатов и хранилище сертификатов доверенных лиц будет добавлен новый сертификат с именем субъекта "CN=DefaultApplicationCertificate", если его еще там нет". Если выбран существующий сертификат, будет показан его отпечаток.

На странице "Сводка" отображаются данные, введенные в диалоговом окне "Сведения о приложении", сведения об использовании существующей службы STS, утверждения, запрашиваемые приложением, и изменения, которые FedUtil внесет в конфигурацию приложения.

На странице сводки также имеется флажок "Планировать ежедневное автоматическое обновление метаданных этого приложения". Если установить этот флажок, FedUtil создаст задачу обновления метаданных приложения и запланирует ее ежедневное выполнение в полночь. Дополнительные сведения см. в разделе Инструкции: управление отношениями доверия с помощью FedUtil.

Нажмите кнопку "Готово".

Ниже перечислены изменения, которые вносятся в файл web.config проверяющей стороны.

  • Добавлены следующие настройки приложения. "Указанная STS" здесь обозначает службу STS, указанную в FedUtil.

      Копировать код 
    <appSettings> <add key="FederationMetadataLocation" value="<указанная_служба_маркеров_безопасности>" /> </appSettings>
  • Всем пользователям предоставлен доступ к метаданным федерации:

      Копировать код 
    <location path="FederationMetadata"> <system.web> <authorization> <allow users="*" /> </authorization> </system.web> </location>
  • В элемент <system.Web>/<httpModules> добавляются элементы WSFederationAuthenticationModule и SessionAuthenticationModule:

      Копировать код 
    <httpModules> ... <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> </httpModules>
  • Эти же элементы также добавляются в элемент <system.webServer>/<modules>:

      Копировать код 
    <system.webServer> ... <modules> <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> </modules> ... </system.webServer>
  • Наконец, в элемент <microsoft.identityModel>/<service> вносятся следующие изменения: "Указанная STS" здесь обозначает службу STS, указанную в FedUtil.

      Копировать код 
    <microsoft.identityModel> <service> <audienceUris> <add value="http://localhost:57349/ClaimsAwareWebSite2/" /> </audienceUris> <federatedAuthentication> <wsFederation passiveRedirectEnabled="true" issuer="https://<указанная_служба_маркеров_безопасности>/FederationPassive/" realm="http://localhost:57349/ClaimsAwareWebSite2/" requireHttps="false" /> <cookieHandler requireSsl="false" /> </federatedAuthentication> <serviceCertificate> <certificateReference x509FindType="FindByThumbprint" findValue="48BF03FCEDA703DE09E0F1F0CEFED60BB92B3DD8" storeLocation="LocalMachine" storeName="My" /> </serviceCertificate> <applicationService> <claimTypeRequired> <!-- Далее перечислены утверждения, предлагаемые службой STS 'http://<указанная_служба_маркеров_безопасности>/Trust'. Добавьте или раскомментируйте утверждения, требуемые для приложения, после чего обновите метаданные федерации этого приложения.--> <claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="http://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" /> <!--<claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" optional="true" />--> <!--<claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" optional="true" />--> <!--<claimType type="http://schemas.xmlsoap.org/claims/CommonName" optional="true" />--> <!--<claimType type="http://schemas.xmlsoap.org/claims/EmailAddress" optional="true" />--> <!--<claimType type="http://schemas.xmlsoap.org/claims/Group" optional="true" />--> <!--<claimType type="http://schemas.xmlsoap.org/claims/UPN" optional="true" />--> <!--<claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier" optional="true" />--> <!--<claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/webpage" optional="true" />--> <!--<claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/title" optional="true" />--> <!--<claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/picture" optional="true" />--> <!--<claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/manager" optional="true" />--> <!--<claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/department" optional="true" />--> </claimTypeRequired> </applicationService> <issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"> <trustedIssuers> <add thumbprint="5C8885A8E3D29D6BF6C9365E00B1BEA5EB284D1E" name="CN=<specified STS>, OU=US-Federated Identity, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" /> </trustedIssuers> </issuerNameRegistry> </service> </microsoft.identityModel>
    • Добавляется элемент <audienceUris>, в котором указывается код URI приложения проверяющей стороны ASP.NET, поддерживающего утверждения.

    • Добавляется элемент <federatedAuthentication>, в котором указывается расположение службы STS для данного приложения проверяющей стороны ASP.NET, поддерживающего утверждения. Это служба STS, указанную в FedUtil.

    • Добавляется элемент <serviceCertificate>, в котором указывается расположение сертификата, используемого приложением проверяющей стороны ASP.NET, поддерживающим утверждения, для шифрования канала связи со службой STS. Это сертификат, указанный в FedUtil.

    • Добавляется элемент <applicationService>/<claimTypeRequired>, в котором указываются утверждения, которые должны присутствовать во всех маркерах, выпускаемых для приложения службой STS. По умолчанию FedUtil настраивает приложение проверяющей стороны ASP.NET, поддерживающее утверждения таким образом, чтобы оно требовало только утверждения об именах и ролях. Сведения о том, как настроить дополнительные утверждения в качестве обязательных для приложения проверяющей стороны, см. в разделе "Настройка приложения для поддержки дополнительных обязательных утверждений".

    • Добавлен элемент <issuerNameRegistry>/<trustedIssuers>, в котором указан сертификат, используемый службой STS для подписания выдаваемых ею маркеров.

Программу FedUtil можно запускать повторно для переключения с локальной службы STS на службу для производственной среды и обратно. При каждом запуске FedUtil созданная ранее конфигурация перезаписывается. Однако FedUtil нельзя использовать для переключения из режима с использованием службы STS (локальной или для производственной среды) в режим без использования службы STS.

Следует также иметь в виду, что если при запуске FedUtil создается локальная служба STS, а затем подключается служба STS для производственной среды, в элемент <issuerNameRegistry> файла конфигурации вносятся два доверенных поставщика: локальная служба STS и служба STS для производственной среды. Непосредственно перед развертыванием приложения следует удалить локальную службу STS из реестра имен поставщиков.

3. Обновление метаданных федерации

По умолчанию при использовании FedUtil с указанием службы STS для производственной среды приложение настраивается так, чтобы в нем требовались только утверждения об именах и ролях. Это видно из содержимого элемента <Microsoft.IdentityModel>/<service>/<applicationService>/<claimTypeRequired> в файле web.config приложения:

  Копировать код 
<claimTypeRequired> <!-- Ниже перечислены утверждения, предлагаемые службой STS '<указанная_служба_маркеров_безопасности>' и добавленные 15.04.2009 15:57:07. Добавьте или раскомментируйте утверждения, требуемые для приложения, после чего обновите метаданные федерации этого приложения.--> <claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="http://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" /> <!--<claimType type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" optional="true" />--> ... </claimTypeRequired>

Например, в предыдущем фрагменте кода закомментировано утверждение об адресе электронной почты. Чтобы настроить дополнительные утверждения в качестве обязательных для приложения, раскомментируйте нужные утверждения. Затем щелкните правой кнопкой мыши проект приложения в обозревателе решений и выберите команду "Обновить метаданные федерации".

FedUtil обновит метаданные федерации приложения в соответствии с изменениями, внесенными в список требуемых утверждений. После этого откройте файл FederationMetadata.xml приложения и просмотрите обновленный список требуемых утверждений. В нем теперь должны содержаться дополнительные утверждения, которые были раскомментированы в файле web.config приложения. Следует иметь в виду, что FedUtil также создает резервную копию файла web.config приложения.

  Копировать код 
<fed:ClaimTypesRequested> <auth:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" Optional="True" xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" /> <auth:ClaimType Uri="http://schemas.microsoft.com/ws/2008/06/identity/claims/role" Optional="True" xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" /> ... </fed:ClaimTypesRequested>

В файл web.config приложения также можно добавить настраиваемые типы утверждений. После этого следует попросить администратора STS обновить политику службы STS для приложения, чтобы оно выдавало утверждения новых типов.