Skip to content

Authenticate inbound web request

This operation is the library's primary request-time workflow, running inside clsSecurityModule.AuthRequest_Handler on every ASP.NET AuthenticateRequest event. It short-circuits requests that already carry an authenticated principal, classifies the remaining requests as internal or external, hands each one to the matching authenticator, and normalizes redirect and error handling so downstream failures never surface as raw exceptions to the caller.

Field Value
Operation ID authenticate-inbound-web-request
Trigger HttpApplication.AuthenticateRequest fires for an inbound request.
Inputs sender As Object, current HttpContext.User, request host, ExternalHostNames, sec-errorpage
Outputs Request continues with an established principal, redirects to login/error, or returns a 401 challenge response
Primary components clsSecurityModule.AuthRequest_Handler, UserAuthenticator.Find, UserAuthenticator.IsAuthenticated
Entry point SAIF.Framework.SecurityModule\clsSecurityModule.vb

Steps

  1. Cast sender to HttpApplication, capture the request context, and log Begin.
  2. Read WebContext.Context.User and determine whether the request already carries an authenticated identity (BR-001).
  3. If the user is already authenticated, log the identity name and skip the remainder of the authentication workflow — no cookie decryption, logon, or redirect logic runs.
  4. For an unauthenticated request, classify the request host by calling UserAuthenticator.Find(WebContext.Request.Url.Host, AppSettings("ExternalHostNames")) (BR-002).
  5. If the configured external-host list contains the request host, choose the external authenticator.
  6. Otherwise, choose the internal authenticator.
  7. Invoke the selected authenticator's Authenticate(WebContext) method.
  8. The external path is Redirect external user to login, which first attempts Perform cookie-based silent re-authentication before redirecting.
  9. The internal path attempts Perform cookie-based silent re-authentication directly, then falls back to Issue browser credential challenge when silent authentication does not succeed.
  10. If the downstream authenticator's redirect aborts the current thread, catch the resulting ThreadAbortException and call Thread.ResetAbort() so the redirect is treated as expected control flow rather than an authentication failure (BR-005).
  11. If any other exception escapes the authentication flow, write it to Log.Error and redirect the response to ErrorPage & "?MSG=" & ex.Message (BR-006).
  12. On failure: the error-page redirect itself can raise a ThreadAbortException; that exception is caught by the preceding branch on the next unwind of the call stack, not treated as a second failure.
  13. In Finally, log End before returning control to the ASP.NET pipeline.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([AuthenticateRequest]) --> S1[Log begin and read current user]
    S1 --> D1{Already authenticated?}
    D1 -->|Yes| EndOk([Request proceeds unchanged])
    D1 -->|No| S2[Classify host]
    S2 --> D2{External host?}
    D2 -->|Yes| S3[Run external authenticator]
    D2 -->|No| S4[Run internal authenticator]
    S3 --> EndOk
    S4 --> EndOk
    S3 -. exception .-> Err([Redirect to error page])
    S4 -. exception .-> Err

Failure and edge-case behavior

  • Already-authenticated requests generate only a debug log entry; they never re-run cookie decryption, Windows logon, or browser-challenge logic (BR-001).
  • The redirect-based fallbacks intentionally trigger ThreadAbortException as a side effect of Response.Redirect; this operation suppresses that specific exception so it never becomes an unintended error-page redirect (BR-005).
  • Any other exception raised anywhere in downstream authentication — including a failed Windows logon — is converted into an error-page redirect with the exception message appended to the query string (BR-006).

Sources

  • SAIF.Framework.SecurityModule\clsSecurityModule.vb
  • SAIF.Framework.SecurityModule\Authenticators\UserAuthenticator.vb