Introduction
This document explains how to install the SAML2 library and configure it to work with the PureAUTH Identity Platform and make DotNet applications passwordless.
Requirements
ASP.NET Web forms application / ASP.NET web API (.Net framework 4.5/4.6+)
Prerequisite
- SAML2 Library – Author : Michael Hallock
NuGet package installation
- Install the SAML2 Library from Project > Manage NuGet Packages > SAML2 by Michael Hallock
![](https://docs.pureauth.io/wp-content/uploads/2023/08/image-1-2.png)
Add DotNet SAML application on PureAUTH
- Login to https://live.pureauth.io/organizations/login/
- Navigate to the Applications tab.
- Select “Add Application”.
- Select “Custom App”.
![](https://docs.pureauth.io/wp-content/uploads/2023/08/image-2-3.png)
- Enter the Application Name. It could be anything you desire.
- Select Primary (Corporate Email) in the Dataset for email field.
![](https://docs.pureauth.io/wp-content/uploads/2023/08/image3.png)
Instead of localhost, you can use your “https://<domain with port>/Login.ashx“
- In the “SAML Response Endpoint (ACS URL)” field, enter the URL using the following pattern.
https://<domain with port>/Login.ashx
![](https://docs.pureauth.io/wp-content/uploads/2023/08/image-4-3.png)
- In “Audience (Entity ID)” field, enter the URL using the following pattern:
https://<domain with port>/Login.ashx
![](https://docs.pureauth.io/wp-content/uploads/2023/08/image-5-2.png)
- In “SAML Logout Response Endpoint (SLO URL)” field enter the URL using the following pattern:
https://<domain with port>/Login.ashx
![](https://docs.pureauth.io/wp-content/uploads/2023/08/image-6-1.png)
Sign Assertion : Check it please.
![](https://docs.pureauth.io/wp-content/uploads/2023/08/image-7-300x62-1.png)
Library Configuration
- Edit your Web.config.
- Inside <configuration> Section add below SAML.
<configSections>
<section name="saml2" type="SAML2.Config.Saml2Section, SAML2"/>
</configSections>
- Inside <system.webServer> Section add below Handlers and Modules.
<handlers>
<remove name="SAML2.Protocol.Saml20SignonHandler" />
<remove name="SAML2.Protocol.Saml20LogoutHandler" />
<remove name="SAML2.Protocol.Saml20MetadataHandler" />
<add name="SAML2.Protocol.Saml20SignonHandler" verb="*" path="Login.ashx" type="SAML2.Protocol.Saml20SignonHandler, SAML2" />
<add name="SAML2.Protocol.Saml20LogoutHandler" verb="*" path="Logout.ashx" type="SAML2.Protocol.Saml20LogoutHandler, SAML2" />
<add name="SAML2.Protocol.Saml20MetadataHandler" verb="*" path="Metadata.ashx" type="SAML2.Protocol.Saml20MetadataHandler, SAML2" />
</handlers>
<modules>
<remove name="Saml20MetadataFetcher" />
<add name="Saml20MetadataFetcher" type="SAML2.Saml20MetadataFetcherModule" preCondition="managedHandler" />
</modules>
- Inside <configuration> and below </system.webServer> add below SAML.
<saml2>
<allowedAudienceUris>
<audience uri="<Paste the ACS url to be configured in the PureAuth Portal: Example: https://localhost:44333/Login.ashx>" />
</allowedAudienceUris>dsw
<serviceProvider id= "<Must be changed according to the changes in the audience URL. Example: "https://localhost:44333/">" server="<Similar to serviceProvider id. Example : "https://localhost:44333/">" >
<signingCertificate findValue="CN=localhost" storeLocation="LocalMachine" storeName="My" x509FindType="FindBySubjectDistinguishedName" />
<endpoints>
<endpoint type="SignOn" localPath="Login.ashx" redirectUrl="~/api/Values" binding="Post" />
<endpoint type="Logout" localPath="Logout.ashx" redirectUrl="~/Help" />
<endpoint type="Metadata" localPath="Metadata.ashx" />
</endpoints>
<authenticationContexts comparison="Exact">
<add context="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" referenceType="AuthnContextClassRef" />
</authenticationContexts>
</serviceProvider>
<identityProviders metadata= "<Points to a directory that contains the metadata downloaded/generated from the IDP. Example : "C:\Users\ABC\Desktop\MetaPureAuth">" >
<add id= "<SAML Login URL obtained from PureAuth Portal. Example:"https://live.pureauth.io/auth/custom-app-saml/45177dcfc3/fb0593a3-ad58-4d34-beaa-b356c5097492">" default="true" omitAssertionSignatureCheck="false">
<certificateValidations>
<add type="SAML2.Specification.SelfIssuedCertificateSpecification, SAML2" />
</certificateValidations>
</add>
</identityProviders>
<actions>
<clear />
<action name="SetSamlPrincipal" type="SAML2.Actions.SamlPrincipalAction, SAML2" />
<action name="MyAuthentication" type=" "<Replace this with namespace, which we created for custom authentication. Example: PACKAGE>".MyAuthenticationAction, <Same as namespace> " />
<action name="Redirect" type="SAML2.Actions.RedirectAction, SAML2" />
</actions>
</saml2>
- The field highlighted in Red will be the ACS url to be configured in the PureAuth Portal.
- The fields highlighted in Blue must be changed according to the changes in the audience URL (highlighted RED).
- The field highlighted in yellow should be the SAML Login URL obtained from PureAuth Portal.
- The field highlighted in green points to a directory that contains the metadata downloaded/generated from the IDP.
- Generate the metadata by the following steps:
- Go to https://www.samltool.com/idp_metadata.php
- Copy the entity ID from PureAUTH and paste it in the EntityID field.
- Copy the SAML Login URL from PureAUTH and paste it in the Single Sign On Service Endpoint (HTTP-REDIRECT) Field.
- Copy the X509 certificate from PureAUTH and paste it in the SP X.509 cert field.
- Select NameId Format to be emailAddress.
- Scroll down and click “Build IDP metadata“.
- Copy the generated IDP metadata and paste it in Notepad.
- Save it as an .XML file at location given in “Web.config” file.
- Generate the metadata by the following steps:
Example:
<identityProviders metadata="C:\Users\ABC\Desktop\MetaPureAuth">
- Replace the field highlighted in purple with your namespace, which we created for custom authentication.
Add custom Authentication
- Add a custom authentication handler to the root.
The Authentication Handler name should be : MyAuthenticationAction.cs
- Add below complete section in MyAuthenticationAction.cs
using SAML2;
using SAML2.Actions;
using SAML2.Identity;
using SAML2.Protocol;
using System;
using System.Linq;
using System.Security.Claims;
using System.Web;
using System.Web.Security;
namespace <YourNamespace>
{
public class MyAuthenticationAction : IAction
{
#region Implementation of IAction
private string _name = "MyAuthentication";
public string Name
{
get { return _name; }
set { _name = value; }
}
/// <summary>
/// Action performed during login.
/// </summary>
/// <param name="handler">The handler initiating the call.</param>
/// <param name="context">The current http context.</param>
/// <param name="assertion">The saml assertion of the currently logged in user.</param>
public void SignOnAction(AbstractEndpointHandler handler, HttpContext context, Saml20Assertion assertion)
{
var identifier = assertion.Subject.Value;
throw new ArgumentException(identifier);
//Handle Auth Cookies Here
//context.Response.Redirect("~/api/Values");
}
/// <summary>
/// Action performed during logout.
/// </summary>
/// <param name="handler">The handler.</param>
/// <param name="context">The context.</param>
/// <param name="IdPInitiated">During IdP initiated logout some actions such as redirecting should not be performed</param>
public void LogoutAction(AbstractEndpointHandler handler, HttpContext context, bool IdPInitiated)
{
FormsAuthentication.SignOut();
}
#endregion
}
}
Verify SAML Authentication
- Visit the Login.ashx endpoint.
- You will be redirected to PureAuth.
- Open the AuthVR5 app and scan the QR code using Swift Login.