Startup code

Like all ASP.NET Core libraries the AuthP library has to be registered as a service. Also, yhe AuthP library follows the ASP.NET Core of format of configuring itself with extension methods, and providing configuration points.

Here is a simple example of what registering the AuthP library would look like, but there are lots of different extension methods and configurations.

services.RegisterAuthPermissions<Example4Permissions>()
    .IndividualAccountsAuthentication()
    .UsingEfCoreSqlServer(Configuration.GetConnectionString("DefaultConnection")) 
    .RegisterAuthenticationProviderReader<SyncIndividualAccountUsers>()
    .IndividualAccountsAddSuperUser()
    .SetupAspNetCorePart();

A list of the AuthP's extensions and what you can use

The AuthP library has lots of options and the table below shows the various groups and when and where they should go.

Group	Method	Needed?
Configure	RegisterAuthPermissions<TEnum>	Required, first
Authentication	IndividualAccountsAuthentication AzureAdAuthentication ManualSetupOfAuthentication	Required, second
Database	UsingEfCoreSqlServer UsingInMemoryDatabase	One required
Bulk Load	AddTenantsIfEmpty AddRolesPermissionsIfEmpty AddAuthUsersIfEmpty RegisterFindUserInfoService<TLookup>	Optional
User Admin	RegisterAuthenticationProviderReader<TSync>	Required for admin
SuperUser	AddSuperUserToIndividualAccounts	Optional
Finalize	SetupAspNetCorePart SetupAspNetCoreAndDatabase SetupForUnitTestingAsync	One required, last

The following sections explains each Group in more detail.

Configure

You must start with the RegisterAuthPermissions<TEnum> method. This starts the registration of AuthP. There are two parts to this configuration method.

1. It allows you to tell AuthP what enum contains your Permissions.
   NOTE: This method will throw an exception you Permissions the enum has the : ushort applied to it.
2. You can set the AuthP's options. At the moment there are
   1. Setting up AuthP's JWT Token, and optional JWT refresh value (see JWT Token configuration).
   2. Setting up AuthP's multi-tenant feature (see Multi tenant configuration for the options).

Authentication

This tells AuthP what authentication provider(s) you are using. For the Individual User Accounts and Azure Active Directory authentication providers AuthP has built-in versions that adds the AuthP claims to the cookie. For other authentication providers you need to write your own code to add the AuthP claims to the cookie.

See Setup Authentication for more information.

Database

You need to select a database type where AuthP can store its information. At the moment there are only two options:

1. UsingEfCoreSqlServer

This method takes in a connection string to a SQL Server database where the AuthP entities are stored.

NOTE: The AuthP code is designed to be share a database that other parts of the application uses, e.g. your own EF Core database, the Individual Account database, and so on. This works because the AuthP's database has its own named EF Core migration history table so that it can be migrated without effecting other parts of the database. This reduces the number databases your application needs.

2. UsingInMemoryDatabase

This creates a SQLite in-memory database. On startup the database will be created, and when the application closed the database will be disposed.

An in-memory database is there mainly for unit testing your application. The Bulk load methods are also useful for seeding the database at the start of a unit test.

Bulk Load

The bulk load methods allow you to setup Role, Multi-tenants, and AuthUsers, but only if the database has no Roles, Multi-tenants or AuthUsers respectively. This provides a quick way to load AuthP settings on startup. That's mainly when unit testing, but it is be helpful when adding AuthP to an existing application.

The Bulk Load features are also available as an admin service for cases where an admin user wants to load a large number of Roles, Multi-tenants or AuthUsers.

There are three Bulk Load extension methods which will update the AuthP's database on application startup. They are:

• AddTenantsIfEmpty: Adds AuthP multi-tenant Tenants if no Tenants already exists.
• AddRolesPermissionsIfEmpty : Adds AuthP Roles if no Roles already exists.
• AddAuthUsersIfEmpty: Adds AuthP's Users if no AuthUsers already exist.

The other method is the RegisterFindUserInfoService<TLookup>, which allows you to provide class which implements the IFindUserInfoService interface. Your class is registered to the service provider and is used by the Bulk Load (setup or admin services) to obtain the UserId of a authentication provider user via either the user's Email address, or their UserName.

The code below provides an example of how bulk load features can be added to the registering of AuthP in ASP.NET Core's ConfigureServices method in the Startup class. The code was taken from Example4's startup class, which has a good example of using all three startup bulk load extension methods.

services.RegisterAuthPermissions<Example4Permissions>()
    .AddRolesPermissionsIfEmpty(Example4AppAuthSetupData.BulkLoadRolesWithPermissions)
    .AddTenantsIfEmpty(Example4AppAuthSetupData.BulkHierarchicalTenants)
    .AddAuthUsersIfEmpty(Example4AppAuthSetupData.UsersRolesDefinition)
    .RegisterFindUserInfoService<IndividualAccountUserLookup>()
    // ... other AuthP configuration methods left out

The table below provides states the basic format of the bulk loading with link to the service definitions which contains comments on the format. You can also see an example of these formats in the Example4AppAuthSetupData class.

What	bulk load type	service
Roles	string containing lines	IBulkLoadRolesService
Tenants	string containing lines	IBulkLoadTenantsService
Users	List<DefineUserWithRolesTenant>	IBulkLoadUsersService

Note that these bulk load methods only add Roles, Tenants and AuthUsers when there are no existing entries in the AuthP database.

User Admin

The authentication provider's users are the master list of users and the AuthP's AuthUsers need to be in synced to authentication provider's users. The RegisterAuthenticationProviderReader<TSync> extension method allows you to provide a service (that implements the ISyncAuthenticationUsers interface ) that AuthP can use to 'sync' its AuthUsers with the authentication provider's users.

The AuthP library contains a ISyncAuthenticationUsers for the Individual Account authentication provider, and its called SyncIndividualAccountUsers, but it is also shown below.

public class SyncIndividualAccountUsers : ISyncAuthenticationUsers
{
    private readonly UserManager<IdentityUser> _userManager;

    public SyncIndividualAccountUsers(UserManager<IdentityUser> userManager)
    {
        _userManager = userManager;
    }

    /// <summary>
    /// This returns the userId, email and UserName of all the users
    /// </summary>
    /// <returns>collection of SyncAuthenticationUser</returns>
    public async Task<IEnumerable<SyncAuthenticationUser>> GetAllActiveUserInfoAsync()
    {
        return await _userManager.Users
            .Select(x => new SyncAuthenticationUser(x.Id, x.Email, x.UserName)).ToListAsync();
    }
}

If you are using a different authentication provider you need to create a service that implements the ISyncAuthenticationUsers and register the service using RegisterAuthenticationProviderReader<TSync> extension method.

See AuthUser's admin sync service for more details on how this works.

SuperUser

If you are using the Individual Accounts authentication provider, then when the Individual Accounts is created it will be empty of any users. That can be a problem when you have deployed the application to a new server, as no one is registered to access the admin features to add more users. The AddSuperUserToIndividualAccounts will create a new user in the Individual Accounts database on startup using information in your appsettings.json file shown below:

  "SuperAdmin":
  {
    "Email": "[email protected]",
    "Password": "[email protected]"
  }

This, combined with the Bulk Load extension methods you can create a AuthUser that has the AccessAll Permission member (seeSetting up your Permissions - access for more info). This then allows you to use this SuperUser to set up normal admin users.

NOTE: There is a small security issue in that if someone changes the SuperUser settings in the appsettings.json file, then you would get an extra SuperUser when the application is next deployed.

Finalize

The final extension method in the AuthP setup register all the services and, optionally, run some migration/seeding on startup of the ASP.NET Core. There are three options to chose from:

1. SetupAspNetCoreAndDatabase extension method

This method will apply a migration to the AuthP database on startup, and then seeds the AuthP database with any Bulk Load. To handle the situation where your application is running multiple instances it makes sure any migrations etc. are run inside a lock on a global resource, such as a database. That way it can ensure that the various accesses to the database aren't run at the same time.

The SetupAspNetCoreAndDatabase has a number of parts to it and it has its own SetupAspNetCoreAndDatabase page. Please go to that page for more details on how to use the SetupAspNetCoreAndDatabase extension method.

2. SetupAspNetCorePart extension method

This assumes that any databases has already been created/migrated, especially the AuthP's DbContext. Note: this approach doesn't support Bulk loading.

3. SetupForUnitTestingAsync extension method

This is used for unit testing - see the Unit Test your AuthP app page for more on how to unit test applications that use AuthP.