WS-Federation Integration with Duende IdentityServer

IdentityServer allows your ASP.NET Core website to act as an OpenID Provider and OAuth authorization server, providing single sign-on (SSO) across your applications.

But what if you want to allow WS-Federation applications to use your SSO solution? Do you need to spin up a custom gateway to bridge protocols? Can you support them within your existing IdentityServer installation?

This is where our Rock Solid Knowledge WS-Federation component comes in.

In this tutorial, you’ll learn how to use our WS-Federation component to enable Duende IdentityServer or IdentityServer4 to act as a WS-Federation Identity Provider (IdP).

RSK WS-Federation Component

Our WS-Federation component allows you to support the WS-Federation protocol within your IdentityServer, allowing some applications to authenticate with your IdentityServer using WS-Federation and others using OpenID Connect. Both protocols share the same SSO session, providing the user with a single sign-on experience.

All the WS-Federation interactions are abstracted away in the IdentityServer, allowing for seamless cross-protocol SSO.

Getting Started

Project Setup

This article will build upon the basic in-memory IdentityServer template, which adds a basic UI, test users, and in-memory clients and resources. You can install this template using the IdentityServer .NET CLI command dotnet new isinmem.

You can find the completed source code for this article on GitHub.

License

Our WS-Federation component requires a valid license. You can get a demo license by signing up on our products page or reaching out to us at [email protected].

Install RSK WS-Federation library

You will need to install our IdentityServer-specific WS-Federation library.

Duende IdentityServer WS-Federation library:

dotnet add package Rsk.WsFederation.DuendeIdentityServer

IdentityServer4 WS-Federation library:

dotnet add package Rsk.WsFederation.IdentityServer4

IdentityServer as a WS-Federation Identity Provider

To enable applications to authenticate with your IdentityServer using WS-Federation, you must register our plugin by updating the call to AddIdentityServer with the following:

services.AddIdentityServer()
   // the rest of IdentityServer registrations (clients, resources, users, etc)
   .AddSigningCredential(new X509Certificate2("your private signing key", "password"))
   . AddWsFederationPlugin(options => { 
       options.Licensee = “DEMO";
       options.LicenseKey = "your DEMO licenseKey";   })
   .AddInMemoryRelyingParties(new List<Rsk.WsFederation.Models.RelyingParty>());

The AddWsFederationPlugin adds the necessary WS-Federation dependencies. You need to provide the licencee and license key that you acquired in the Getting Started section.

The AddInMemoryRelyingParties adds a separate store for relying party configuration data. This is similar to our SAML component that has a separate ServiceProviders store. However, relying party configuration entries are optional for now. More on this later.

Our WS-Federation component uses the IdentityServer key store to extract the configured keys. We require X509 certificates and RS256 keys. This means that you won't be able to use the AddDeveloperSigningCredential registration from IdentityServer. Instead, you will need to use AddSigningCredential or the Automatic Key Management feature. If you are still developing, you can find a private key for development in the completed source code for this repository. Otherwise, you can use makecert, OpenSSL, or PowerShell to generate a new key.

And finally, you need to add WS-Federation to the middleware by chaining the call to UseIdentityServer.

app.UseIdentityServer()
   .UseIdentityServerWsFederationPlugin();

This allows your IdentityServer to start handling calls to the WS-Federation endpoints.

WS-Federation Identity Provider Metadata

You can now retrieve your WS-Federation metadata by visiting the path /wsfed. Your metadata contains all the information that relying parties need to integrate with you, such as your unique EntityId, PassiveRequestorEndpoint, and public signing key. Your metadata document can be loaded in by relying parties so that they can automatically configure themselves to use your identity provider.

Adding a WS-Federation Relying Party

Now that IdentityServer has been configured to handle the WS-Federation protocol, you can define a relying party that can authenticate using your IdentityServer. To do this, you need to create the usual Client entry within IdentityServer, for example:

new Client
{
    ClientId = "rp1",
    AllowedScopes = { "openid", "profile" },
    RedirectUris = { "https://localhost:5001/signin-wsfed" },
    ProtocolType = IdentityServerConstants.ProtocolTypes.WsFederation
};

This uses the usual Client entity, specifying the client ID as the expected entity ID of the relying party. The claims that the relying party will receive are controlled by the identity scopes, with the claim types then being mapped by either the defaults in the WsFederationOptions or the RelyingParty configuration you’ll see shortly. The protocol type must be wsfed, and the RedirectUris must contain the incoming wreply value.

To override default settings within the WsFederationOptions for an individual relying party, you can create a RelyingParty record alongside the client one. This entity must have a Realm that matches the ClientId on the client record.

var relyingPartyOverrides = new RelyingParty
{
    Realm = "rp1",
    TokenType = WsFederationConstants.TokenTypes.Saml11TokenProfile11,
    ClaimMapping = new Dictionary<string, string> { { JwtClaimTypes.Name, ClaimTypes.Name } }
};

Source Code

You can find the completed source code for this article on GitHub.

Next Steps

This tutorial covered the basics of enabling your Duende IdentityServer or IdentityServer4 to act as a WS-Federation Identity Provider. This should get you started, but don't forget to use a persistent RelyingParty store instead of the in-memory store before going into production.

If you ran into any issues or have any questions, please get in touch with us at [email protected]. Otherwise, check out our product documentation for feature-specific details.