SAML SSO Authentication

What is SAML?

First what is SAML? It is mainly use for authentication. It’s main role is to standardize web applications on authenticating and transfer data between the identity provider and the service provider. It improves user experience and the user will only remember one password through out the enterprise systems.

OAuth vs SAML?

The primary difference between OAuth and SAML is that we mainly use SAML for authentication and OATH for authorization. Think of it like you are boarding an airplane, when you want to ride an airplane, they will ask for your ticket and your ID. Think of SAML as your ID, and OAuth as your ticket. First they will ask you for your ID, to make sure that you are allowed to board the airplane, next they will ask for your ticket to know where is your designated seat#.

Working with SAML

I was tasked to lead the migration project for all our internal tools/application in our my previous company. The project is to move all our internal apps to use the standard enterprise single sign-on using SAML. Currently, our internal apps are using the old SSO built using the old design. We are required to consume the SAML implementation of this SSO.

We use this simple library for consuming the SAML: AspNetSaml

What we did is to create a managed module, register this module to GAC (Global Assembly Cache) of the server and finally just consume the managed module in web.config like so:

<system.webServer>
    <modules>
      <add name="ManagedModule" type="Namespace.ClassName, ProjectName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=999cf99ff999a99e, processorArchitecture=MSIL" preCondition="managedHandler,runtimeVersionv4.0" />
    </modules>
</system.webServer>

This is the basic flow of SAML Implemenatation:

1. When a user access our app, if the user is not yet authenticated our app should redirect our user to SAML provider.

//specify the SAML provider url here, aka "Endpoint"
var samlEndpoint = "http://saml-provider-that-we-use.com/login/";

var request = new AuthRequest(
"http://www.myapp.com", 
"http://www.myapp.com/SamlConsume"
);

//generate the provider URL
string url = request.GetRedirectUrl(samlEndpoint);

//then redirect your user to the above "url" var
//for example, like this:
Response.Redirect(url);

2. From the saml provider, users will enter their credentials and if the entered credential is valid, the saml provider will authenticate and redirect the user to our app as authenticated user.
3. SAML provider will post the samlresponse to our app (eg. http://www.myapp.com/SamlConsume)

//ASP.NET MVC action method... But you can easily modify the code for Web-forms etc.
public ActionResult SamlConsume()
{
    //specify the certificate that your SAML provider has given to you
    string samlCertificate = @"-----BEGIN CERTIFICATE-----
BLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAH123543==
-----END CERTIFICATE-----";

    Saml.Response samlResponse = new Response(samlCertificate);
    samlResponse.LoadXmlFromBase64(Request.Form["SAMLResponse"]); //SAML providers usually POST the data into this var

    if (samlResponse.IsValid())
    {
        //WOOHOO!!! user is logged in
        //YAY!

        //Some more optional stuff for you
        //lets extract username/firstname etc
        string username, email, firstname, lastname;
        try
        {
            username = samlResponse.GetNameID();
            email = samlResponse.GetEmail();
            firstname = samlResponse.GetFirstName();
            lastname = samlResponse.GetLastName();
        }
        catch(Exception ex)
        {
            //insert error handling code
            //no, really, please do
            return null;
        }

        //user has been authenticated, put your code here, like set a cookie or something...
        //or call FormsAuthentication.SetAuthCookie() or something
    }
}

4. Your app will read the samlresponse and if valid will let the user use your app, your app will now handle the roles of the user depending on your policies.

Some additional tips:

• Make sure your app is identifiable by your saml provider.
• Use Firebug to trace your http requests (or any http tracing tool)
• Understand the difference between samlresponse and samlrequest
• Using Firebug you should be able to see the samlresponse.
• If you have multiple web apps that you want to have SSO using your saml provider. I suggest you create an httprequest/httphandler to handle the samlresponse from your provider. You can then install this dll to your server and just add the handler to each web app’s config. No code change require to your web apps. I created a separate article for implementing SAML SSO using managed module, here’s the link.