Error Handling | SAML2P Documentation

Our SAML Service Provider (SP) component is a standard ASP.NET Core authentication handler. We have architected our component in the same way as 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 event is raised upon an authentication failure. For example, if the received SAML response is invalid.

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

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

The startup configuration option ThrowOnLogoutErrors can be used to suppress logout errors. The ThrowOnLogoutErrors has a default value of true, which means that 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;
  });

Previous Next