Implementing Single Sign-on Integration With SAML Providers Using C#

What Is Single Sign-on at All?

Suppose you have a web application that people are using to do one thing X, but you are doing it great. For example, it would be a web store allowing to order a custom T-shirt printing by uploading some funny and pretty images found on the internet.

You are looking for ways to extend its functionality by adding some more capabilities for your users, but you don't want to lose the focus on this thing that you are doing best of all. 

One way would be to integrate your web application with other services, such as a cool image provider, a trends meter, a delivery service, etc. It would allow your users to seamlessly move between different services (for example: looking for a cool image, checking trends, and uploading this image to your custom printing service) and do multiple things using only your web application.

Single Sign-On simplifies authentication flow and allows your users to sign in only once (on your web application) with their login/password (or even more innovative mechanisms, like FIDO2, if you use such) and use more integrated services by simple clicks without the need to log in again and again. It allows you to extend the functionality of your product by adding more value with relatively low investments.

SAML 2.0

SAML is one of the standard ways of doing Single Sign-On. For a long time, extensive enterprise services use this mechanism as one of the most secure and proven methods to exchange sensitive authentication and authorization information, like logins, passwords, emails, user accounts, etc. But it's not that complicated to add this solution between smaller businesses and enable cool integrations.

SAML is one of the most secure ways to integrate with third-party among many other options. It allows parties to use asymmetric encryption (RSA) based on secure X.509 certificates. As of 2021, the standard is in version 2.

I should note that it might be better for you to trust one of many existing boxed solutions with a proven history and from vendors responsible for their code and overall solution. However, as a developer, I know that businesses may need much more flexibility and customization in their products, so I want to provide more details and working examples using C#, so you can easily reuse this with your ASP.NET application.

SAML Workflow

Usually, the 'classic' SAML workflow includes 3 parties: 

• Service Provider — this is a third-party service you want to integrate with.
• Identity Provider — this is some (enterprise) trusted authentication service, that is able to prove the user identify and tell the Service Provider that 'he is OK!'
• User Agent — a browser with your Web Store opened by a user.

This "classic" scenario is suitable for the enterprise, and we are not going to stop for long here. You can see the workflow diagram below and it is explained in all details on Wikipedia.

However, we are a small business, right? So, usually, we don't have complicated agreements with Enterprise-level Identity Providers, but we still need to integrate with third-party. Let's see how it should look like for us.

The First Step of The Integration

The first thing is an agreement with some service provider to have an integration with your service. This time we focus on SAML protocol specifically, but I know about tenish more custom integration algorithms used by many small and medium-sized services. They use custom HTTP API, REST, WCF, XML, and JSON-based data formats, JWTokens and OAuth, and sometimes even combine all things. Whatever option is used, they need to provide you with some configuration parameters to establish an initial test connection.

For SAML-based integrations, they will ask you to provide so-called "metadata information." That's a small XML file that contains information about your service. This file is being used by service providers representatives to automatically create a certification (aka test) endpoint that would allow you to test the connection, resolve all the roadblocks and certify everything before you go public.

The critical part here is the XML content of this file that must be signed with your private X.509 certificate (aka private key, in terms of RSA). Of course, you have to buy one. Some providers allow using self-signed credentials for testing purposes. That's a matter of your agreement with the service provider.

I've prepared some code that is open source and publicly available on my GitHub account. This small console application allows you to generate a Metadata.xml file and properly sign it with the private key.

Now, you should send your Public X.509 Certificate (as a *.crt file, or PEM text) and this Metadata.xml via a secure channel.

As soon as the service provider replies with some connection endpoints, the first part might be over.

Integration Workflow

You have a web application that implements some authentication workflow and allows users to sign in with their login and password. It means that you are the Identity Provider, and by doing this, you can eliminate some redundant steps and make a process simpler. So, imagine that we combine Identity Provider and your Web Store into one entity, like this:

It simplifies the overall picture. However, it's not that simple under the hood. What actually should happen in the end is we should have an XML document called SAMLResponse prepared and encoded in Base64. You have to send this document via an HTTP POST request to the service provider to authenticate the user and automatically redirect his browser to the third-party target service — see detailed steps in the diagram below.

Again, I've prepared a set of utility classes written in C#, so you can easily see how to execute those steps in your web application.

Below, you can find my comments on every important aspect of that process. But I believe, it will be much easier to follow the steps in class SamlIntegrationSteps.cs > method BuildEncodedSamlResponse(...).

Step 1. Creating SAML assertion XML is not harder than creating a usual XML document. But you have to follow the SAML specification and documentation provided by your Service Provider to use the appropriate field names. A working example is here: SamlAssertionAlgorithms.cs.

AssertionType assertion = new AssertionType

{

    ID = ...Assertion Id ...,

    IssueInstant = ...UTC Time...,

    Version = "2.0",

    Issuer = new NameIDType

    {

        Value = "...your Web Store URL here..."

    },

    Subject = new SubjectType

    {

        Items = new object[]

        {

            new NameIDType

            {

                Format = "urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress",

                Value = userData.GetUserEmail()

            },

            new SubjectConfirmationType

            {

                Method = "urn:oasis:names:tc:SAML:2.0:cm:bearer",

                SubjectConfirmationData = new SubjectConfirmationDataType

                {

                    NotOnOrAfter = ...UTC Time....AddMinutes(3),

                    NotOnOrAfterSpecified = true,

                    Recipient = settings.Recipient

                }

            }

        }

    },

    Conditions = new ConditionsType

    {

        NotBefore = ...UTC Time...,

        NotBeforeSpecified = true,

        NotOnOrAfter = ...UTC Time....AddMinutes(3),

        NotOnOrAfterSpecified = true,

        Items = ...conditions that you need...

    },

    Items = new StatementAbstractType[]

    {

        new AttributeStatementType

        {

            // ReSharper disable once CoVariantArrayConversion

            Items = ...attributes array...

        },

        new AuthnStatementType

        {

            AuthnInstant = ...UTC Time...,

            SessionIndex = ...Assertion Id ...,

            AuthnContext = new AuthnContextType

            {

                ItemsElementName = new [] { ItemsChoiceType5.AuthnContextClassRef },

                Items = new object[] { "urn:federation:authentication:windows" }

            }

        }

    }

};

Step 2. The signing of the SAML assertion can be done as described in official Microsoft docs. A working example is here: SamlAssertionAlgorithms.cs.

Step 3. Encryption of the SAML assertion is implemented in SamlAssertionAlgorithms.cs using System.Security.Cryptography.xml.

xxxxxxxxxx

X509Certificate2 x509 = ...get certificate...

xmlElement.SigningKey = x509.PrivateKey;

xmlElement.SignedInfo.CanonicalizationMethod = SamlSignedXml.XmlDsigExcC14NTransformUrl;

// Create a reference to be signed. 

Reference reference = new Reference

{

    Uri = "#" + referenceValue

};

reference.AddTransform(new XmlDsigEnvelopedSignatureTransform());

reference.AddTransform(new XmlDsigExcC14NTransform());

// Add the reference to the SignedXml object. 

xmlElement.AddReference(reference);

// Add an RSAKeyValue KeyInfo (optional; helps recipient find key to validate). 

KeyInfo keyInfo = new KeyInfo();

keyInfo.AddClause(new KeyInfoX509Data(certificate));

xmlElement.KeyInfo = keyInfo;

// Compute the signature. 

xmlElement.ComputeSignature();

// Put the sign as the first child of main Request tag.

xmlAssertion?.InsertAfter(xmlElement, xmlAssertion.ChildNodes[0]);

Step 4. Adding the assertion document to the SAMLResponse is just about adding XML:

xxxxxxxxxx

XmlDocument encryptedAssertion = new XmlDocument();

// Add namespaces

XmlDeclaration xmlDeclaration = encryptedAssertion.CreateXmlDeclaration("1.0", "UTF-8", null);

XmlElement encryptedRoot = encryptedAssertion.DocumentElement;

encryptedAssertion.InsertBefore(xmlDeclaration, encryptedRoot);

// Form Assertion element

XmlElement encryptedAssertionElement = encryptedAssertion.CreateElement("saml",

    "EncryptedAssertion", "urn:oasis:names:tc:SAML:2.0:assertion");

encryptedAssertion.AppendChild(encryptedAssertionElement);

// Add encrypted content

var encryptedDataNode = encryptedAssertion.ImportNode(encryptedData.GetXml(), true);

encryptedAssertionElement.AppendChild(encryptedDataNode);

// Form a document

var root = xmlDocument.DocumentElement;

var node = root.OwnerDocument.ImportNode(encryptedAssertionElement, true);

root.RemoveChild(xmlAssertionSource ?? throw new InvalidOperationException());

root.AppendChild(node);

Step 5. Signing the SAMLResponse is almost the same as signing the Assertion. A working example is here: SamlResponseAlgorithms.cs.

The End

Some service providers may avoid specific steps and do not require the signature or encryption. In this case, you may remove these parts of the code. Overall, feel free to use my examples in your apps, and I hope this will help you and your application engage users and grow the customer base.

Cheers!

Related Links

Examples of SAML responses.
Tips and Tricks on documenting custom API.