Geneva is integrated in ASP.NET/IIS using the standard IHttpModule extensibility mechanism. Geneva ships with three HTTP modules:

• ClaimsPrincipalHttpModule (already wrote about it here).
• WSFederationAuthenticationModule (implements WS-Federation authentication)
• SessionAuthenticationModule (implements session authentication)

ClaimsPrincipalHttpModule is special – but the other two are built upon a framework for handling token based authentication in ASP.NET. To integrate into this framework, one has to derive from a base class called FederatedAuthenticationModuleBase. This implements the IHttpModule interface, subscribes to the AuthenticateRequest and EndRequest pipeline events and provides some helper methods. This base class drives the core logic of how a typical redirection and token based authentication works. For the protocol specific details, the derived class has to implement a bunch of abstract methods. This is how WS-Federation is implemented – other protocols could be realized in a similar fashion.

The core logic is as follows:

AuthenticateRequest

• check if federated authentication is enabled
• check if current request is a sign in request (abstract CanReadSignInRequest)
• extract security token from request (abstract GetSecurityToken)
  • raise SecurityTokenReceived event
• create IClaimsPrincipal from security token
  • raise SecurityTokenValidated event
• set principal
• create session security token
• set session security token using the configured cookie handler
  • raise SessionSecurityTokenCreated event
• raise SignedIn event
• check for a return URL (abstract GetReturnUrlFromResponse)
  • do the redirect

EndRequest

• check if federated authentication is enabled
• if a 401 response is found, redirect to identity provider (abstract RedirectToIdentityProvider)

Now let’s have a close look what the two derived module do.

WSFederationAuthenticationModule
As stated earlier, this module deals with WS-Federation redirects and token parsing.

• CanReadSigninRequest
  checks for the WS-Federation messages (wsignin1.0 / wsignoutcleanup1.0)
• GetSecurityToken
  extracts the token from the STS response and uses the security token handler infrastructure to create a SecurityToken
• GetReturnUrlFromResponse
  parses the WS-Fed context field for a return URL-
• RedirectToIdentityProvider
  creates a SignInRequest message and redirects to the configured identity provider.

SessionAuthenticationModule
After the module implementing the authentication protocol has done its job, the base class creates a session token. This session token contains the original token issued from the STS (the bootstrap token) as well as a serialized version of the IClaimsPrincipal (after transformation via the ClaimsAuthenticationManager). This session token gets persisted by a cookie handler (typically into a HTTP cookie). The session authentication module uses this cookie to re-create the IClaimsPrincipal on each request.

Since the session token characteristics are a bit specific, the module builds upon the base framework and helper methods, but short-circuits the logic by overriding AuthenticateCore directly. This is what happens:

• check if cookie is present (using the configured cookie handler)
• recreate the SessionSecurityToken from the cookie (using the session security token handler)
• raise SessionSecurityTokenReceived event
• based on the outcome of the event either renew the cookie and/or set the principal
• raise SignedIn event

HTH