Bulk Load admin

What is bulk load and why was it created

The AuthP library contains a way to load Roles, Tenants, and AuthP's Users on startup, as long as there AREN'T any Roles, Tenants, and AuthP's Users are already in the AuthP's database.

The Bulk Load feature (and the database seeding) were created so that a developer can run an example and it will look like a fully production application, that is it has example data and users such that you can log in and try out its features.

Bulk Load is NOT designed for you to setup your production application, apart one useful feature on first deploy, which is shown below.

How to set up a super user when deploying a new application

The one problem that Bulk Load can help you is when a new application is deployed it to production for the first time. In this case the database is empty so there isn't any users, which means you so to can’t log in to add users – this is a catch-22 problem. AuthP's solution is Bulk Load plus a special permission that allows a user to access to ALL the features that are protected by the HasPermission attribute / method.

The steps below show how to add a user, referred to as Super Admin user, that can be used to set up the the initial Roles, Admin Users etc. Typically the Super Admin user only used for the initial setup or in extreme situations such as someone deleting an admin role.

1. Setup the AssessAll member in your Permissions

The AuthP's Permission with the value of ushort.MaxValue is designed to give access to every feature. This member normally named as AssessAll, but its value is the important. Here is the end of a Permissions enum only showing the AssessAll member.

public enum Example1Permissions : ushort
{
    // ... other enum members left out


    //Useful for setting up an SuperAdmin user
    //Setting the AutoGenerateFilter to true in the display makes any Role with this enum member 
    //is hidden from tenant users.
    [Display(GroupName = "SuperAdmin", Name = "AccessAll", 
        Description = "This allows the user to access every feature", AutoGenerateFilter = true)]
    AccessAll = ushort.MaxValue,
}

2. Create the bulk load data

You need to create the bulk load data for adding a SuperUser.

public static class SuperAdminBulkLoadData
{
    public static readonly List<BulkLoadRolesDto> RolesDefinition = new()
    {
        new("SuperAdmin", "Super admin - only use for setup", "AccessAll"),
    };

    public static readonly List<BulkLoadUserWithRolesTenant> UsersWithRolesDefinition = new()
    {
        new ( "Super@g1.com", "Super Admin", "SuperAdmin"),
    };
}

Note that the email in the UsersWithRolesDefinition is the email of the user you want to be the SuperAdmin user.

3. Add the bulk load to the registering of the AuthP library

You need to use the AddRolesPermissionsIfEmpty and AddAuthUsersIfEmpty extensions methods to the AuthP's registration, with the data in step 2.

services.RegisterAuthPermissions<Example1Permissions>()
    .UsingEfCoreSqlServer(connectionString)
    .AddRolesPermissionsIfEmpty(AppAuthSetupData.RolesDefinition)
    .AddAuthUsersIfEmpty(AppAuthSetupData.UsersWithRolesDefinition)
    //... rest of the registration left out

4. You need to link the AuthP SuperUser to the authentication provider

You need to give the AuthP bulk load a way to get the userId of the user in the authentication provider. This depends on the type of authentication provider you are using. Here are the options.

4.a. Using an external authentication provider like Azure Active Directory (Azure AD), Google, etc.

In this case you can copy the userId from that source and add it to the bulk load setup data, for instance in Example5 which uses Azure AD and by inspecting the Azure AD via the Azure Portal I could get the email and userId of user. The code below shows how I updated the Bulk Load data to add the userId.

public static readonly List<BulkLoadUserWithRolesTenant> UsersWithRolesDefinition = new ()
{
    new ("Admin@authpermissions.onmicrosoft.com", "Admin User", "Admin Role",
        "a5a10d86-27cf-4fff-8bdd-ca6ee9c93f27"), //This optional parameter holds the user's UserId
};

4.b. Using an internal authentication provider like individual users account

In the case that you are using an authentication provider that uses a local database, then you need to add the user to that database, and get the UserId created by the authentication provider. To do this you need to:

1. Add the new user to the authentication provider
2. Implement a class that matches the IFindUserInfoService which finds the UserId from the email (or name)
3. Register your IFindUserInfoService class using the RegisterFindUserInfoService extension method

This process is needed with ASP.NET Core individual users account provider and AuthP has created classes to handle this. The code below shows the registration of the AuthP library, when using individual users account authentication provider.

services.RegisterAuthPermissions<Example3Permissions>(options =>
    {
        options.TenantType = TenantTypes.SingleLevel;
        options.AppConnectionString = connectionString;
        options.PathToFolderToLock = _env.WebRootPath;
    })
    .UsingEfCoreSqlServer(connectionString)
    .IndividualAccountsAuthentication()
    .AddRolesPermissionsIfEmpty(AppAuthSetupData.RolesDefinition)
    .AddAuthUsersIfEmpty(AppAuthSetupData.UsersWithRolesDefinition) 
    .RegisterFindUserInfoService<IndividualAccountUserLookup>() //Register individual users account IFindUserInfoService class
    .AddSuperUserToIndividualAccounts() // Adds a user using data in the appsettings.json file
    .SetupAspNetCoreAndDatabase(options =>
    {
        //Migrate/create the individual users account database
        options.RegisterServiceToRunInJob<StartupServiceMigrateAnyDbContext<ApplicationDbContext>>();
    });

NOTE: You MUST use the SetupAspNetCoreAndDatabase when using this bulk load approach, as it has to update the database before the application starts. If you want to migrate / seed in your CI/CD pipeline, then you should build a application that will execute the code in the BulkLoadOnStartup class after the various databases have been created / migrated.

Additional resources

• Permissions explained