We frequently help Product Owners and Development Teams add SAML 2.0 authentication to C# and ASP.NET applications, and we wanted to share an overview of what is involved with moving from username/password based authentication to single sign-on via SAML.
This article is not meant to be an in-depth tutorial on the SAML authentication protocol. We give you an overview of the different implementation options and trade-offs as well as addressing common questions about the effort required to turn your C# or ASP.NET application into a SAML Service Provider.
There are three main approaches to adding SAML authentication to a C# or ASP.NET application:
- Use a Commercial SAML Component
- Use Shibboleth integrated with IIS as your Service Provider
- Use an Open Source SAML Library
Option #1 – Commercial SAML Component
There are two popular commercial SAML components available for C# and ASP.NET – ComponentSpace ($499 for a single developer license) and ComponentPro’s Ultimate SAML ($299 for Standard Edition single developer license). Both of these libraries give you a software-based SAML Service Provider complete with documentation, examples and support. These libraries also include a SAML Identity Provider, which is useful for testing. You can download a free evaluation version of both libraries.
- You will not have to implement any of the SAML protocol in your application
- Commercial support and software updates are available
- Test IdP is included
- Ideal for SaaS applications (i.e. if you are not using IIS to host your app, your app is multi-tenant and/or your want to implement self-service for users to add their IdP metadata)
- Free 30 day trial with example Visual Studio projects
- You could say cost is a con, but going with a commercial SAML component is typically more cost effective than trying to adapt an open source SAML library or writing the SAML authentication code by hand
- If your application is redistributed or white labeled, you need to read the license terms carefully
Other implementation considerations:
- If you are selling your app to higher-education customers, you may want to pick Shibboleth as your SAML Service Provider solution because it is widely used in higher-education, and it will likely save you some headaches. Shibboleth has the capability to fetch metadata from a “feed”. The commercial and open source SAML libraries for C# and ASP.net do not have this capability.
Option #2 – Shibboleth Service Provider
Shibboleth is a mature open source SAML Service Provider implementation that integrates with IIS as an ISAPI filter. The best way to think about Shibboleth is that you are relying on a web server module to handle the SAML authentication.
You would configure Shibboleth to protect a route on your web server (eg. /secure), and when you browse to the “Shibboleth-protected” URL, the Shibboleth ISAPI filter is triggered and takes care of all of the SAML authentication steps.
Control will only be passed to your application after a successful IdP authentication. Shibboleth takes the user attributes from the Identity Provider’s SAML Response and sets Server Variables. In your application, you would check the value of the Server Variables in order to make an access control decision.
- Shibboleth is open source software, so there are no license costs
- Shibboleth is ideal for situations where you run your own IIS server, and you do not have a requirement to allow self-service configuration changes
- Shibboleth is the preferred SAML Service Provider for Identity Federations like InCommon
- A Shibboleth implementation could save you time over a software based SAML service provider implementation and might be the best approach if you have legacy software that you need to SAML-enable. The only code modification required would be to look for Server Variables set by Shibboleth after a successful IdP login
- Commercial support for Shibboleth is available
- Shibboleth uses configuration files. The Shibboleth Service must be restarted when the config files are updated
- Shibboleth is Java based and can be a bit of a memory hog when running on Windows, especially if you join an Identity Federation or turn on debugging
- Advanced Shibboleth configurations can be a little tricky to implement
- You will likely need a test Identity Provider. TestShib is one available option
Option #3 – Open Source SAML Service Provider Libraries
We typically do not recommend using the available open source C# and ASP.NET SAML Service Provider libraries for production implementations. The available open source libraries are either missing key features of the SAML protocol (eg. logout, decrypting assertions, etc.) or are complex and come with a lot of dependencies.
You may be able to get away with using an open source SAML SP implementation, but your Dev Team will likely be spending valuable time implementing missing SAML functionality, and your total cost of ownership will be higher than if you just purchased a commercial SAML component.
Recently there have been improvements in this area, and we can recommend looking at the Sustainsys/Saml2 SAML library to see if it will meet your needs.
There are two other open source SAML SP libraries that we have worked with, but we do not recommend using these libraries in production because they are missing key features:
We have been working with customers to help add SAML authentication to thick and mobile applications. Since SAML is a web-based authentication flow, and not many SAML Identity Providers support the SAML Enhanced Client or Proxy (ECP) profile, the best option for adding SAML authentication to iOS, Android and thick applications is to use an embedded web browser.
Okta has published a good example of the embedded web browser approach for SAML authentication to an iOS application. In Okta’s example OAuth is used to impersonate the logged in user after a successful SAML authentication, but this extra step might not be necessary depending on your use case.
The diagram below shows a simplified version of the authentication flow without the extra OAuth step. Note that a SAML Service Provider is required as part of this architecture, and this approach will not work well if the customers SAML Identity Provider is hidden behind a firewall.