Setup Authentication

This document tells you how to register which authentication provider (or providers) where AuthP should add new claims when the a user logs in. Currently there are two build-in adapters in AuthP:

• IndividualAccountsAuthentication, which handles the Individual User Accounts authentication provider
• AzureAdAuthentication, which handles the Azure Active Directory (shortened to Azure AD)

There is also a ManualSetupOfAuthentication extension method which says you have build your own adapter to add the AuthP's claims to the cookie. I cover how to build you own adapter at the end of this document.

NOTE: AuthP's JWT Token approach works with ANY authentication provider as long as it creates a NameIdentifier claim holding the UserId. However you still need to register the your authentication provider because AuthP will throw an error if a authentication provider isn't registered. You can use the ManualSetupOfAuthentication extension method to say you are handling this yourself.

The next sections define AuthP's built-in methods for different authentication provider, ending on how you would build an adapter to an OpenID / OAuth2 authentication provider.

The three parts of linking AuthP

There are up to three parts to linking to an authentication provider as shown below. Each description of an adapter includes information on the relevant parts.

1. REQUIRED: Registering your authentication provider you are using with AuthP. Built-in adapters adds the AuthP's claims into the authentication cookie.
2. OPTIONAL: A way to sync AuthP's list of users against the authentication provider's list of users. This is explained in AuthUser admin service > Synchronizing the AuthUsers.
3. OPTIONAL: Service that implements the IFindUserInfoService interface - only used for Individual User Accounts when you are using Bulk Loading.

Individual Users Account authentication provider

1. Registering the Individual User Accounts authentication provider

You register that you are using Individual User Accounts authentication provider, by adding the IndividualAccountsAuthentication extension method to the registering of the AuthP service.

services.RegisterAuthPermissions<Example4Permissions>()
    .IndividualAccountsAuthentication() 
    //... other methods left out

2. Sync Individual Accounts users with AuthP's users.

The Individual Accounts authentication provider allows new users to register with the application. Newly registered users won't be in the AuthP's list of users, but AuthP contains a class called SyncIndividualAccountUsers which can be used in your AuthP admin pages - see this part of the docs about this.

You register using the RegisterAuthenticationProviderReader<SyncIndividualAccountUsers>() method / type.

NOTE: If you customize the IdentityUser, then you can't use the built-in SyncIndividualAccountUsers, but you need to create a class that inherits the ISyncAuthenticationUsers and uses the UserManager<CustomIdentityUser> - see section later.

3. Finding the UserId from the authentication provider when you are using Bulk Loading

This is useful for the Individual User Accounts authentication provider when you are using Bulk Loading. That's because you need to register at least one admin user so that you can log in when deploying the application for the first time, otherwise you don't have a way to access the admin code in your app.

AuthP contains a class called IndividualAccountUserLookup which provides the Email-to-UserId lookup on the Individual Account users. This allows you to add users to the Individual Accounts database and then read their UserId / Email so that you can link the Individual Accounts database users with the AuthP users being loaded via Bulk loading.

You register using the RegisterFindUserInfoService<IndividualAccountUserLookup>() method / type.

NOTE: If you customize the IdentityUser, then you can't use the built-in IndividualAccountUserLookup, but you need to create a class that inherits the IFindUserInfoService and uses the UserManager<CustomIdentityUser>.

NOTE: How to handle Individual Account with a custom IdentityUser

You can customize the IdentityUser used in the Individual User Accounts authentication provider. If you do this you need to use the alternative registration extension methods shown below:

• REQUIRED: Use the IndividualAccountsAuthentication<TCustomIdentityUser> extension method instead of the normal IndividualAccountsAuthentication() to register the Individual User Accounts authentication provider. Where the TCustomIdentityUser class inherits IdentityUser class.
• OPTIONAL: Use AddSuperUserToIndividualAccounts<TCustomIdentityUser> extension method instead of the normal AddSuperUserToIndividualAccounts() to to add a SuperUser to the Individual Accounts database.
• OPTIONAL: The invite new user feature takes in the the IdentityUser type, which allows you to use a custom IdentityUser class.

If you want to use features such as SyncIndividualAccountUsers you also need to copy the followings classes and create a new class where every reference to UserManager<IdentityUser> is changes to UserManager<CustomIdentityUser>. They are:

• Copy SyncIndividualAccountUsers class and create a new version with CustomIdentityUser.
• Copy IndividualAccountUserLookup class and create a new version with CustomIdentityUser.

Azure Active Directory (Azure AD) authentication provider

Adding Azure AD as an authentication provider uses ASP.NET Core's OpenId pattern and AuthP provides methods to link this to AuthP.

1. Registering the Azure AD authentication provider

You register that you are using the Azure AD authentication provider, by adding the AzureAdAuthentication extension method to the registering of the AuthP service, with some settings. See code below:

services.RegisterAuthPermissions<Example4Permissions>()
    .AzureAdAuthentication(AzureAdSettings.AzureAdDefaultSettings()) 
    //... other methods left out

The AzureAdSettings class contains a set of settings to define the Azure AD claims to find the UserId, Email, and UserName, plus various settings to alter how the Azure AD authentication provider works. The AzureAdDefaultSettings method uses the normal settings for a Azure AD, has one optional property to control the Azure AD authentication provider with is the string authenticationSchemeName parameter

The authenticationSchemeName defaults to the OpenIdConnectDefaults.AuthenticationScheme value which should be the same as the string used to define that you are using the Azure AD authentication provider (see code startup code below). If you are registering multiple authentication providers, then the authenticationSchemeName parameter should be set to the same string as the Azure AD authentication provider registration.

services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(Configuration.GetSection("AzureAd"));

2. Sync Azure AD users with AuthP's users.

When new users are added, updated or removed / disabled to Azure AD you need apply these changes to the AuthP Users so that you can add the various Roles / Multi-tenant settings. As part of Example5 application I have created a class that implements the ISyncAuthenticationUsers for syncing AuthP's user from the Azure AD users. You can find the code in the Example5's AzureAdCode folder

This uses the Microsoft.Identity.Client to read all the users in the Azure AD. NOTE: This means either only a Azure AD user who has Azure AD admin privileges can use the Sync Azure AD feature, but a better solution is to add the Users.Read permission to application the Azure AD > app registration.

You register using the RegisterAuthenticationProviderReader<SyncAzureAdUsers>() method, with the SyncAzureAdUsers service found in Example5.

3. Finding the UserId from the authentication provider for Bulk Loading

This feature isn't really useful with Azure AD because you can obtain the UserId of a Azure AD user either via the Azure Portal or PowerShell.

How to create code to link AuthP to any authentication provider

If you want to use a authentication provider that the AuthP doesn't currently have a built-in version, then you can build one. In general these will be for external authentication providers like Google, Twitter etc. The good news is that Google, Twitter etc. follow the same pattern as AuthP's code to link Azure AD to AuthP, which can be found in the AzureAdOpenIdExtension class.

NOTE: See this section in the article called "Advanced techniques around ASP.NET Core Users and their claims" which describes the main authentication approaches, OAuth2 and OpenIdConnect, and how you can link into their login event.

1. Registering code to be called when someone logs in

The code in the AzureAdOpenIdExtension class uses ASP.NET Core's OpenID feature where you can use an event to add/alter claims that will be added to the logging-in user. Unlike Azure Ad authentication providers like Google, Twitter etc. don't allow you to scan the whole set of users (!!), so you are likely to use the approach where you automatically add any new users that log in into the AuthP users (NOTE: another approach, say for a SaaS application, is that a new user is sent to a page to ask / pay for features where you call IAuthUsersAdminService.AddNewUserAsync - see this docs for this method).

If you study the SetupOpenAzureAdOpenId method you will see it has to obtain:

• REQUIRED: UserId in NameIdentifier claim: The UserId value / claim it key to how AuthP links the logging-in user to the AuthP users so it can obtain the correct Permissions / multi-tenant DataKey. Typically the UserId is a unique string that represents the user, but doesn't break privacy rules. Most external authentication providers supply this, but you can use the email as the UserId if a UserId is missing.
• OPTIONAL: Email: This is the email for this user. This is used if you plan to add a AuthP user if the logging-in user isn't already there.
• OPTIONAL: UserName: This is the name of the user. This is used if you plan to add a AuthP user if the logging-in user isn't already there.

NOTE: When creating a new AuthP User either of the Email or UserName can be null, but both can't be null.

As you can see from the SetupOpenAzureAdOpenId that the default claims from Azure AD:

• The NameIdentifier claim didn't contain the correct UserId as shown in Azure AD. I therefore had to remove the original claim and create the the correct format. The NameIdentifier claim is key to AuthP working.
• The Name claim wasn't set, so I added that claim as ASP.NET Core shows that name when you are signed in.
• If the logging-in user is known to AuthP, then it will add the Permissions and optional DataKey claims.

NOTE: The code would have been much simpler if I didn't need to remove / replace the NameIdentifier - see this article for a simpler way.

You also tell AuthP that you are handling the authentication provider by adding the ManualSetupOfAuthentication() when registering AuthP, otherwise AuthP will error saying a authentication provider hasn't be linked.

2. Sync your external authentication provider users with AuthP's users.

It's very unlikely you want to sync to authentication providers like Google, Twitter etc. If you need to build this you follow the ISyncAuthenticationUsers interface.

3. Finding the UserId from your external authentication provider when you are using Bulk Loading

Again, I don't think you need this as you can get the UserId of the user you want to be the first Admin user and add it to the UserId parameter in DefineUserWithRolesTenant

Additional resources

• Authentication explained
• Add New User adapter
• Bulk Load admin