This repo contains a minimal example app built with C# and ASP.NET Core that supports SAML using the SSOReady C# SDK.
SSOReady is an open-source way to add SAML and SCIM support to your application.
To check out this repo yourself, you'll need a working installation of dotnet
.
Then, run:
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
Then, visit http://localhost:5293.
There are two steps involved in implementing SAML:
- Initiating SAML logins, where you redirect the user to their corporate identity provider
- Handling SAML logins, where you log the user in after they've authenticated using SAML.
In this demo app, initiating SAML logins happens from the /saml-redirect
endpoint:
app.MapGet("/saml-redirect", async (string email) =>
{
var redirectResponse = await ssoready.Saml.GetSamlRedirectUrlAsync(new GetSamlRedirectUrlRequest
{
// convert john.doe@example.com to just example.com
OrganizationExternalId = email.Split("@")[1]
});
return Results.Redirect(redirectResponse.RedirectUrl!);
});
You initiate a SAML login by calling
Saml.GetSamlRedirectUrlAsync
and redirecting to the returned URL.
The
OrganizationExternalId
is to tell SSOReady which customer's corporate identity provider you want to
redirect to. In the demo app, we use example.com
or example.org
as the
organization external
ID.
After your user finishes authenticating over SAML, SSOReady will redirect them
back to your application. In this demo app, that callback URL is configured to
be http://localhost:5293/ssoready-callback
, so you'll get requests that look
like this:
GET http://localhost:5293/ssoready-callback?saml_access_code=saml_access_code_...
Here's how the demo app handles those requests:
app.MapGet("/ssoready-callback", async (HttpContext context, [FromQuery(Name = "saml_access_code")] string samlAccessCode) =>
{
var redeemResponse = await ssoready.Saml.RedeemSamlAccessCodeAsync(new RedeemSamlAccessCodeRequest
{
SamlAccessCode = samlAccessCode
});
context.Session.SetString("email", redeemResponse.Email!);
return Results.Redirect("/");
});
You handle a SAML login by calling
Saml.RedeemSamlAccessCodeAsync
with the saml_access_code
query parameter value, and logging the user in from
the Email
SSOReady returns to you.
And that's it! That's all the code you have to write to add SAML support to your application.
To make this demo app work out of the box, we did some work for you. You'll need to follow these steps yourself when you integrate SAML into your app.
The steps we took were:
-
We signed up for SSOReady at https://app.ssoready.com.
-
We created an environment, and configured its redirect URL to be
http://localhost:5293/ssoready-callback
. -
We created an API key. Because this is a demo app, we hard-coded the API key. In production apps, you'll instead put that API key secret into an
SSOREADY_API_KEY
environment variable on your backend. -
We created two organizations, both of which use DummyIDP.com as their "corporate" identity provider:
- One organization has external
ID
example.com
and a domain whitelist of justexample.com
. - The second organization has extnernal ID
example.org
and domain whitelistexample.org
.
- One organization has external
ID
In production, you'll create a separate organization for each company that wants SAML. Your customers won't be using DummyIDP.com; that's just a SAML testing service that SSOReady offers for free. Your customers will instead be using vendors including Okta, Microsoft Entra, and Google Workspace. From your code's perspective, those vendors will all look exactly the same.
This demo app gives you a crash-course demo of how to implement SAML end-to-end. If you want to see how this all fits together in greater detail, with every step described in greater detail, check out the SAML quickstart or the rest of the SSOReady docs.