Skip to end of metadata
Go to start of metadata
Icon

This guide will show you how to verify a SAML response using C# and the client kit for .NET. The example code in this section demonstrates verification of a SAML response in an ASP.NET MVC web application. The exact same concept will also work for ASP.NET Web Forms.

You may download the code in this guide from https://github.com/signicat/auth.

 

Include the .NET client kit in your project

The first step is to download the client kit for C#. Unzip the file, copy the Signicat.Basic.dll to your project and include it as a reference.

Create the method which will receive the SAML response

The Verify method

Code walkthrough

  1. string recipient = Url.Action("Verify", "Auth", null, Request.Url.Scheme);

    A SAML response contains information about the intended recipient of it, i.e. the URL of the method which should receive it. This is a safety mechanism to make sure that we're not verifying SAML responses that were intended for another application. If this application was running on http://localhost:8080 then the call to Url.Action yields http://localhost:8080/auth/verify. (In production you are required to use https.)

  2. authAttributes = Signicat.Basic.Saml.Verify(SAMLResponse, Infrastructure.Test, 0, recipient);

    The Verify method expects the base 64 encoded SAML response, the infrastructure (Test or Production), the time skew and the previously constructed recipient URL. If successful, the invocation returns a set of all the attributes in the SAML response. If unsuccessful, it will throw an exception and the exception message will tell you why.
     

  3. string nationalId = authAttributes.First(a => a.Namespace == "national-id" && a.Name == "no.fnr").Value;

    This is a regular LINQ query to extract the relevant information from the SAML response. The code you write here will depend on what id method is in use and which information you are interested in. See example SAML responses for different id providers here.

  4. FormsAuthentication.SetAuthCookie(nationalId, false);

    Demo code. Most likely you want to map a national identity number of a person to some kind of user id in your application. You are not required nor encouraged to use the national identity number in your cookies.
     

  5. return RedirectToAction("Granted", new { name = plainName });

    Authentication is complete and you may redirect the user to wherever you'd like.

Error situations

The following exceptions and messages may be produced when verifying the SAML response:

  1. ArgumentException – "SAML Response cannot be null". For example, this may happen if a user is sent to the Verify action without having authenticated first.
  2. ArgumentException – "Recipient is undefined". Occurs when you have failed to define the intended recipient of the SAML response.
  3. SignicatException  – "The SAML response is not signed". This would theoretically happen if an attacker was trying to send unsigned SAML responses to your application.
  4. SignicatException – "The response ID ffff-ffff-ffff-ffff-ffff has already been used and cannot be reused". In the event that an attacker is able to intercept a SAML response and tries to re-use it, then this exception message would be produced in order to indicate that an already consumed SAML response is attempted to be reused.
  5. SignicatException – "Assertion conditions not present". Signicat will always include assertion conditions (such as the validity period) in a SAML response. If these are missing, the response is considered invalid.
  6. SignicatException – "HasNotBefore and HasNotOnOrAfter is required". Specifically, the validity period must always be specified.
  7. SignicatException – "The SAML response is not yet valid ...". This situation would occur if there is a mismatch between Signicat server clocks and your server clocks. Please refer to How to use time skew when verifying SAML responses.
  8. SignicatException – "The SAML response validity period has expired ...". This situation would occur if there is a mismatch between Signicat server clocks and your server clocks. Please refer to How to use time skew when verifying SAML responses.
  9. SignicatException – "Recipient mismatch ...". Occurs if the SAML response contains a recipient which differs from the input to the Verify method.
  10. SignicatException – "Failed to verify SAML response signature. ...". Indicates that the SAML response has been tampered with, or that the certificate with which it was signed is unexpected or not issued by the expected issuer. The exception message will contain information regarding why the signature verification failed.
  11. SignicatException – "SAML response status code = ..., message = ...". The SAML response was verified, but the authentication process was not successful. The end user may have cancelled or did not have the right certificate etc.

Full example code