How to implement SAML SSO in C# with ASP.NET core
TLDR: ASP.NET Core example app
Link to example app: https://github.com/ssoready/ssoready-example-app-csharp-aspnetcore-saml
SAML in C#: getting started
If you make business software – especially for big companies – you’ll likely need to support SAML-based single sign-on (SSO) for one or more of your customers.
And, if you’re like most developers, you’ve never implemented SAML SSO before; you’re finding this whole thing very confusing. That’s normal! Please understand that most developers – even very experienced developers – feel the same way about SAML.
Hopefully by the end of this guide, you’re on your way to a safe and easy SAML implementation. We’ll start with some of the basics and then run through a simple example app.
What is SAML?
We should start by understanding SAML very broadly. We don’t need to think too deeply about the particulars of a C# implementation just yet.
We’ve put together a few basic resources to help developers get started:
- A gentle introduction to SAML: This is a casual, conceptual overview of SAML single sign-on that skips over a bunch of details. This is probably a good fit if you’re trying to decide how/when you’re going to handle SAML SSO.
- SAML, a technical primer: This is a more detailed and practical treatment of SAML single sign-on. This is probably a good fit if you need to set up SAML SSO right now. It’ll communicate mostly everything you need to know.
Put very briefly, you’ll use SAML to log users in. Instead of your users presenting you with credentials, they’ll present credentials to a centralized authentication service that your customer controls. (This service is called an identity provider in SAML.)
You’ll communicate with that identity provider using a series of standard steps defined in SAML. You’ll receive claims about users’ identities from the identity provider, and, if you receive valid claims, you’ll authenticate users in your own software.
It’s not that complicated in principle, but the details become really challenging.
Should I implement SAML myself?
Unless you really, really know what you’re doing, you should not be implementing SAML yourself. You should be using a third-party service.
SAML is hard, and it can be really dangerous. It’s just a weird protocol that uses XML digital signatures, which invite all kinds of tricky problems. There are other subtle issues that might not be obvious, e.g. the multi-tenancy considerations that you’ll need to handle. SAML’s hard enough that we see major vulnerabilities crop up after years in widely-used SAML implementations.
More practically, SAML is time consuming. It will take you a really long time to stand up a custom SAML service in production. And then you’ll need someone to maintain it over time. Very few companies will get positive ROI from a homegrown SAML implementation.
SSOReady C# (ASP.Net Core) SDK for SAML SSO
About SSOReady
We make SAML authentication middleware for developers. If you need to support SAML single sign-on in your application, you can use us. We’ll abstract away all the hard stuff.
We build tools for all major programming languages and web development frameworks. For example, we support Python, Javascript, Ruby, Java, and C#, among others. You could also just interface directly with our HTTP API using whatever tech stack you want.
All of our products are fully open source (MIT). We’re venture-funded, and we have real customers that rely on our services in production.
You can learn a bit more at ssoready.com.
SSOReady C# SDK
You can use our SAML middleware using our C# SDK (SSOReady.Client on Nuget). The code’s actually pretty simple!
First, you have to install SSOReady.Client.
nuget install SSOReady.Client
You’ll need an API key. You can get one for free at app.ssoready.com.
From there, you can instantiate an SSOReady client like this:
using SSOReady.Client;
// this loads your SSOReady API key from SSOREADY_API_KEY
var ssoready = new SSOReady.Client.SSOReady();
You’ll need to set up an endpoint that sends your users to their SAML identity provider.
Here’s what that looks like:
// this is how you implement a "Sign in with SSO" button
var redirectResponse = await ssoready.Saml.GetSamlRedirectUrlAsync(new GetSamlRedirectUrlRequest
{
// the ID of the organization/workspace/team (whatever you call it)
// you want to log the user into
OrganizationExternalId = email.Split("@")[1]
});
// redirect the user to `redirectResponse.RedirectUrl`...
And then you’ll need an endpoint that handles SAML logins:
// this goes in your handler for POST /ssoready-callback
var redeemResponse = await ssoready.Saml.RedeemSamlAccessCodeAsync(new RedeemSamlAccessCodeRequest
{
SamlAccessCode = "saml_access_code_..."
});
// log the user in as `redeemResponse.Email` inside `redeemResponse.OrganizationExternalId`...
That’s pretty much it! Please note that this isn’t the documentation. I’ve omitted a bunch of details in order to demonstrate some simplicity. Make sure you spend some time digging into our docs for SSOReady and checkout the GitHub for our C# SDK.
C# (ASP.Net Core) SAML Example App
Get started with an ASP.Net Core SAML example app
It’s surprisingly hard to find a good example app for a SAML implementation written in C#. So we’ve written a maximally simple web application using ASP.NET Core that supports SAML single sign-on.
There’s not even really a front-end. It’s pretty much just a single Program.cs file.
You can run it right now:
git clone https://github.com/ssoready/ssoready-example-app-csharp-asnetcore-saml
cd ssoready-example-app-csharp-asnetcore-saml
dotnet run --project ./WebApplication/WebApplication.csproj
More details live here. Notice that the core logic – once you remove the comments – is only a few lines of code! Pretty simple stuff.
ASP.NET SAML example app FAQs:
Where is the SAML authentication request?
We’ve abstracted this away for you. You don’t need to handle any XML yourself. If you want to see the details, we capture all of the SAML back-and-forth in our web app at app.ssoready.com.
Where is the SAML response?
Just like with the AuthN request, We’ve abstracted this away for you. If you want to see the details, check out app.ssoready.com.
What identity providers does SSOReady support?
SSOReady supports all SAML identity providers, including Microsoft Entra ID (formerly Azure AD), Okta, OneLogin, and many others. We’ve written up some detailed instructions for different identity providers on our docs page, e.g. here for Microsoft Entra ID.
Can I self-host SSOReady?
Yes. Check it the documentation here.
I have a problem. Can you help?
Of course. Please create a github issue at https://github.com/ssoready/ssoready, and we’ll try to fix things for you.
What are some other C# libraries I can use for SAML?
We’re definitely not your only option. There are a handful of alternatives that you might consider.
We sometimes see people download a tool called Componentspace to set up SAML. I’ll admit that I haven’t tried it myself. It covers both ASP.NET and ASP.NET Core, and they have some solid customer logos. They also offer consulting services, which may help you out if you’re just getting started.
I stumbled across this ASP.NET Core library for supporting SAML as a service provider. I can’t personally recommend this service; it may work, but I don’t see a ton of evidence for its widespread adoption.
You may find this tool useful. Compared to other libraries, it comes with reasonably solid documentation. I’m inclined to think this is a viable tool due to its affiliation with the miniOrange consultancy, but I can’t personally vouch for it.
You might also have success using Keycloak. Fair warning: it has been my experience that people find Keycloak complicated. I’m confident that it’ll work, but I can’t promise it’ll be easy.
If I’m missing any good ones, drop me an email at ned.oleary@ssoready.com.