Overview

Side claims enrichment allows an implementer to configure the Ed-Fi dashboard application to authenticate with a third party Security Token Service (STS), and amend the claims received from that STS to include the claims that the dashboard application requires for user authorization. This feature was introduced in Ed-Fi Dashboards v1.3.

Terms

Key terms used in this documentation include:

Claim. The Ed-Fi dashboard application requires a particular set of claims in order to determine what data a user may view, and what actions that user may perform. If a user does not have the required claims, the user may be authenticated against the application, but would not be able to view data or do much of anything.
Ed-Fi STS. The Ed-Fi dashboard ships with an STS included, and is located in the EdFi. Dashboards.SecurityTokenService.Web project. By default, the dashboard application will authenticate and authorize (i.e., apply claims) on the STS side.
STS (Security Token Service). This software-based identity provider is responsible for issuing security tokens, especially software tokens as part of a claims-based identity system. In a typical usage scenario, a client requests access to a secure software application often called a relying party (RP).
WIF (Windows Identity Foundation). The Windows Identity Foundation is a Microsoft software framework for building identity-aware applications. It provides APIs for building STSs as well as tools for building claims-aware and federation-capable applications.

Technical Components

Components discussed in this documentation include:

Dashboard WIF configuration. Exists in the Web.config of the EdFi .Dashboards.Presentation.Web application. It is located in the microsoft.identityModel configuration section.
Dashboard configuration-specific installers. Located in the EdFi.Dashboards.Presentation.Web.Utilities.CastleWindsor namespace.
- ISignInRequestMessageProvider. Handles attaching any necessary data to the sign-in request message before it goes to the STS to authenticate. This information is used to establish context when the token is posted pack to the Ed-Fi dashboard application. The existing implementation should work for most scenarios.
- IClaimsAuthenticationManagerProvider. Handles amending the token with Dashboard Claims.
STS configuration-specific installers. Located in the EdFi.Dashboards.SecurityTokenService.Web.Utilities.CastleWindsor namespace.
- IGetOutputClaimsIdentityProvider. Once the STS has authenticated the user, this implementation will apply claims.

Claim Scenarios and Configuration

This section describes how to configure claims for three scenarios.

Scenario 1: Ed-Fi STS Identity Provider
Scenario 2: Ed-Fi STS Identity Provider & Claims Provider
Scenario 3: Third-Party STS Identity Provider

These scenarios and their configuration details are described in detail below.

Scenario 1: Ed-Fi STS Identity Provider

In this scenario the STS acts only as the Identity Provider. It will only authenticate the user and apply a few basic claims to identity that user (claims such as name and email). The Ed-Fi dashboard application will be responsible for amending the claims once the token is validated on the client side to include the necessary dashboard claims. This method is used to simulate in-development authenticating to a third-party STS, such as ADFS 2.0.

Configuration Details

The configuration for Scenario 1 is as follows:

Dashboard WIF configuration. By default the application should be configured to point to the developer STS.Dashboard configuration-specific installers. These are located in the EdFi.Dashboards.Presentation.Web.Utilities.CastleWindsor namespace.
- ISignInRequestMessageProvider: Should be using SecurityTokenServiceSignInRequestMessageProvider.
- IClaimsAuthenticationManagerProvider: Should be using DashboardClaimsAuthenticationManagerProvider.

 protected override void RegisterISignInRequestMessageProvider(IWindsorContainer container)
    {
    	container.Register(Component
    		.For<ISignInRequestMessageProvider>()
       		.ImplementedBy<SecurityTokenServiceSignInRequestMessageProvider>());
    }

  protected override void RegisterIClaimsAuthenticationManagerProvider(IWindsorContainer container)
    {
    	container.Register(Component
    		.For<IClaimsAuthenticationManagerProvider>()
    		.ImplementedBy<DashboardClaimsAuthenticationManagerProvider>());
    }

STS configuration-specific installers. Located in the EdFi.Dashboards.SecurityTokenService.Web.Utilities.CastleWindsor namespace.

- IGetOutputClaimsIdentityProvider. Should be using IdentityClaimsGetOutputClaimsIdentityProvider.

protected virtual void RegisterIGetOutputClaimsIdentityProvider(IWindsorContainer container)
{
    container.Register(Component
    	.For<IGetOutputClaimsIdentityProvider>()
    	.ImplementedBy<IdentityClaimsGetOutputClaimsIdentityProvider>());
}

Scenario 2: Ed-Fi STS Identity Provider & Claims Provider

In this scenario the STS not only authorizes the user, but also issues dashboard claims. This is a helpful configuration if you do not have an existing STS for your organization or if you are not ready to add the dashboards as a relying party to your existing STS.

Configuration Details

The configuration details for Scenario 2 are as follows:

Dashboard WIF configuration. By default the application should be configured to point to the developer STS.
Dashboard configuration-specific installers. Located in the EdFi.Dashboards.Presentation.Web.Utilities.CastleWindsor namespace.
- ISignInRequestMessageProvider. Should be using SecurityTokenServiceSignInRequestMessageProvider.
- IClaimsAuthenticationManagerProvider. Should be using PassThroughClaimsAuthenticationManagerProvider.

protected override void RegisterISignInRequestMessageProvider(IWindsorContainer container)
{
    container.Register(Component
    	.For<ISignInRequestMessageProvider>()
    	.ImplementedBy<SecurityTokenServiceSignInRequestMessageProvider>());
}

protected override void RegisterIClaimsAuthenticationManagerProvider(IWindsorContainer container)
{
    container.Register(Component
    	.For<IClaimsAuthenticationManagerProvider>()
    	.ImplementedBy<PassThroughClaimsAuthenticationManagerProvider>());
}

STS configuration-specific installers. Located in the EdFi.Dashboards.SecurityTokenService.Web.Utilities.CastleWindsor namespace.
- IGetOutputClaimsIdentityProvider. Should be using DashboardClaimsGetOutputClaimsIdentityProvider.

protected virtual void RegisterIGetOutputClaimsIdentityProvider(IWindsorContainer container)
{
    container.Register(Component
        .For<IGetOutputClaimsIdentityProvider>()
        .ImplementedBy<DashboardClaimsGetOutputClaimsIdentityProvider>());
}

Scenario 3: Third-Party STS Identity Provider

In this scenario you authenticate off of a third-party STS, such as ADFS 2.0. ADFS 2.0 provides mechanisms for applying application claims, but it requires that the STS be able to access the information necessary to build the claims. For the Ed-Fi dashboard application this information resides in a SQL database and may not be accessible directly by the STS.

To support this scenario, a Client-Side Claims Enrichment has been implemented that allows the claims to be decorated on the client-side by the dashboard application itself.

Configuration Details

The configuration details for Scenario 3 are as follows:

Dashboard WIF configuration. Consult the documentation of your STS for configuration information. It is important that the STS be compatible with WIF 4. Using FedUtil.exe to configure your Web.config is very helpful, but to use the tool you will need to download and Windows Identity Foundation SDK v4.0.
Dashboard configuration-specific installers. Located in the EdFi.Dashboards.Presentation.Web.Utilities.CastleWindsor namespace.
- ISignInRequestMessageProvider: The default SecurityTokenServiceSignInRequestMessageProvider should work for most scenarios.
- IClaimsAuthenticationManagerProvider: You may need to write your own implementation of this class. It is important to identify what key you will use to tie your users in the STS to a particular record in the StaffInformation table (StaffUSI). From that point you can use the existing code to learn how to use a StaffUSI to produce a claims tree.
STS configuration-specific installers. No changes are needed here since you will be using a third-party STS. During development it is sometimes helpful to implement your own version of IGetOutputClaimsIdentityProvider to simulate what the actual STS will return in development environments

Other Scenarios: 3rd Party STS Identity Provider and Claims Provider

Under this scenario a third party STS would provide authentication claims as well as dashboard application claims much in the same way as the Scenario 1, but with the third party STS performing all the functions of the Ed-Fi STS. The Dashboard WIF configuration would be identical to Scenario 3.

Claims used by the Ed-Fi dashboard may be found in the "EdFi.Dashboards.SecurityTokenService.Authentication" project in the static class EdFiClaimTypes.