Establecer la confianza de una aplicación de usuario de confianza de ASP.NET a un STS mediante FedUtil

FedUtil.exe se proporciona con Windows® Identity Foundation (WIF). Le ayuda a establecer la confianza de una aplicación de usuario de confianza (RP) a los servicios de token de seguridad (STS). Proporciona las siguientes capacidades:

• Registrar un STS de producción existente como un emisor de confianza de la aplicación de RP.

• Ayudar a desarrollar una aplicación para notificaciones proporcionando un STS local.

• Adaptar una aplicación existente para notificaciones.

• Actualizar los metadatos de federación para una aplicación de RP.

• Programar actualizaciones automáticas de los metadatos de federación para una aplicación de RP.

En las siguientes secciones se muestra cómo hacer cada una de estas tareas utilizando FedUtil. También puede hacerlas manualmente realizando los mismos cambios en el archivo web.config de la aplicación de RP que realiza FedUtil.

1. Crear un STS local

En este ejercicio, creará un STS local para usarlo con nuestra aplicación de usuario de confianza de ASP.NET para notificaciones. Observe que debe ejecutar FedUtil desde dentro de Visual Studio para hacerlo. Esta opción está pensada para ayudar al desarrollo de una aplicación de usuario de confianza de ASP.NET para notificaciones con un STS no de producción. Después, verá cómo puede pasar a utilizar un STS de producción.

En Visual Studio, abra el menú Archivo y seleccione Nuevo, Sitio web. Seleccione Sitio web de ASP.NET para notificaciones.

A continuación, haga clic con el botón secundario en el proyecto en el Explorador de soluciones y seleccione Agregar referencia STS:

Así se ejecuta la herramienta FedUtil. Verá el cuadro de diálogo de FedUtil, comenzando con la página de bienvenida a la herramienta Federation Utility:

Esta página le pide que escriba dos campos:

1. Ubicación de configuración de la aplicación: especifique la ruta de acceso al archivo web.config de su servicio de . Si ejecuta FedUtil desde fuera de Visual Studio, o lo ejecuta desde el menú Herramientas en Visual Studio sin tener abierto un proyecto, este campo estará vacío. Si ejecuta FedUtil haciendo clic con el botón secundario en un proyecto en Visual Studio, este campo ya contiene la ruta de acceso al archivo web.config de su proyecto. El archivo web.config ya debe existir y estar en su estado predeterminado (es decir, como fue generado por Visual Studio). Si ejecuta más de una vez FedUtil en el mismo archivo web.config, FedUtil simplemente sobrescribe el contenido que agrega al archivo web.config.

2. URI de la aplicación: especifique el URI de su servicio de ASP.NET. Observe que se trata de un archivo .svc. Si ejecuta FedUtil desde fuera de Visual Studio, o lo ejecuta desde el menú Herramientas en Visual Studio sin tener abierto un proyecto, este campo estará vacío. Si ejecuta FedUtil haciendo clic con el botón secundario en un proyecto en Visual Studio, este campo ya contiene dos URI de su proyecto: uno que utiliza localhost y otro que utiliza el nombre de dominio completo de su equipo, si está disponible. Este URI se utiliza como valor de dominio kerberos al configurar la aplicación para notificaciones. También se utiliza como primer URI de audiencia. Si desea especificar URI de audiencia adicionales, debe hacerlo manualmente. Si el URI no es seguro (es decir, no comienza con “https://”), se mostrará una advertencia al hacer clic en Siguiente.

Después haber proporcionado la información, haga clic en Siguiente. Verá la página Security Token Service. Seleccione Crear un nuevo proyecto de STS en la solución actual:

Tenga en cuenta que si ejecuta FedUtil desde fuera de Visual Studio, o si ejecuta FedUtil desde el menú Herramientas en Visual Studio sin tener abierto un proyecto, no estará disponible la opción Crear un nuevo proyecto de STS en la solución actual.

Haga clic en Siguiente. Aparece la Página de resumen:

La Página de resumen muestra la información que escribió en el cuadro de diálogo Información de aplicación, su elección para crear un nuevo STS, las notificaciones solicitadas por la aplicación y los cambios que FedUtil realizará en la configuración de la aplicación.

Haga clic en Finalizar.

Si examina el archivo web.config, verá que FedUtil lo ha modificado:

• Se agregan los siguientes valores de configuración de la aplicación:

  <appSettings> <add key="FederationMetadataLocation" value="C:\inetpub\wwwroot\ClaimsAwareWebSite1_STS\FederationMetadata\2007-06\FederationMetadata.xml" /> </appSettings>
  

• Se ha concedido acceso a todos los usuarios a los metadatos de federación:

  <location path="FederationMetadata"> <system.web> <authorization> <allow users="*" /> </authorization> </system.web> </location>
  

• WSFederationAuthenticationModule y SessionAuthenticationModule se agregan al elemento <system.Web>/<httpModules>:

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

• También se agregan al elemento <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>
  

• Finalmente, el elemento <microsoft.identityModel>/<service> se modifica de este modo:

  <microsoft.identityModel> <service> <audienceUris> <add value="https://localhost:58496/ClaimsAwareWebSite2/" /> </audienceUris> <federatedAuthentication enabled="true"> <wsFederation passiveRedirectEnabled="true" issuer="https://localhost:58497/ClaimsAwareWebSite2_STS/" realm="https://localhost:58496/ClaimsAwareWebSite2/" requireHttps="false" /> <cookieHandler requireSsl="false" /> </federatedAuthentication> <applicationService> <claimTypeRequired> <claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="https://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>
  

  • Se agrega un elemento <audienceUris> para especificar el URI de la aplicación de usuario de confianza de ASP.NET para notificaciones.

  • Se agrega un elemento <federatedAuthentication> para especificar la ubicación del STS para esta aplicación de usuario de confianza de ASP.NET para notificaciones. Para este ejercicio, se utiliza el STS local.

  • Se agrega un elemento <applicationService>/<claimTypeRequired> para especificar las notificaciones que exige la aplicación en cualquier token que el STS emita para ella. Para este ejercicio, se utilizan las notificaciones predeterminadas “name” y “role”. Observe que el usuario de confianza realmente no depende de estos requisitos de tipo de notificación. Se encuentran en el archivo de configuración por dos razones:

    1. Las aplicaciones de usuario de confianza pueden utilizar estos requisitos de tipo de notificación para validar si el token entrante tiene o no estas notificaciones. Esto se puede hacer en ClaimsAuthenticationManager.

    2. Proporcionan un método fácil para que los usuarios de confianza actualicen los requisitos de tipo de notificación de la aplicación de usuario de confianza.

  • Se agrega un elemento <issuerNameRegistry>/<trustedIssuers> para especificar el certificado que usa el STS para firmar los tokens que emite. El STS utilizará un certificado predeterminado para firmar los tokens que genera. Este certificado se denomina "STSTestCert" y se agrega automáticamente al almacén de certificados para que lo use el STS. El archivo de certificado se encuentra en el proyecto de STS. La contraseña del archivo es "STSTest". Esto no se debería utilizar en un ejercicio de producción. Puede reemplazar el certificado predeterminado por cualquier otro certificado. Asegúrese de que el usuario del proceso de IIS tiene acceso a la clave privada de ese tipo de certificado. También podría decidir crear un tipo derivado de IssuerNameRegistry para realizar una validación mediante programación de certificados de emisores de confianza.

También, si examina el Explorador de soluciones, verá que FedUtil ha agregado un nuevo proyecto a la solución. Este proyecto es el STS local. También observe que se ha agregado un documento de metadatos de federación a la aplicación de usuario de confianza y al STS local.

Observe que no se cifran los tokens emitidos por este STS local.

Para agregar notificaciones adicionales que va a emitir el STS local, abra CustomSecurityTokenService.cs en el proyecto STS bajo la carpeta App_Code, desplácese al método GetOutputClaimsIdentity y agregue las notificaciones adicionales.

2. Registrar un STS de producción existente

En este ejercicio, establecerá la confianza de un usuario de confianza de ASP.NET a un STS existente.

En Visual Studio, abra el menú Archivo y seleccione Nuevo, Sitio web. Seleccione Sitio web de ASP.NET para notificaciones. Haga clic con el botón secundario en el proyecto en el Explorador de soluciones y seleccione Agregar referencia STS. Así se ejecuta la herramienta FedUtil. En la página de bienvenida de la herramienta Federation Utility, asegúrese de que la Ubicación de configuración de la aplicación y el URI de la aplicación son correctos y haga clic en Siguiente.

En la página Información de la aplicación, seleccione Usar un STS existente:

Debe especificar la ubicación del extremo de metadatos de federación para el STS de producción. Puede hacer clic en el botón Probar ubicación para asegurarse de que el documento de metadatos es accesible. Este botón realiza una solicitud al extremo especificado y muestra la respuesta en el explorador web predeterminado. Para este ejercicio, utilizamos un STS de Servicios de federación de Active Directory® (AD FS) 2.0. Una vez especificada la ubicación del documento de metadatos de federación, haga clic en Siguiente.

Tenga en cuenta que si especifica un STS que tiene un certificado en el que no confía el almacén de certificados local, verá el siguiente mensaje de advertencia: ”ID1025: Se ha procesado una cadena de certificados, pero termina en un certificado raíz en el que el proveedor de confianza no confía”. Si desea continuar de todos modos, haga clic en Sí. Si no es así, haga clic en No y seleccione un STS diferente.

Aparece otra página Información de aplicación, esta vez pidiéndole que seleccione Sin cifrado o Habilitar cifrado:

Confirme con su administrador de STS que el STS de producción admite el cifrado de tokens. En ese caso, se recomienda habilitar el cifrado. Para este ejercicio, seleccione Habilitar cifrado. Ahora debe seleccionar el certificado que el usuario de confianza desea que utilice el STS al cifrar los tokens.

Utilizar el certificado predeterminado significa que si el STS local ya ha creado un certificado para cifrar tokens, este mismo certificado se utiliza de nuevo para el descifrado. Al registrar un STS de producción, esto no es muy común, porque el STS de producción probablemente no utilizará el mismo certificado que utilizó para el STS local. No debería utilizar esta opción en una solución de producción. Si ya tiene un certificado de servicio, puede que desee utilizar el mismo certificado.

Si selecciona un certificado existente, FedUtil muestra los certificados en el almacén de certificados local. El certificado debe tener una clave privada y un nombre de sujeto. Asegúrese de que la identidad (por ejemplo, NETWORK SERVICE) bajo la que se ejecuta la aplicación tiene acceso a la clave privada del certificado.

Para este ejercicio, puede utilizar el certificado predeterminado o seleccionar uno existente. Cuando haya acabado, haga clic en Siguiente.

Aparece la página Notificaciones ofrecidas:

Contiene una lista de notificaciones que proporciona el STS. FedUtil obtiene esta lista descargando los metadatos del STS y analizándolos. De forma predeterminada, FedUtil solo configura las notificaciones de nombre y rol como notificaciones obligatorias en la configuración del usuario de confianza. Para saber cómo configurar la aplicación de usuario de confianza para que exija notificaciones adicionales, consulte la sección “Cómo configurar la aplicación para que exija notificaciones adicionales”. Si la aplicación de usuario de confianza exige notificaciones que no proporciona el STS, debería ponerse en contacto con el administrador de STS y llegar a los acuerdos necesarios.

Haga clic en Siguiente. Aparece la Página de resumen:

Si seleccionó un certificado de pruebas, la información de la aplicación incluirá esta nota: “Certificado de aplicación seleccionado: se agregará un nuevo certificado con el nombre de sujeto 'CN=DefaultApplicationCertificate' a los almacenes de certificados personales y de usuarios de confianza, de no estar ya presentes”. Si seleccionó un certificado existente, verá la huella digital de ese certificado.

La Página de resumen muestra la información que escribió en el cuadro de diálogo Información de aplicación, su elección para usar un STS existente, las notificaciones solicitadas por la aplicación y los cambios que FedUtil realizará en la configuración de la aplicación.

La Página de resumen también incluye una casilla denominada “Programar actualizaciones de metadatos diarias para esta aplicación”. Si activa esta casilla, FedUtil programará una tarea para actualizar los metadatos de la aplicación todas las noches a medianoche. Para obtener más información, vea Cómo: Realizar la administración de confianza mediante FedUtil.

Haga clic en Finalizar.

A continuación se muestran los cambios del archivo web.config del usuario de confianza:

• Se agregan los siguientes valores de configuración de la aplicación. “Specified STS” hace referencia al STS que especificó en FedUtil.

  <appSettings> <add key="FederationMetadataLocation" value="<specified STS>" /> </appSettings>
  

• Se ha concedido acceso a todos los usuarios a los metadatos de federación:

  <location path="FederationMetadata"> <system.web> <authorization> <allow users="*" /> </authorization> </system.web> </location>
  

• WSFederationAuthenticationModule y SessionAuthenticationModule se agregan al elemento <system.Web>/<httpModules>:

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

• También se agregan al elemento <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>
  

• Finalmente, el elemento <microsoft.identityModel>/<service> se modifica de este modo. “Specified STS” hace referencia al STS que especificó en FedUtil.

  <microsoft.identityModel> <service> <audienceUris> <add value="https://localhost:57349/ClaimsAwareWebSite2/" /> </audienceUris> <federatedAuthentication> <wsFederation passiveRedirectEnabled="true" issuer="https://<specified STS>/FederationPassive/" realm="https://localhost:57349/ClaimsAwareWebSite2/" requireHttps="false" /> <cookieHandler requireSsl="false" /> </federatedAuthentication> <serviceCertificate> <certificateReference x509FindType="FindByThumbprint" findValue="48BF03FCEDA703DE09E0F1F0CEFED60BB92B3DD8" storeLocation="LocalMachine" storeName="My" /> </serviceCertificate> <applicationService> <claimTypeRequired> <!--Following are the claims offered by STS 'http://<specified STS>/Trust'. Add or uncomment claims that you require by your application and then update the federation metadata of this application.--> <claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" /> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/CommonName" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/EmailAddress" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/Group" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/UPN" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/webpage" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/title" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/picture" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/manager" optional="true" />--> <!--<claimType type="https://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>
  

  • Se agrega un elemento <audienceUris> para especificar el URI de la aplicación de usuario de confianza de ASP.NET para notificaciones.

  • Se agrega un elemento <federatedAuthentication> para especificar la ubicación del STS para esta aplicación de usuario de confianza de ASP.NET para notificaciones. Es el STS que especificó en FedUtil.

  • Se agrega un elemento <serviceCertificate> para especificar la ubicación del certificado que la aplicación de usuario de confianza de ASP.NET para notificaciones utiliza para cifrar sus comunicaciones con el STS. Este es el certificado que especificó en FedUtil.

  • Se agrega un elemento <applicationService>/<claimTypeRequired> para especificar las notificaciones que exige la aplicación en cualquier token que el STS emita para ella. De forma predeterminada, FedUtil configura la aplicación de usuario de confianza de ASP.NET para notificaciones para que solo exija notificaciones de rol y nombre. Para saber cómo configurar la aplicación de usuario de confianza para que exija notificaciones adicionales, consulte la sección “Cómo configurar la aplicación para que exija notificaciones adicionales”.

  • Se agrega un elemento <issuerNameRegistry>/<trustedIssuers> para especificar el certificado que usa el STS para firmar los tokens que emite.

Observe que puede ejecutar FedUtil repetidamente para cambiar entre un STS local y un STS de producción y viceversa. Cada vez que ejecuta FedUtil, simplemente sobrescribe la configuración que creó previamente. Sin embargo, no puede utilizar FedUtil para cambiar de utilizar un STS local o STS de producción a no utilizar ningún STS.

También tenga en cuenta que si ejecuta FedUtil y crea un STS local y, a continuación, cambia a un STS de producción, el elemento <issuerNameRegistry> del archivo de configuración contendrá dos emisores de confianza. Uno es el STS local y el otro es el STS de producción. Cuando esté listo para implementar la aplicación, debería quitar el STS local del registro de nombres de emisor.

3. Actualizar los metadatos de federación

De forma predeterminada, al utilizar FedUtil y especificar un STS de producción, FedUtil configura su aplicación para que solo requiera notificaciones de rol y nombre. Puede verlo examinando el elemento <Microsoft.IdentityModel>/<service>/<applicationService>/<claimTypeRequired> en el archivo web.config de la aplicación:

<claimTypeRequired> <!--Following are the claims offered by STS '<specified STS>', and added at 4/15/2009 3:57:07 PM. Add or uncomment claims that you require by your application and then update the federation metadata of this application.--> <claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" /> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" optional="true" />--> ... </claimTypeRequired>

Por ejemplo, en el fragmento de código anterior, la notificación emailaddress está comentada. Para configurar la aplicación para que requiera notificaciones adicionales, comente las notificaciones que desea. A continuación, en el Explorador de soluciones, haga clic con el botón secundario en el proyecto de aplicación y seleccione Actualizar metadatos de federación:

FedUtil actualiza los metadatos de federación de la aplicación para reflejar los cambios en la lista de notificaciones necesarias. Después, abra el archivo FederationMetadata.xml de la aplicación y examine la lista actualizada de notificaciones necesarias. Ahora debería incluir cualquier notificación adicional comentada en el archivo web.config de la aplicación. Observe que FedUtil también realiza una copia de seguridad del archivo web.config de la aplicación.

<fed:ClaimTypesRequested> <auth:ClaimType Uri="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" Optional="True" xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" /> <auth:ClaimType Uri="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" Optional="True" xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" /> ... </fed:ClaimTypesRequested>

También puede agregar tipos de notificación personalizados al archivo web.config de la aplicación. A continuación, debe pedir al administrador de STS que actualice la directiva de STS de la aplicación para que emita los nuevos tipos de notificación.