Rsk.Saml v3: Release Notes

SAML support for IdentityServer4 v4 is now available.

Over the past few months, we have been building new features in our SAML IdP & SP component, culminating in 6 minor releases and 2 major releases (more on these later). This includes:

• new features, thanks to sponsored development and popular demand
• new extensibility points, thanks to a major release that allowed us to make some planned breaking changes

With the release of IdentityServer4 version 4, we are now supporting three different major versions of IdentityServer4. To make this simple, we are separating the IdentityServer4 dependency from our core component functionality into an anti-corruption layer that can stay in sync with IdentityServer4 as it evolves.

Our core SAML logic component can now be found in Rsk.Saml. If you want to act as an SP, this is now the package you need to use. If you’re going to act as an IdP, you should continue to use Rsk.IdentityServer4.Saml (which, itself, has a dependency on Rsk.Saml).

The dynamic auth adaptor for our SAML component has also been updated (v1.3.0) to support the new Rsk.Saml dependency.

Which SAML Library Should I Use?

• I am a SAML Service Provider: I want to allow users to log in using an external SAML Identity Provider
  • Use the latest version of Rsk.Saml
• I am a SAML Identity Provider: I want to allow users in external systems to log in using my user store
  • I am using IdentityServer4 v2: use Rsk.IdentityServer4.Saml v3.*
  • I am using IdentityServer4 v3: use Rsk.IdentityServer4.Saml v3.*
  • I am using IdentityServer4 v4: use Rsk.IdentityServer4.Saml v4.*

If you are an existing service provider, you can continue to use Rsk.IdentityServer4.Saml. However, you may miss out on new features that will only be published in the Rsk.Saml library.

Release Notes – v2.9 and v2.10

Before we get into the big v3 changes, here are the highlights from our last two v2 releases:

• SP: Support for the artifact binding type
• SP: Added ValidationCertificates for request signing key rollover
• SP: Added support for Home Realm Discovery (using “IDPList” and “IDPEntry”)
• SP: Added “SamlChallengeProperties” allowing a challenge request to override Home Realm Discovery and Force Authentication

Release Notes – Rsk.Saml v3

With this release, we have discontinued support for .NET Framework and non-LTS or Current versions of .NET Core. That means we, currently, only support .NET Core 2.1 and .NET Core 3.1.

With this initial release, we are still supporting IdentityServer4 v2 and will continue to do so until the end of 2020 (12 months after the last patch). We will continue to support IdentityServer4 v4 for at least another year.

New Features

• IdP: Added support for IdP-Initiated SSO. This allows the user to be forwarded to an SP from within an IdP by clicking on a button. This flow does not offer the same assurances as SP-Initiated SSO. The dangers of this flow are discussed in our article “The Dangers of IdP-Initiated SSO”.
• SP: Added support for IdP-Initiated SLO. This allows an end-user to terminate all sessions by initiating the logout process once, with our SP now handling both SLO requests and responses. SLO is discussed in more detail in our article “The Challenge of Building SAML Single Logout”.

Improvements

• IdP: ACS endpoint preference is now ordered by index
• SP: Now uses the correlation cookie name configured in the handlers cookie builder
• SP: SamlBindingService extended to include support for building SOAP binding payloads
• All custom component exceptions inherit from SamlException

Breaking Changes

• SP: The ISamlCorrelationStore has been updated to include the SAML options and to use the Saml2RequestCorrelationMessage directly as opposed to an encrypted string. The options allow the correlation cookie to be configured per request, and the Saml2RequestCorrelationMessage allows encoding and encryption to use any method you wish. If you have a custom ISamlCorrelationStore, please reach out to support@identityserver.com for more details.
• IdP: Method rename in IServiceProviderStore, from FindServiceProviderByEntityIdAsync to FindServiceProviderByEntityId
• IdP: RequestTrustLength option has been replaced by MessageTrustLength. Its default value is now 5 minutes
• SP: ResponseTrustLength option had been replaced by MessageTrustLength
• SP: The unused RemoteSignOutPath option has been removed
• IdP and SP: RequireSignedSingleLogoutResponses option has been renamed to RequireSignedLogoutResponses
• EF: a new property of RequireAuthenticationRequestsSigned which allows the IdP’s WantAuthnRequestsSigned setting to be overridden per SP
• EF: RequireSamlRequestDestination property renamed to RequireSamlMessageDestination. See below for EF migrations recommendations
• Dropped support for .NET Framework and non-LTS or Current versions of .NET Core
• Obsoletes from v2 have now been removed

2021 Roadmap

For the rest of this year, we are focussing on completing the removal of the IdentityServer4 dependency from our Rsk.Saml library and adding support for the back-channel binding types to stay ahead of the upcoming 3rd party cookie blocking in browsers and to bring ourselves more in line with version 2 of Kantara’s SAML interop profile.

• Full removal of IdentityServer4 from Rsk.Saml
• Support for more back-channel binding types (artifact binding)
• Focus on improving documentation with feature specific documentation
• Support for “traditional” SAML SLO (not using iFrames)
• Additional documentation for debugging steps and FAQs
• Stretch goal: revamp of signing and encryption algorithm support

Our feature development is heavily influenced by customer feedback. So, if you have any feature requests, let us know!

Bonus: EF Migrations

In version 3, we have renamed a database column. This is annoying, we know, but it has enabled us to reuse an existing configuration setting for new features rather than creating 2 new settings.

If you are using EF migrations, once you create your new migrations, we recommend that you replace the following “DropColumn” and “AddColumn” with a call to “RenameColumn”.

Remove:

migrationBuilder.DropColumn(
  name: "RequireSamlRequestDestination",
  table: "ServiceProviders");

migrationBuilder.AddColumn<bool>(
  name: "RequireSamlMessageDestination",
  table: "ServiceProviders",
  nullable: false,
  defaultValue: false);

Add:

migrationBuilder.RenameColumn(
  name: "RequireSamlRequestDestination", 
  table: "ServiceProviders",
  newName: "RequireSamlMessageDestination");