Error Handling

Our SAML Service Provider (SP) component is a standard ASP.NET Core authentication handler. We have architected our component similarly to Microsoft's OpenID Connect authentication handler, where errors are thrown as exceptions. There are various ways of handling errors within an ASP.NET Core application. This gives you complete control over error handling within your application.

For general advice, we recommend reading Microsoft's Handle errors in ASP.NET Core documentation.

Handling Authentication Errors

The ASP.NET Core authentication handlers have in-built events. The OnRemoteFailure is raised upon authentication failures, such as an invalid SAML response.

Here's an example of how you can use the OnRemoteFailure event to handle an authentication failure gracefully.

services.AddAuthentication()
  .AddSaml2p("saml", options =>
  {
      // Other configuration code removed for brevity

      options.Events = new RemoteAuthenticationEvents
      {
          OnRemoteFailure = (context) =>
          {
              // log error
              logger.LogError($"SAML authentication failure: {context.Failure.Message}");

              // redirect to a page
              context.Response.Redirect("/Home");

              // mark response as handled before returning
              context.HandleResponse();
              return Task.CompletedTask;
          }
      };
  });

Suppressing Logout Errors

You can use the startup configuration option ThrowOnLogoutErrors to suppress logout errors. The ThrowOnLogoutErrors has a default value of true, meaning logout errors are thrown as exceptions. When ThrowOnLogoutErrors is set to false, the authentication handler will return false instead of throwing an exception.

services.AddAuthentication()
  .AddSaml2p("saml", options =>
  {
      // Other configuration code removed for brevity

      options.ThrowOnLogoutErrors = false;
  });