A Blazor app supporting both hosting models, Blazor WebAssembly and Blazor Server, a WebApi for accessing data and an Identity Provider for authentication. Based on the blazor-solution-setup repository.
\
Headway is a framework for building configurable Blazor applications fast. It is based on the blazor-solution-setup project, providing a solution for a Blazor app supporting both hosting models, Blazor WebAssembly and Blazor Server, a WebApi for accessing data and an Identity Provider for authentication.
To help get you started the Headway framework comes with seed data that provides basic configuration for a default navigation menu, roles, permissions and a couple of users.
The default seed data comes with two user accounts which will need to be registered with an identity provider that will issue a token to the user containing a RoleClaim called
headwayuser. The two default users are:
|User|Headway Role|Indentity Provider RoleClaim|
|——|——————|——————————————|
|alice@email.com|Admin|headwayuser|
|grant@email.com|Developer|headwayuser|
The database and schema can be created using EntityFramework Migrations.
An example application will be created using Headway to demonstrate features available the Headway framework including, configuring dynamically rendered page layout, creating a navigation menu, configuring a workflow, binding page layout to the workflow, securing the application using OAuth 2.0 authentication and restricting users access and functionality with by assigning roles and permissions.
The example application is called RemediatR. RemediatR will provide a platform to refund (remediate or redress) customers that have been wronged in some way e.g. a customer who bought a product that does not live up to it’s commitments. The remediation flow will start with creating the redress case with the relevant data including customer, redress program and product data. The case progresses to refund calculation and verification, followed by sending a communication to the customer and finally end with a payment to the customer of the refunded amount.
Different users will be responsible for different stages in the flow. They will be assigned a role to reflect their responsibility. The roles will be as follows:
The RemediatR Flow is as follows:
RemediatR can be built using the Headway platform in several easy steps involving creating a few models and repository layer, and configuring the rest.
This example uses EntityFramework Code First.
- In Headway.RemediatR.Repository
- Add a reference to project Headway.Repository
- Add a reference to project Headway.RemediatR.Core
- Create RemediatRRepository class.
- In Headway.Repository
- Add a reference to project Headway.RemediatR.Core
- Update ApplicationDbContext with the models
- Create the schema and update the database
- In Visual Studio Developer PowerShell
> cd Headway.WebApi> dotnet ef migrations add RemediatR --project ..\Utilities\Headway.MigrationsSqlServer> dotnet ef database update --project ..\Utilities\Headway.MigrationsSqlServer
builder.Services.AddScoped<IRemediatRRepository, RemediatRRepository>();GetCountryOptionItems method to OptionsRepository<PackageReference Include="FluentValidation.AspNetCore" Version="11.1.2" ></PackageReference>
builder.Services.AddControllers().AddFluentValidation(fv => fv.RegisterValidatorsFromAssembly(Assembly.Load("Headway.RemediatR.Core")))
<PackageReference Include="FluentValidation" Version="11.1.0" ></PackageReference>
app.UseAdditionalAssemblies(new[] { typeof(Redress).Assembly });
In Headway.BlazorWebassemblyApp
builder.Services.UseAdditionalAssemblies(new[] { typeof(Redress).Assembly });
Seed data for RemediatR permissions, roles and users can be found in RemediatRData.cs.
Alternatively, permissions, roles and users can be configured under the Authorisation category in the Administration module.
Seed data for RemediatR navigation can be found in RemediatRData.cs
Alternatively, modules, categories and menu items can be configured under the Navigation category in the Administration module.
Blazor applications use token-based authentication based on digitally signed JSON Web Tokens (JWTs), which is a safe means of representing claims that can be transferred between parties.
Token-based authentication involves an authentication server issuing an athenticated user with a token containing claims, which can be sent to a resource such as a WebApi, with an extra authorization header in the form of a Bearer token. This allows the WebApi to validate the claim and provide the user access to the resource.
Headway.WebApi authentication is configured for the Bearer Authenticate and Challenge scheme. JwtBearer middleware is added to validate the token based on the values of the TokenValidationParameters, ValidIssuer and ValidAudience.
builder.Services.AddAuthentication(options =>{options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;}).AddJwtBearer(options =>{var identityProvider = builder.Configuration["IdentityProvider:DefaultProvider"];options.Authority = $"https://{builder.Configuration[$"{identityProvider}:Domain"]}";options.TokenValidationParameters = new TokenValidationParameters{ValidIssuer = builder.Configuration[$"{identityProvider}:Domain"],ValidAudience = builder.Configuration[$"{identityProvider}:Audience"]};});
Blazor applications obtain a token from an Identity Provider using an authorization flow. The type of flow used depends on the Blazor hosting model.
ASP.NET Core Blazor authentication and authorization.
\
“Security scenarios differ between Blazor Server and Blazor WebAssembly apps. Because Blazor Server apps run on the server, authorization checks are able to determine:
- The UI options presented to a user (for example, which menu entries are available to a user).
- Access rules for areas of the app and components.
Blazor WebAssembly apps run on the client. Authorization is only used to determine which UI options to show. Since client-side checks can be modified or bypassed by a user, a Blazor WebAssembly app can’t enforce authorization access rules. “
Blazor Server uses Authorization Code Flow in which a Client Secret is passed in the exchange. It can do this because it is a ‘regular web application’ where the source code and Client Secret is securely stored server-side and not publicly exposed.
Blazor WebAssembly uses Authorization Clode Flow with Proof of Key for Code Exchange (PKCE), which introduces a secret created by the calling application that can be verified by the authorization server. The secret is called the Code Verifier. It must do this because the entire source is stored in the browser so it cannot use a Client Secret because it is not secure.
The key difference between Blazor Server using the Authorization Code Flow and Blazor WebAssembly using the Authorization Clode Flow with Proof of Key for Code Exchange (PKCE), is Blazor Server can use a
Client Secretin the exchange because it can be securely stored on the server. Blazor WebAssembly on the other hand cannot securely store aClient Secretso it has to create acode_verifierand then generate acode_challengefrom it, which can be used in the exchange instead.
Authorization Code Flow steps:
/authorize endpoint).authorization code, which can only be used once.authorization code along with the applications Client ID and Client Secret to the authorization server (/oauth/token endpoint).authorization code, Client ID and Client Secret.ID Token and Access Token (and optionally, a Refresh Token) .Access Token contains user claims.Access Token containing user claims to the authorization header of a HttpClient request in the form of a Bearer token.Authorization Clode Flow with Proof of Key for Code Exchange (PKCE) steps:
\
The PKCE Authorization Code Flow builds on the standard Authentication Code Flow so it has very similar steps.
code_verifier and then generates a code_challenge from it./authorize endpoint) along with the code_challenge.code_challenge and then redirects the user back to the application with an authorization code, which can only be used once.authorization code along with the code_verifier (created in step 2.) to the authorization server (/oauth/token endpoint).code_challenge and code_verifier.ID Token and Access Token (and optionally, a Refresh Token). The Access Token contains user claims.Access Token containing user claims to the authorization header of a HttpClient request in the form of a Bearer token.To access resources via the Headway.WebApi the authentication server must issue a token to the user containing a RoleClaim called headwayuser and the users email. The application can then access further information about the user from the Headway.WebApi to determine what the user is authorised to do e.g. Headway.WebApi will return the menu items to build up the navigation panel. If a user does not have permission to access a menu item then Headway.WebApi simply wont return it.
Headway currently supports authentication from two identity providers IdentityServer4 and Auth0. During development you can toggle between them by setting IdentityProvider:DefaultProvider in the appsettings.json files for Headway.BlazorServerApp, Headway.BlazorWebassemblyApp and Headway.WebApi e.g.
"IdentityProvider": {"DefaultProvider": "Auth0"},
NOTE: if implementing
Auth0you will need to create aAuth Pipeline Ruleto return the email and role as a claim.
function (user, context, callback) {const accessTokenClaims = context.accessToken || {};const idTokenClaims = context.idToken || {};const assignedRoles = (context.authorization || {}).roles;accessTokenClaims['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] = user.email;accessTokenClaims['http://schemas.microsoft.com/ws/2008/06/identity/claims/role'] = assignedRoles;idTokenClaims['http://schemas.microsoft.com/ws/2008/06/identity/claims/role'] = assignedRoles;return callback(null, user, context);}
headwayuser role claim and controllers are embelished with the [Authorize(Roles="headwayuser")] attribute.email claim to confirm the user has the relevant Headway role or permission required to access to resource being requested.When using Entity Framework Core, models inheriting from ModelBase will automatically get properties for tracking instance creation and modification. Furthermore, an audit of changes will be logged to the Audits table.
public abstract class ModelBase{public DateTime? CreatedDate { get; set; }public string CreatedBy { get; set; }public DateTime? ModifiedDate { get; set; }public string ModifiedBy { get; set; }}
To log changes ApplicationDbContext overrides DbContext.SaveChanges and gets the changes from DbContext.ChangeTracker.
Capturing the user is done by calling ApplicationDbContext.SetUser(user). This is currently set in RepositoryBase where it is called from ApiControllerBase which gets the user claim from to authorizing the user.
Headway.WebApi uses Serilog for logging and is configured to write logs to the Log table in the database using Serilog.Sinks.MSSqlServer.
The client can send a log entry request to the Headway.WebApi e.g.:
try{var x = 1 / zero;}catch (Exception ex){var log = new Log { Level = Core.Enums.LogLevel.Error, Message = ex.Message };await Mediator.Send(new LogRequest(log)).ConfigureAwait(false);}
Logging is also available to api request classes inheriting LogApiRequest and can be called as follows:
var log = new Log { Level = Core.Enums.LogLevel.Information, Message = "Log this entry..." };await LogAsync(log).ConfigureAwait(false);
In the Serilog config specify a custom column to be added to the Log table to capture the user with each entry. To automatically log EF Core SQL queries to the logs, add the override "Microsoft.EntityFrameworkCore.Database.Command": "Information".
"Serilog": {"Using": [ "Serilog.Sinks.MSSqlServer" ],"MinimumLevel": {"Default": "Information","Override": {"Microsoft": "Error","Microsoft.EntityFrameworkCore.Database.Command": "Information"}},"WriteTo": [{"Name": "MSSqlServer","Args": {"connectionString": "Data Source=(localdb)\\mssqllocaldb;Database=Headway;Integrated Security=true","tableName": "Logs","autoCreateSqlTable": true,"columnOptionsSection": {"customColumns": [{"ColumnName": "User","DataType": "nvarchar","DataLength": 100}]}}}]},
More details on enriching Serilog log entries with custom properties can be found here. For Serilog enrichment to work loggerConfiguration.Enrich.FromLogContext() is called when configuring logging in Program.cs.
builder.WebHost.UseSerilog((hostingContext, loggerConfiguration) =>loggerConfiguration.ReadFrom.Configuration(hostingContext.Configuration).Enrich.FromLogContext());
Middleware is also added in Program.cs to get the user from the httpContext and push it onto the logging context for each request. The middleware must be added AFTER app.UseAuthentication(); so the user claims is available in the httpContext.
app.UseAuthentication();app.Use(async (httpContext, next) =>{var identity = (ClaimsIdentity)httpContext.User.Identity;var claim = identity.FindFirst(ClaimTypes.Email);var user = claim.Value;LogContext.PushProperty("User", user);await next.Invoke();});
The following UML diagram shows the ClaimModules API obtaining an authenticated users permissions which restrict the modules, categories and menu items available to the user in the Navigation Menu:
Headway documents use Blazored.FluentValidation where the <FluentValidationValidator ></FluentValidationValidator> is placed inside the <EditForm> e.g.
<EditForm EditContext="CurrentEditContext"><FluentValidationValidator ></FluentValidationValidator>
NOTE:
Blazored.FluentValidation is used for client side validation only while DataAnnotation and Fluent API is used for server side validation with Entity Framework.
\
\
For additional reading see Data Annotations Attributes and Fluent API Configurations in EF 6 and and EF Core.
The source for a standard dropdown is IEnumerable<OptionItem> and the selected item is bound to @bind-Value="SelectedItem".
Fields can be linked to each other so at runtime the value of one can be dependent on the value of another. For example, in a scenario where one field is Country and the other is City, and both are rendered as dropdown lists. The dropdown list for Country is initially populated while the dropdown list for “City” remains empty. Only once a country has been selected will the dropdown list for City be populated, with a list of cities belonging to the selected country.
LinkedSource key/value pair:Name=LinkedSource;VALUE=[LINKED FIELD NAME]LinkedSource property.It is possible to link two DynamicFields in different DynamicModels. This is done using PropagateFields key/value pair:
\
e.g. Name=PropagateFields;VALUE=[COMMA SEPARATED LINKED FIELD NAMES]
\
Consider the example we have Config.cs and ConfigItem.cs where ConfigItem.PropertyName is dependent on the value of Config.Model.
\
\Config.Model is rendered as a dropdown containing a list of classes with the [DynamicModel] attribute. ConfigItem.PropertyName is rendered as a dropdown containing a list of properties belonging to the class selected in Config.Model.
[DynamicModel]public class DemoModel{// code omitted for brevitypublic string Model { get; set; }public List<DemoModelItem> DemoModelItems { get; set; }// code omitted for brevity}[DynamicModel]public class DemoModelItem{// code omitted for brevitypublic string PropertyName { get; set; }// code omitted for brevity}
To map the linked source DemoModel.Model to target DemoModelItem.PropertyName:
\
DemoModel‘s ConfigItem for DemoModelItems, it’s ConfigItem.ComponentArgs property will contain a PropagateFields key/value pair:Name=PropagateFields;VALUE=ModelDemoModelItem‘s ConfigItem for PropertyName, it’s ConfigItem.ComponentArgs property will contain a LinkedSource key/value pair:Name=LinkedSource;VALUE=ModelDemoModel.Model will be propagated in ComponentArgHelper.AddDynamicArgs(), where the propagated args will be passed into the DemoModel.DemoModelItems‘s component as a DynamicArg whose value is the source field DemoModel.Model. The component for DemoModel.DemoModelItems inherit from DynamicComponentBase, which will map the linked fields together so the target references the source field via it’s LinkedSource property.Data access is abstracted behind interfaces. Headway.Repository provides concrete implementation for the data access layer interfaces. it currently supports MS SQL Server and SQLite, however this can be extended to any data store supported by EntityFramework Core.
Headway.Repository is not limited to EntityFramework Core and can be replaced with a completely different data access implementation.
Add the connection string to appsettings.json of Headway.WebApi.
Note Headway will know whether you are pointing to SQLite or a MS SQL Server database based on the connection string. This can be extended in DesignTimeDbContextFactory.cs to use other databases if required.
"ConnectionStrings": {/* SQLite*//*"DefaultConnection": "Data Source=..\\..\\db\\Headway.db;"*//* MS SQL Server*/"DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=Headway;Trusted_Connection=True;"}`
Create the database and schema using EF Core migrations in Headway.MigrationsSqlServer or MigrationsSqlite, depending on which database you choose. If you are using Visual Studio in the Developer PowerShell navigate to Headway.WebApi folder and run the following:
The following incredibly useful UML diagrams have been provided by @VR-Architect.
wwwroot\css folder in the Blazor project and click Add then Client-Side Library.... Search for font-awesome and install it.@import url('font-awesome/css/all.min.css'); at the top of site.css.@import url('font-awesome/css/all.min.css'); to app.css didn’t work. Instead add <link href="css/font-awesome/css/all.min.css" rel="stylesheet" /> to index.html.Migrations are kept in separate projects from the ApplicationDbContext.
The ApplicationDbContext is in the Headway.Repository library, which is referenced by Headway.WebApi. When running migrations from Headway.WebApi, the migrations are output to either Headway.MigrationsSqlite or Headway.MigrationsSqlServer, depending on which connection string is used in Headway.WebApi‘s appsettings.json. For this to work, a DesignTimeDbContextFactory class must be created in Headway.Repository. This allows migrations to be created for a DbContext that is in a project other than the startup project Headway.WebApi. DesignTimeDbContextFactory specifies which project the migration output should target based on the connection string in Headway.WebApi‘s appsettings.json.
public class DesignTimeDbContextFactory : IDesignTimeDbContextFactory<ApplicationDbContext>{public ApplicationDbContext CreateDbContext(string[] args){IConfigurationRoot configuration= new ConfigurationBuilder().SetBasePath(Directory.GetCurrentDirectory()).AddJsonFile(@Directory.GetCurrentDirectory() + "/../Headway.WebApi/appsettings.json").Build();var builder = new DbContextOptionsBuilder<ApplicationDbContext>();var connectionString = configuration.GetConnectionString("DefaultConnection");if(connectionString.Contains("Headway.db")){builder.UseSqlite(connectionString, x => x.MigrationsAssembly("Headway.MigrationsSqlite"));}else{builder.UseSqlServer(connectionString, x => x.MigrationsAssembly("Headway.MigrationsSqlServer"));}return new ApplicationDbContext(builder.Options);}}
Headway.WebApi‘s Startup.cs should also specify which project the migration output should target base on the connection string.
services.AddDbContext<ApplicationDbContext>(options =>{if (Configuration.GetConnectionString("DefaultConnection").Contains("Headway.db")){options.UseSqlite(Configuration.GetConnectionString("DefaultConnection"),x => x.MigrationsAssembly("Headway.MigrationsSqlite"));}else{options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection"),x => x.MigrationsAssembly("Headway.MigrationsSqlServer"));}});
In the Developer PowerShell window navigate to the Headway.WebApi project and manage migrations by running the following command:
Add a new migration:
\
\dotnet ef migrations add UpdateHeadway --project ..\..\Utilities\Headway.MigrationsSqlServer
Update the database with the latest migrations. It will also create the database if it hasn’t already been created:
\
\dotnet ef database update --project ..\..\Utilities\Headway.MigrationsSqlServer
Remove the latest migration:
\
\dotnet ef migrations remove --project ..\..\Utilities\Headway.MigrationsSqlServer
Supporting notes:
Newtonsoft.Json (Json.NET) has been removed from the ASP.NET Core shared framework. The default JSON serializer for ASP.NET Core is now System.Text.Json, which is new in .NET Core 3.0.
Entity Framework requires the Include() method to specify related entities to include in the query results. An example is GetUserAsync in AuthorisationRepository.
public async Task<User> GetUserAsync(string claim, int userId){var user = await applicationDbContext.Users.Include(u => u.Permissions).FirstOrDefaultAsync(u => u.UserId.Equals(userId)).ConfigureAwait(false);return user;}
The query results will now contain a circular reference, where the parent references the child which references parent and so on. In order for System.Text.Json to handle de-serialising objects contanining circular references we have to set JsonSerializerOptions.ReferenceHandler to IgnoreCycle in the Headway.WebApi‘s Startup class. If we don’t explicitly specify that circular references should be ignored Headway.WebApi will return HTTP Status 500 Internal Server Error.
services.AddControllers().AddJsonOptions(options =>options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles);
The default JSON serializer for ASP.NET Core is now System.Text.Json. However, System.Text.Json is new and might currently be missing features supported by Newtonsoft.Json (Json.NET).
\
I reported a bug in System.Text.Json where duplicate values are nulled out when setting JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles.
How to specify ASP.NET Core use Newtonsoft.Json (Json.NET) as the JSON serializer install Microsoft.AspNetCore.Mvc.NewtonsoftJson and the following to the Startup of Headway.WebApi:
\
Note: I had to do this after noticing System.Text.Json nulled out duplicate string values after setting ReferenceHandler.IgnoreCycles.
services.AddControllers().AddNewtonsoftJson(options =>options.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore);