WSFederationAuthenticationModule Classe

Definição

public ref class WSFederationAuthenticationModule : System::IdentityModel::Services::HttpModuleBase

public class WSFederationAuthenticationModule : System.IdentityModel.Services.HttpModuleBase

type WSFederationAuthenticationModule = class
    inherit HttpModuleBase

Public Class WSFederationAuthenticationModule
Inherits HttpModuleBase

Herança

Object

HttpModuleBase

WSFederationAuthenticationModule

Exemplos

void Application_Start(object sender, EventArgs e)
{
    // Code that runs on application startup

    //SUBSCRIBE TO WSFAM EVENTS
    FederatedAuthentication.WSFederationAuthenticationModule.AuthorizationFailed += new EventHandler<AuthorizationFailedEventArgs>(WSFederationAuthenticationModule_AuthorizationFailed);
    FederatedAuthentication.WSFederationAuthenticationModule.RedirectingToIdentityProvider += new EventHandler<RedirectingToIdentityProviderEventArgs>(WSFederationAuthenticationModule_RedirectingToIdentityProvider);
    FederatedAuthentication.WSFederationAuthenticationModule.SecurityTokenReceived += new EventHandler<SecurityTokenReceivedEventArgs>(WSFederationAuthenticationModule_SecurityTokenReceived);
    FederatedAuthentication.WSFederationAuthenticationModule.SecurityTokenValidated += new EventHandler<SecurityTokenValidatedEventArgs>(WSFederationAuthenticationModule_SecurityTokenValidated);
    FederatedAuthentication.WSFederationAuthenticationModule.SessionSecurityTokenCreated += new EventHandler<SessionSecurityTokenCreatedEventArgs>(WSFederationAuthenticationModule_SessionSecurityTokenCreated);
    FederatedAuthentication.WSFederationAuthenticationModule.SignedIn += new EventHandler(WSFederationAuthenticationModule_SignedIn);
}

void WSFederationAuthenticationModule_SignedIn(object sender, EventArgs e)
{
    //Anything that's needed right after succesful session and before hitting the application code goes here
    System.Diagnostics.Trace.WriteLine("Handling SignIn event");
}

void WSFederationAuthenticationModule_SessionSecurityTokenCreated(object sender, SessionSecurityTokenCreatedEventArgs e)
{
    //Manipulate session token here, for example, changing its expiration value
    System.Diagnostics.Trace.WriteLine("Handling SessionSecurityTokenCreated event");
    System.Diagnostics.Trace.WriteLine("Key valid from: " + e.SessionToken.KeyEffectiveTime);
    System.Diagnostics.Trace.WriteLine("Key expires on: " + e.SessionToken.KeyExpirationTime);
}

void WSFederationAuthenticationModule_SecurityTokenValidated(object sender, SecurityTokenValidatedEventArgs e)
{
    //All vlidation SecurityTokenHandler checks are successful
    System.Diagnostics.Trace.WriteLine("Handling SecurityTokenValidated event");
}

void WSFederationAuthenticationModule_SecurityTokenReceived(object sender, SecurityTokenReceivedEventArgs e)
{
    //Augment token validation with your cusotm validation checks without invalidating the token.
    System.Diagnostics.Trace.WriteLine("Handling SecurityTokenReceived event");
}

void WSFederationAuthenticationModule_AuthorizationFailed(object sender, AuthorizationFailedEventArgs e)
{
    //Use this event to report more details regarding the ahorization failure
    System.Diagnostics.Trace.WriteLine("Handling AuthorizationFailed event");
}

void WSFederationAuthenticationModule_RedirectingToIdentityProvider(object sender, RedirectingToIdentityProviderEventArgs e)
{
    //Use this event to programmatically modify the sign-in message to the STS.
    System.Diagnostics.Trace.WriteLine("Handling RedirectingToIdentityProvider event");
}

Observações

A WSFederationAuthenticationModule classe implementa um módulo HTTP conhecido como WS-Federation Authentication Module (WSFAM). O WSFAM é implementado de fábrica pela Windows Identity Foundation (WIF). O WSFAM é adicionado ao pipeline de ASP.NET fazendo uma entrada no ficheiro web.config. Deriva de HttpModuleBase, que implementa IHttpModule. Regista-se no tempo de execução ASP.NET para ouvir os eventos EndRequest e AuthenticateRequest. Ao ouvir o EndRequest evento, a WSFAM redireciona os clientes para um serviço de token de segurança (STS) para obter um token de segurança quando a autorização falha num recurso solicitado. Ouvir o AuthenticateRequest evento permite ao WSFAM monitorizar os pedidos HTTP para uma resposta do STS que contenha o token solicitado. Quando tal token está presente e válido, cria uma instância de ClaimsPrincipal para o utilizador autenticado usando as reivindicações presentes no token.

Ao utilizar o WSFAM, a gestão de sessões é fornecida por um módulo de autenticação de sessão (SAM), que é uma instância da SessionAuthenticationModule classe, ou uma classe derivada dela. O SAM também é adicionado ao pipeline ASP.NET no ficheiro de configuração. O SAM monitoriza pedidos de cookies de autenticação (sessão). Quando estes cookies estão presentes e válidos, o módulo extrai o ClaimsPrincipal para o utilizador autenticado a partir do SessionSecurityToken e define a HttpContext.User propriedade e as propriedades principais Thread.CurrentPrincipal do thread.

A WSFAM oferece:

• A capacidade de uma aplicação ASP.NET externalizar a autenticação para um serviço de token de segurança (STS) utilizando o protocolo WS-Federation. A identidade pode ser federada através de um ou mais domínios de identidade e envolver múltiplos STS.

• Identidade baseada em reclamações para aplicações ASP.NET. Durante a autenticação, o WSFAM constrói um principal a partir das reivindicações no token de segurança enviadas pelo STS e define esse principal de reivindicações como principal do thread. Pode então usar este princípio para tomar decisões adicionais de autorização, apresentação e lógica sobre o utilizador que representa no seu código.

O WSFAM expõe várias propriedades que fornecem parâmetros de mensagem por defeito para usar em WS-Federation pedidos de início e encerramento de sessão. Estas propriedades são normalmente inicializadas a partir do <elemento wsFederation> num ficheiro de configuração. As mais importantes destas propriedades são:

• A Issuer propriedade, que especifica o endereço do serviço de token de segurança (STS) para o qual enviar WS-Federation pedidos de entrada e saída.

• A Realm propriedade, que especifica o parâmetro wtrealm a usar em pedidos de início de sessão WS-Federation. O parâmetro wtrealm identifica o domínio de segurança da parte confiável (RP) da aplicação ao STS.

Os parâmetros da mensagem de início de sessão também podem ser alterados por pedido, fornecendo um delegado handler de eventos para o RedirectingToIdentityProvider evento.

Duas propriedades controlam o comportamento do módulo. Ambas estas propriedades são também tipicamente inicializadas a partir do <wsFederation> elemento em configuração.

• A PassiveRedirectEnabled propriedade especifica se o módulo deve realizar redirecionamentos passivos para o STS para autenticação.

• A PersistentCookiesOnPassiveRedirects propriedade especifica se as sessões devem ser persistentes. Se esta propriedade for definida como verdadeira, o SAM é usado para escrever um cookie de sessão para o cliente. Em pedidos subsequentes do cliente, o SAM fornece autenticação utilizando o token persistido no cookie da sessão.

O WSFAM gera vários eventos durante o início e o encerramento de sessão, que permitem aos programadores do ASP.NET alterar o comportamento padrão do módulo e controlar os detalhes de como a autenticação e o processamento das reclamações são realizados.

Os seguintes eventos são levantados antes do pedido de assinatura WS-Federation ser enviado ao STS:

• AuthorizationFailed: Levantado quando o redirecionamento passivo está ativado e a autorização falha num recurso solicitado.

• RedirectingToIdentityProvider: Levantado pouco antes do WSFAM enviar o pedido de assinatura WS-Federation ao STS. Pode usar este evento para alterar os parâmetros no pedido de iniciação de sessão.

Os seguintes eventos são apresentados quando uma resposta de login (token de segurança emitido) é recebida do STS:

• SecurityTokenReceived: Levantado logo após o token de segurança enviado pelo STS ser lido da resposta.

• SecurityTokenValidated: Levantado logo após o token ter sido validado. Pode usar este evento para filtrar, transformar ou adicionar reivindicações ao principal de reivindicações (ClaimsPrincipal) criado a partir do token de segurança.

• SessionSecurityTokenCreated: Levantado pouco antes do token de sessão (SessionSecurityToken) criado a partir do principal de reivindicações ser usado para definir o principal do thread e o utilizador atual e é escrito no cookie da sessão. Dá-te a oportunidade de modificar o token da sessão ou ativar ou desativar a escrita do cookie da sessão.

• SignedIn: Levantado no final da autenticação, logo após o principal da thread e o utilizador atual terem sido definidos.

• SignInError: Elevado se ocorrer uma exceção durante o início de sessão. Pode cancelar o pedido e impedir que a exceção seja devolvida ao chamador.

Ao sair de uma sessão ou ao processar um pedido de limpeza de WS-Federation de saída de sessão (wsignoutcleanup1.0), são levantados os seguintes eventos:

• SigningOut: Levantado pouco antes da sessão ser eliminada para permitir que realize qualquer limpeza que possa depender da sessão ou para cancelar o log-out.

• SignedOut: Levantado logo após a sessão ter sido eliminada.

• SignOutError: Elevado se ocorrer uma exceção durante o desligamento. Pode cancelar o log-out e impedir que a exceção seja devolvida ao chamador.

Existem duas formas de iniciar sessão num STS usando o WSFAM. A primeira é permitir redirecionamentos passivos através da PassiveRedirectEnabled propriedade. Neste caso, quando a autorização falha num recurso solicitado, em vez de devolver uma 401:Access Denied resposta ao cliente, o WSFAM constrói uma mensagem WS-Federation de pedido de entrada a partir das suas propriedades e redireciona o cliente para o STS para recuperar um token de segurança. A segunda forma é redirecionar explicitamente o cliente para o STS chamando o SignIn método a partir de uma página web ou controlo personalizado na sua aplicação. O SignIn método também utiliza as propriedades do WSFAM para construir o pedido de entrada.

Qualquer um dos métodos sobrecarregados SignOut pode ser usado para sair da sessão. Isto elimina o cookie de sessão no cliente. Não envia uma mensagem de deslido WS-Federation ("wsignout1.0") para o STS. Para sair no STS, deve usar o FederatedSignOut método.

A WSFAM trata WS-Federation pedidos de limpeza de desistência ("wsignoutcleanup1.0"), eliminando a sua sessão com o cliente. Se o parâmetro wreply na mensagem de limpeza de encerramento não estiver definido, o WSFAM devolve uma imagem de uma marca de verificação verde ao STS que enviou a mensagem. Esta funcionalidade pode ser usada por um STS como reconhecimento de que o RP completou a sua saída.

O WSFAM expõe a sua funcionalidade — por exemplo, o seu pipeline de processamento de pedidos — através de vários métodos específicos para cada tarefa. Pode sobrepor estes métodos em classes derivadas para alterar o comportamento do WSFAM.

Para ser utilizado, o módulo deve ser adicionado ao pipeline conforme no seguinte XML:

<configuration>
  <system.webServer>
    <modules>
      <add name="WsFederationAuthenticationModule" type="System.IdentityModel.Services.WSFederationAuthenticationModule, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
    </modules>
  </system.webServer>
</configuration>

Uma vez configurado, os WSFederationAuthenticationModule eventos geram em várias fases do processamento de um pedido HTTP. Os programadores do ASP.NET podem gerir estes eventos no ficheiro global.asax.