Secure External APIs with API Keys - and Keep the Villains at Bay

What Are API Keys?

The first step in implementing API Keys is to design the data structure and build out the CRUD for the UI.  Well, the CRD, anyway, updating API Keys doesn't make much sense.

Conveniently enough ASP.Net Boilerplate already provides a Users entity that ostensibly offers a superset of everything required.  ASP.Net Boilerplate Users can have multiple Roles and each of those Roles can have multiple Permissions.  

 

Developers can then restrict access to methods and classes via the AbpAuthorize("SomePermission") attribute, which takes a Permission as a parameter.  When an end user makes a request to an endpoint ABP determines the user from a bearer token in the request header, figures out their roles, and figures out which permissions belong to those roles.  If one of those permissions matches the requirement in the AbpAuthorize() attribute, the call is allowed through.

API Keys should be similar.  As far as fields they'll have an "API Key" instead of "Username", and a "Secret" instead of a "Password".  Unlike users they'll likely only need one permission for decorating the external API instead of many.  Thus, they'll have just a single Role to help link the single permission to the API Keys.

Therefore, implementing this should be as simple as having ApiKey inherit from User and pretend that Username is ApiKey and Password is Secret.

Crudy Keys

A1. Add Entity

The ApiKey contains zero additional columns:

publicclassApiKey:User{}

A2. Add to DB Context

A3. Add Migration

The addition of inheritance to the User entity means Entity Framework will add a discriminator column because Entity Framework Core prefers the  Table per Hierarchy inheritance strategy. It will take care of setting that discriminator column for all future data, but it won't for older data.  To address that add either a second migration or add this to the first migration:

migrationBuilder.Sql("UPDATE AbpUsers SET Discriminator = 'User'");

A4. Update Database

A5. Add DTO

The only field we want to expose when viewing API Keys is the key (username).  We want a custom mapping from Username to ApiKey when AutoMapper converts it.  Therefore we want a DTO like this:

publicclassApiKeyDto:EntityDto<long>{[Required][StringLength(AbpUserBase.MaxUserNameLength)]publicstring ApiKey {get;set;}}

And a mapping profile like this:

publicclassApiKeyDtoProfile:Profile{publicApiKeyDtoProfile(){CreateMap<ApiKey,ApiKeyDto>().ForMember(i => i.ApiKey, opt => opt.MapFrom(i => i.UserName));}}

A6. Register a Permission

context.CreatePermission(PermissionNames.Pages_ApiKeys, L("ApiKeys"), multiTenancySides: MultiTenancySides.Host);

A7. AppService

The AppService has three things of note.  

First, the Create DTO is different from the View DTO, because users send in a Secret but never get one back.  We can solve that by making a CreateApiKeyDto that inherits from the view DTO and customizes the final generic parameter

[AutoMapFrom(typeof(ApiKey))]publicclassCreateApiKeyDto:ApiKeyDto{[Required][StringLength(AbpUserBase.MaxPlainPasswordLength)]publicstring Secret {get;set;}}[AbpAuthorize(PermissionNames.Pages_ApiKeys)]publicclassApiKeysAppService:AsyncCrudAppService<ApiKey, ApiKeyDto,long, PagedAndSortedResultRequestDto, CreateApiKeyDto>{...

Second, we need a custom method to retrieve unique API Keys and Secrets.  A quick naive version would look like this:

publicCreateApiKeyDtoMakeApiKey(){returnnewCreateApiKeyDto{
        ApiKey = User.CreateRandomPassword(),
        Secret = User.CreateRandomPassword()};}

Finally, when we create ApiKeys we need to put in some fake value in the various required user fields, but most importantly we need to hash the secret with an IPasswordHasher<User>.

publicoverrideasync Task<ApiKeyDto>CreateAsync(CreateApiKeyDto input){var fakeUniqueEmail = input.ApiKey +"@noreply.com";var apiKey =newApiKey{
        UserName = input.ApiKey,
        EmailAddress = fakeUniqueEmail,
        Name ="API Key",
        Surname ="API Key",
        IsEmailConfirmed =true,
        NormalizedEmailAddress = fakeUniqueEmail
    };

    apiKey.Password = _passwordHasher.HashPassword(apiKey, input.Secret);await _userManager.CreateAsync(apiKey);var apiRole =await _roleService.EnsureApiRole();await _userManager.SetRolesAsync(apiKey,new[]{ apiRole.Name });await CurrentUnitOfWork.SaveChangesAsync();returnnewApiKeyDto{
        Id = apiKey.Id,
        ApiKey = apiKey.UserName
    };}

That call to _roleService.EnsureApiRole() basically just creates a Role and a Permission that we can decorate our external API calls with.

/// <summary>/// ApiKeys should have the API permission.  Users/ApiKeys must get permissions by association with a Role./// This code finds and returns a role called API or if it doesn't exist it creates and returns a role/// called API that has the API permission.  This code is called when an API Role is created.  Thus, the API/// role is created the 1st time a user creates an API Key for a tenant./// </summary>publicasync Task<Role>EnsureApiRole(){var apiRole =await _roleRepository.GetAll().FirstOrDefaultAsync(i => i.Name == RoleNames.Api);if(apiRole !=null)return apiRole;var permissions = _permissionManager.GetAllPermissions().Where(i => i.Name == PermissionNames.Api);
    apiRole =newRole{
        TenantId = CurrentUnitOfWork.GetTenantId(),
        Name = RoleNames.Api,
        DisplayName ="API"};await _roleManager.CreateAsync(apiRole);await _roleManager.SetGrantedPermissionsAsync(apiRole, permissions);return apiRole;}

A8. Run App, See Swagger Update, Rejoice

Great, the API is finished:

publicngOnInit(){this.apiKey =newCreateApiKeyDto();this.apiKeyServiceProxy
        .generateApiKey().first().subscribe(apiKey =>(this.apiKey = apiKey));}

<mat-form-fieldclass="col-sm-12"><inputmatInputtype="text"name="Key"[(ngModel)]="apiKey.apiKey"requiredplaceholder="Key"readonly#keyInput/><buttonmat-icon-buttonmatSuffixtype="button"(click)="copyInputToClipboard(keyInput)"><mat-iconmatTooltip="Copy to clipboard">content_copy</mat-icon></button></mat-form-field>

publiccopyInputToClipboard(inputElement: HTMLInputElement){
    inputElement.select();
    document.execCommand('copy');
    inputElement.setSelectionRange(0,0);}