Authenticate users with WS-Federation in ASP.NET Core

This tutorial demonstrates how to enable users to sign in with a WS-Federation authentication provider like Active Directory Federation Services (ADFS) or Azure Active Directory (AAD). It uses the ASP.NET Core 2.0 sample app described in Facebook, Google, and external provider authentication.

For ASP.NET Core 2.0 apps, WS-Federation support is provided by Microsoft.AspNetCore.Authentication.WsFederation. This component is ported from Microsoft.Owin.Security.WsFederation and shares many of that component's mechanics. However, the components differ in a couple of important ways.

By default, the new middleware:

  • Doesn't allow unsolicited logins. This feature of the WS-Federation protocol is vulnerable to XSRF attacks. However, it can be enabled with the AllowUnsolicitedLogins option.
  • Doesn't check every form post for sign-in messages. Only requests to the CallbackPath are checked for sign-ins. CallbackPath defaults to /signin-wsfed but can be changed via the inherited RemoteAuthenticationOptions.CallbackPath property of the WsFederationOptions class. This path can be shared with other authentication providers by enabling the SkipUnrecognizedRequests option.

Register the app with Active Directory

Active Directory Federation Services

  • Open the server's Add Relying Party Trust Wizard from the ADFS Management console:

Add Relying Party Trust Wizard: Welcome

  • Choose to enter data manually:

Add Relying Party Trust Wizard: Select Data Source

Add Relying Party Trust Wizard: Configure Certificate

  • Enable support for WS-Federation Passive protocol, using the app's URL. Verify the port is correct for the app:

Add Relying Party Trust Wizard: Configure URL

Note

This must be an HTTPS URL. IIS Express can provide a self-signed certificate when hosting the app during development. Kestrel requires manual certificate configuration. See the Kestrel documentation for more details.

  • Click Next through the rest of the wizard and Close at the end.

  • ASP.NET Core Identity requires a Name ID claim. Add one from the Edit Claim Rules dialog:

Edit Claim Rules

  • In the Add Transform Claim Rule Wizard, leave the default Send LDAP Attributes as Claims template selected, and click Next. Add a rule mapping the SAM-Account-Name LDAP attribute to the Name ID outgoing claim:

Add Transform Claim Rule Wizard: Configure Claim Rule

  • Click Finish > OK in the Edit Claim Rules window.

Azure Active Directory

  • Navigate to the AAD tenant's app registrations blade. Click New application registration:

Azure Active Directory: App registrations

  • Enter a name for the app registration. This isn't important to the ASP.NET Core app.
  • Enter the URL the app listens on as the Sign-on URL:

Azure Active Directory: Create app registration

  • Click Endpoints and note the Federation Metadata Document URL. This is the WS-Federation middleware's MetadataAddress:

Azure Active Directory: Endpoints

  • Navigate to the new app registration. Click Settings > Properties and make note of the App ID URI. This is the WS-Federation middleware's Wtrealm:

Azure Active Directory: App registration properties

Add WS-Federation as an external login provider for ASP.NET Core Identity

  • Add a dependency on Microsoft.AspNetCore.Authentication.WsFederation to the project.

  • Add WS-Federation to the Configure method in Startup.cs:

    services.AddIdentity<ApplicationUser, IdentityRole>()
        .AddEntityFrameworkStores<ApplicationDbContext>()
        .AddDefaultTokenProviders();
    
    services.AddAuthentication()
        .AddWsFederation(options =>
        {
            // MetadataAddress represents the Active Directory instance used to authenticate users.
            options.MetadataAddress = "https://<ADFS FQDN or AAD tenant>/FederationMetadata/2007-06/FederationMetadata.xml";
    
            // Wtrealm is the app's identifier in the Active Directory instance.
            // For ADFS, use the relying party's identifier, its WS-Federation Passive protocol URL:
            options.Wtrealm = "https://localhost:44307/";
    
            // For AAD, use the App ID URI from the app registration's Properties blade:
            options.Wtrealm = "https://wsfedsample.onmicrosoft.com/bf0e7e6d-056e-4e37-b9a6-2c36797b9f01";
        });
    
    services.AddMvc()
     // ...
    

The call to AddIdentity configures the default scheme settings. The AddAuthentication(String) overload sets the DefaultScheme property. The AddAuthentication(Action<AuthenticationOptions>) overload allows configuring authentication options, which can be used to set up default authentication schemes for different purposes. Subsequent calls to AddAuthentication override previously configured AuthenticationOptions properties.

AuthenticationBuilder extension methods that register an authentication handler may only be called once per authentication scheme. Overloads exist that allow configuring the scheme properties, scheme name, and display name.

Log in with WS-Federation

Browse to the app and click the Log in link in the nav header. There's an option to log in with WsFederation: Log in page

With ADFS as the provider, the button redirects to an ADFS sign-in page: ADFS sign-in page

With Azure Active Directory as the provider, the button redirects to an AAD sign-in page: AAD sign-in page

A successful sign-in for a new user redirects to the app's user registration page: Register page

Use WS-Federation without ASP.NET Core Identity

The WS-Federation middleware can be used without Identity. For example:

public void ConfigureServices(IServiceCollection services)
{
    services.AddAuthentication(sharedOptions =>
    {
        sharedOptions.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        sharedOptions.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        sharedOptions.DefaultChallengeScheme = WsFederationDefaults.AuthenticationScheme;
    })
    .AddWsFederation(options =>
    {
        options.Wtrealm = Configuration["wsfed:realm"];
        options.MetadataAddress = Configuration["wsfed:metadata"];
    })
    .AddCookie();
}

public void Configure(IApplicationBuilder app)
{
    app.UseAuthentication();
        // …
}